Watchers

Each unit implements one of two contracts: CrumbsWatcher (hook and event capture) or CrumbsHttpAdapter (HTTP capture). Both feed a ring buffer in CrumbsStore, which a VM Service extension serves to the CLI and the MCP tools.

Quick Reference#

crumbs:install registers ExceptionWatcher and DumpWatcher for you; a hand wiring registers them itself.

Call-site guard#

CrumbsPlugin.install() installs no mode guard of its own. The app gates the whole crumbs install at the call site, and kDebugMode and !kReleaseMode both tree-shake it from a release build:

if (!kReleaseMode) {
  CrumbsPlugin.install();
  // register additional watchers here
}

• kDebugMode is what crumbs:install writes into lib/main.dart. Debug builds carry crumbs; profile and release builds do not.
• !kReleaseMode also keeps crumbs in profile builds. Use it when you measure performance: debug frame timings do not describe a shipped app, so a frame measurement needs a profile build. Keep the guard at the call site, never inside a helper, or the call stays live in release and the tree-shake is lost.

The snippets on this page use kDebugMode; either guard works in each of them. Individual watchers need no guard of their own, except that DumpWatcher has an internal kDebugMode check (see below) and so captures nothing in a profile build unless allowInRelease is set.

Chain-preserve pattern#

A watcher that replaces a global Dart or Flutter hook saves the previous handler, calls it from the new one, and restores it on uninstall(). That is how crumbs coexists with Sentry and Bugsnag: it records the error and forwards it to whatever was registered before it. ExceptionWatcher is the reference:

// 1. Chain-preserve FlutterError.onError (sync framework errors).
_previousFlutterOnError = FlutterError.onError;
FlutterError.onError = (FlutterErrorDetails details) {
  CrumbsStore.recordException(/* ... */);
  _previousFlutterOnError?.call(details);
};

// 2. Chain-preserve PlatformDispatcher.instance.onError (async and isolate errors).
_previousPlatformOnError = PlatformDispatcher.instance.onError;
PlatformDispatcher.instance.onError = (Object error, StackTrace stack) {
  CrumbsStore.recordException(/* ... */);
  return _previousPlatformOnError?.call(error, stack) ?? true;
};

Framework-agnostic watchers#

These units ship in crumbs and depend on no application framework.

LogWatcher#

Subscribes to Logger.root.onRecord from package:logging. Every record that reaches the root logger, at any level, becomes a LogRecordEntry (stamped with a monotonic atUs) and goes to the store, through CrumbsRedaction.redactor when the host set one.

Install sets hierarchicalLoggingEnabled to true so named child loggers (Logger('http'), Logger('auth')) reach the root, and sets Logger.root.level to Level.ALL so fine-grained levels are emitted too. A second install while the subscription is live is a no-op. An app that does not use package:logging simply produces no records; adding it later needs no crumbs change. CrumbsPlugin.install() offers no way to leave LogWatcher out. A level the app sets on Logger.root after the install still decides which records are emitted at all.

ExceptionWatcher#

Hooks FlutterError.onError (synchronous framework and widget errors) and PlatformDispatcher.instance.onError (asynchronous errors, isolate errors, plugin errors), both through the chain-preserve pattern. The PlatformDispatcher handler returns the previous handler's answer, so a reporter that returns false to let the native crash reporter take over keeps that behaviour; with no previous handler it returns true (handled), as before install.

uninstall() restores both handlers to exactly what they held before install(); a second install() is a no-op.

To coexist with Sentry, initialise Sentry first: the watcher wraps the handlers that already exist, so a reporter installed after crumbs keeps receiving errors only if it chains as well.

// sentryDsn is the host's; SentryFlutter.init sets both error hooks.
await SentryFlutter.init((options) => options.dsn = sentryDsn);
if (kDebugMode) {
  CrumbsPlugin.install();
  CrumbsPlugin.registerWatcher(ExceptionWatcher()); // wraps Sentry's handlers; Sentry still fires
}

DumpWatcher#

Replaces the global debugPrint callback with an interceptor that records a DumpRecord and calls the previous callback. uninstall() restores the previous callback exactly. print() does not go through debugPrint and is not captured.

install() is a no-op outside a debug build unless allowInRelease is set to true before it runs.

if (kDebugMode) {
  CrumbsPlugin.install();
  CrumbsPlugin.registerWatcher(DumpWatcher());
}

FramePerfWatcher#

Joins frame magnitude from SchedulerBinding.addTimingsCallback with per-frame attribution drained from FlutterTimeline, and exposes a static livenessCounter with every ext.crumbs.frames answer. See FramePerfWatcher for liveness, attribution and the clock.

if (!kReleaseMode) {
  CrumbsPlugin.install();
  CrumbsPlugin.registerWatcher(FramePerfWatcher());
}

HTTP adapters#

HTTP adapters implement CrumbsHttpAdapter: name, install and uninstall, plus an optional pendingCount getter. They feed CrumbsStore.recordHttp, and their in-flight counts add up in CrumbsStore.pendingHttpCount, which tapir's wait_for_network_idle reads. Register an adapter with CrumbsPlugin.registerHttpAdapter(), which calls its install() at once.

