Adding Analytics Inspection to the Debug Panel

What you'll learn

• Generating the analytics inspector sub-brick for app_debugger
• Understanding how the ring buffer captures events without dropping them
• Wiring the analytics interceptor into your bootstrap
• Stripping the inspector from release builds with build_prepare

Prerequisites

• app_debugger brick already installed (see App Debugger Setup)
• analytics_impl dependency present and registered in your bootstrap

Step 1: Generate the Brick

archipelago generate app_debugger_analytics

No variables are required. The generator detects your monorepo layout and places the packages automatically.

Step 2: Understand the Generated Packages

Three packages are generated:

infrastructure/
├── app_debugger_analytics_api/     # Inspector contract
│   └── lib/src/
│       └── analytics_inspector_sdk.dart
├── app_debugger_analytics/         # Debug tab implementation
│   └── lib/src/
│       ├── analytics_inspector_sdk_impl.dart
│       ├── interceptor/analytics_debug_interceptor.dart
│       └── di/analytics_inspector_module.dart
└── app_debugger_analytics_noop/    # Release no-op
    └── lib/src/
        └── analytics_inspector_sdk_noop.dart

The ring buffer inside the impl holds up to 1 000 entries. It is purely observational — events are never dropped, modified, or delayed by the inspector.

Step 3: Configure build_prepare

Add the swap entry to build_prepare.yaml:

# build_prepare.yaml
flavors:
  debug:
    app_debugger_analytics:
      dependency: app_debugger_analytics       # Real inspector in debug
  release:
    app_debugger_analytics:
      dependency: app_debugger_analytics_noop  # Stripped in release

Run before each release build:

dart run devtools/build_prepare.dart --flavor release

Step 4: Wire the Interceptor in bootstrap.dart

The post_gen hook patches two locations inside bootstrap.dart. Verify both are present after generation:

// 1. Register the inspector as a debug panel tab
// Inside the archipelago:debug_panel_pages sentinel:
GetIt.I<AnalyticsInspectorSDK>();

// 2. Attach the interceptor to the analytics pipeline
final analyticsInterceptor = GetIt.I<AnalyticsInspectorSDK>().interceptor;
if (analyticsInterceptor != null) {
  AnalyticsInitializer.registerInterceptor(analyticsInterceptor);
}

If you skipped post_gen or the patch was not applied, add these lines manually inside your bootstrap sequence, after DI is initialised.

Step 5: Verify in Debug Mode

Run the app in debug mode and navigate to the debug panel. You should see an Analytics tab. Fire a test event from any screen:

GetIt.I<AnalyticsSDK>().track('tutorial_test', {'step': 1});

The event appears in the tab immediately. The ring buffer scrolls automatically once the 1 000-entry limit is reached — oldest entries are discarded first.

How the Ring Buffer Works

Property	Value
Capacity	1 000 entries
Behaviour at capacity	Oldest entry evicted
Impact on event delivery	None — interceptor is passive
Available in release	No (noop swapped in)

Next Steps

• Set up App Debugger if you haven't already
• Configure Analytics SDK to see which events you are tracking