ispectify is the logging backbone of the ISpect toolkit. Pure Dart, no Flutter — usable in CLI tools, server-side Dart, and shared business-logic packages.

• Typed log entries with explicit severity levels and log-type keys.
• Filtering, in-memory history, and custom truncation.
• Trace extensions for async / sync / stream operations with timing and outcome tagging.
• Observer hooks to forward events into Sentry, Crashlytics, Grafana, or anywhere else.
• Built-in redaction engine shared across the ispectify_* interceptor packages.

Install

dependencies:
  ispectify: ^5.0.0-dev22

Quick start

import 'package:ispectify/ispectify.dart';

final logger = ISpectLogger();

logger.info('Application started');
logger.warning('Cache miss — falling back to network');
logger.error('Payment gateway returned 502', exception, stackTrace);

Custom log types:

logger.log(
  'User signed in',
  logLevel: LogLevel.info,
  type: const ISpectLogType('auth'),
);

Configuration

final logger = ISpectLogger(
  options: ISpectLoggerOptions(
    enabled: true,
    useHistory: true,
    useConsoleLogs: true,
    maxHistoryItems: 5000,
    logTruncateLength: 4000,
  ),
);

Streaming-only (no in-memory history — useful when every event is forwarded to an observer):

final logger = ISpectLogger(
  options: const ISpectLoggerOptions(useHistory: false),
);

Filter by log-type key (suppress noisy categories without changing call sites):

final logger = ISpectLogger(
  filter: ISpectFilter(logTypeKeys: {'analytics', 'route'}),
);

Filter by level (drop debug/verbose, keep info and above):

final logger = ISpectLogger(
  logger: ISpectBaseLogger(
    filter: LogLevelRangeFilter(minLevel: LogLevel.info),
  ),
);

Tracing

Trace extensions wrap work in a start/end log pair with duration, outcome, and optional result projection — so you can see one-line "did this domain action succeed?" entries in the log viewer.

final users = await logger.traceAsync<List<User>>(
  source: 'user_repository',
  operation: 'fetch_list',
  run: () => userRepository.fetchAll(),
  projectResult: (list) => {'count': list.length},
);

Also available: traceSync, traceStream. Each reports duration, exception, and stack trace on failure.

Observers

Observers receive every log event in real time — attach one per external sink:

class GrafanaObserver extends ISpectObserver {
  const GrafanaObserver();

  @override
  void onLog(ISpectLogData data) { /* ship to Loki */ }

  @override
  void onError(ISpectLogData err) { /* ship to Loki */ }

  @override
  void onException(ISpectLogData err) { /* ship to Loki */ }
}

logger.addObserver(const GrafanaObserver());

Data redaction

Sensitive data is automatically masked before it reaches logs or observers. Redaction is enabled by default — built-in rules cover auth headers, tokens, passwords, API keys, cookies, PII (SSN, passport, driver's license), financial data (credit cards, IBAN), phone numbers, and more.

Custom keys and patterns

import 'package:ispectify/ispectify.dart';

final redactor = RedactionService(
  sensitiveKeys: {
    ...defaultSensitiveKeys,
    'x-custom-secret',
    'internal_token',
  },
  sensitiveKeyPatterns: [
    RegExp(r'my_app_secret_\w+', caseSensitive: false),
  ],
  // Keys where the value is replaced entirely (not edge-masked).
  fullyMaskedKeys: {'filename'},
  placeholder: '***',
  visibleEdgeLength: 3,
  redactBinary: true,
  redactBase64: true,
);

Ignoring defaults

final redactor = RedactionService(
  // e.g., ?mobile=true is a platform flag, not a phone number.
  ignoredKeys: {'mobile', 'platform_token'},
  ignoredValues: {'<test-token>', 'public-api-key'},
);

Disabling

Each interceptor accepts enableRedaction: false on its settings object. See the per-package README for the exact settings type.

Security

Exported logs are plain-text JSON. Never write PII (emails, phone numbers, tokens) directly via logger.info(...) — rely on the redaction engine when values flow through network interceptors, and sanitise user input before logging it manually.

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.

---