Credential redaction#

The HTTP buffer is served to AI agents, so CrumbsStore.recordHttp masks credentials before it buffers a record, and onHttpRecord subscribers receive the masked copy too. The model is Laravel Telescope's: three name lists, matched case-insensitively, each value under a matching name replaced with ********.

Extend a list at install time; an addition merges with the defaults and never replaces them:

CrumbsRedaction.hideRequestHeaders(['X-Auth']);
CrumbsRedaction.hideRequestParameters(['pin']);
CrumbsRedaction.hideResponseParameters(['recovery_codes']);

An empty value (null, false, '', [], {}) stays visible: it is not a secret, and it explains a validation failure. A subtree nested deeper than 64 levels is masked whole, which keeps recordHttp from overflowing the stack on a pathological body. A bare list with no key (recovery codes returned directly under data, for example) has nothing to match and is not masked.

The store reads bodies that parse as a JSON object or array, and form-encoded bodies (grant_type=password&password=...), where only the value of a matching pair changes and a bracketed key (user[password], codes[]) matches on its last part. Anything else (plain text, a truncated JSON snippet, a Dart Map.toString()) is buffered as the adapter handed it over, so an adapter masks a body before it stringifies or truncates it:

// A body held as a Dart structure.
final Object? safe = CrumbsRedaction.redactParameters(
  data,
  CrumbsRedaction.hiddenRequestParameters,
);

// A body held as a string, before it is cut to size.
final String? safeText = CrumbsRedaction.redactBody(
  text,
  CrumbsRedaction.hiddenResponseParameters,
);

Both return a masked copy and never mutate their input. Beyond these lists, a host can set CrumbsRedaction.redactor to run its own text redactor over every field of the log, event, exception and HTTP records, after the key masking; a redactor that throws drops the record. See Redaction.

DioHttpAdapter#

crumbs does not depend on dio, so DioHttpAdapter hooks nothing itself: its install() and uninstall() are empty and its pendingCount is 0. The app adds dio, writes an interceptor, and records each response through the static DioHttpAdapter.recordRequest(), which goes through recordHttp and its credential masking like any adapter:

import 'package:crumbs/crumbs.dart';
import 'package:dio/dio.dart';

class CrumbsDioInterceptor extends Interceptor {
  @override
  void onResponse(Response<dynamic> response, ResponseInterceptorHandler handler) {
    DioHttpAdapter.recordRequest(
      url: response.requestOptions.uri.toString(),
      method: response.requestOptions.method,
      statusCode: response.statusCode ?? 0,
      durationMs: 0, // time the request in onRequest for a real duration
    );
    handler.next(response);
  }
}

Add it with dio.interceptors.add(CrumbsDioInterceptor()). The bundled example/ app has a complete interceptor that times each request and records errors. CrumbsPlugin.registerHttpAdapter(DioHttpAdapter()) only lists the adapter in the registry; it is optional.

MagicHttpFacadeAdapter#

Captures every request through Magic's network driver by registering a MagicNetworkInterceptor that pairs onRequest with onResponse or onError through a FIFO in-flight list. The pairing is by call order, since the interceptor contract carries no correlation handle, so records carry attributedHeuristically: true. pendingCount is the length of that in-flight list.

The adapter masks request and response bodies before it truncates them, and MagicCrumbsIntegration.install() hides the header named by Magic's auth.token.header config (default Authorization) on top of the defaults. Its install() registers nothing while the network driver is not bound, so call MagicCrumbsIntegration.install() after Magic.init().

Magic-stack watchers#

These watchers ship in magic_devtools, not in crumbs and not in magic core, and one MagicCrumbsIntegration.install() call after Magic.init() registers all of them with MagicHttpFacadeAdapter:

import 'package:magic_devtools/crumbs.dart';

if (kDebugMode) {
  MagicCrumbsIntegration.install(); // after Magic.init()
}

package:magic_devtools/crumbs.dart exists only in a magic_devtools release built on crumbs. crumbs:install writes these lines when the resolved magic_devtools ships it, and warns and skips them otherwise. Until that release ships, MagicTelescopeIntegration feeds fluttersdk_telescope, not crumbs, so the HTTP, event, gate, query and cache buffers of crumbs stay empty in a Magic app. Each watcher subscribes through Magic's EventDispatcher, which has no per-listener removal, so its uninstall() is a no-op; a test that needs a clean dispatcher calls EventDispatcher.instance.clear() in setUp.

The model buffer has no extension and no MCP tool: read it in the app through CrumbsStore.recentModels() or CrumbsStore.onModelRecord.

Gotchas#

Related Documentation#

• FramePerfWatcher: liveness, attribution and the frame clock.
• Redaction: the text redactor and the redacted flag.
• Installation: where each watcher is registered in main.dart.
• Tool reference: the output shape of each buffer over MCP.