ispectify 5.0.0-dev34

Pure-Dart structured logging, tracing, filtering, history, observers, export, and redaction core for the ISpect toolkit.

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 your own Sentry, Crashlytics, Grafana, or backend adapter.
• Built-in redaction engine shared across the ispectify_* interceptor packages.

Install

dependencies:
  ispectify: ^5.0.0-dev34

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.

Redaction is a safety layer, not a substitute for data minimization. Prefer disabling body/header capture when payload contents are not needed, and add project-specific keys for business identifiers that only your application understands.

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.

Only disable redaction in isolated local or deterministic test environments. Exported sessions and observer events should be treated as sensitive artifacts even when redaction is enabled.

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 sanitize user input before logging it manually. See docs/SECURITY.md for the recommended data-handling policy.

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.

---