ispectify_db 5.0.0-dev43

Passive database observability for ISpect with operation tracing, timings, slow-query logs, result projection, and redaction.

ispectify_db adds passive database observability to the ISpect toolkit. It traces SQL statements, ORM operations, and KV-store calls through a single dbTrace extension — with timing, row counts, slow-query detection, and redaction.

• Works with any driver: sqflite, drift, Isar, ObjectBox, shared_preferences, hive, etc. — just wrap the call.
• Redaction of argument values by configured keys.
• Slow-query threshold triggers a separate log entry so perf outliers stand out.
• Optional stack trace capture on errors, without paying the cost on the hot path.
• Pure Dart — no Flutter binding required.

Install

dependencies:
  ispectify: ^5.0.0-dev43
  ispectify_db: ^5.0.0-dev43

Quick start

Configure once at startup:

import 'package:ispectify_db/ispectify_db.dart';

ISpectDbCore.config = const ISpectDbConfig(
  sampleRate: 1.0,
  redact: true,
  attachStackOnError: true,
  slowQueryThreshold: Duration(milliseconds: 400),
);

Then wrap each storage call with dbTrace:

import 'package:sqflite/sqflite.dart';

final rows = await ISpect.logger.dbTrace<List<Map<String, Object?>>>(
  source: 'sqflite',
  operation: 'query',
  statement: 'SELECT * FROM users WHERE id = ?',
  args: [userId],
  table: 'users',
  run: () => db.rawQuery('SELECT * FROM users WHERE id = ?', [userId]),
  projectResult: (rows) => {'rows': rows.length},
);

source and operation become the grouping key in the log viewer; projectResult lets you record "just the counts" without dumping row contents.

Configuration

Field	Default	What it does
sampleRate	1.0	Fraction of calls to log (e.g. 0.1 = 10%).
redact	true	Mask sensitive keys in args and statement.
redactKeys	built-in set	Override the redaction key list.
attachStackOnError	true	Capture and log stack trace on failure.
slowQueryThreshold	null	If set, durations above the threshold are re-logged as db-slow-query.

ISpectDbCore.config = const ISpectDbConfig(
  redact: true,
  redactKeys: ['password', 'token', 'secret'],
  slowQueryThreshold: Duration(milliseconds: 250),
);

The ISpect toolkit

ISpect is a modular monorepo. Install only what your project needs — each package works independently.

Package	What it does
ispect	Flutter UI — debug panel, log viewer, navigation observer, inspector integration
ispect_layout	Visual layout inspector — sizes, constraints, decorations, compare mode, color picker
ispectify	Pure-Dart logging core — typed log entries, filtering, tracing, observers
ispectify_dio	Dio HTTP interceptor with automatic redaction
ispectify_http	http package interceptor with automatic redaction
ispectify_ws	WebSocket traffic capture with automatic redaction
ispectify_db	Database operation tracing (SQL, ORM, KV stores)
ispectify_bloc	BLoC event / state / transition observer

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines, and open issues or pull requests at the ISpect repository.

License

MIT — see LICENSE.

---