Adding WebSocket Inspection to the Debug Panel

Enterprise

What you'll learn

• Generating the WebSocket inspector sub-brick for app_debugger
• Configuring the ring buffer (capacity, payload capture, truncation)
• Wiring the inspector interceptor into your WebSocket client
• Reading the live endpoint > topic > event tree in the panel

Prerequisites

• app_debugger brick already installed (see App Debugger Setup)
• websocket_sdk configured and registered in your bootstrap

Step 1: Generate the Brick

archipelago generate app_debugger_websocket

No variables are required. The brick works with any WebSocketClient implementation registered in GetIt.

Step 2: Understand the Generated Packages

infrastructure/
├── app_debugger_websocket_api/     # Inspector contract
│   └── lib/src/
│       ├── websocket_inspector_sdk.dart
│       └── config/websocket_inspector_config.dart
├── app_debugger_websocket/         # Debug tab implementation
│   └── lib/src/
│       ├── websocket_inspector_sdk_impl.dart
│       ├── interceptor/websocket_debug_interceptor.dart
│       └── di/websocket_inspector_module.dart
└── app_debugger_websocket_noop/    # Release no-op
    └── lib/src/
        └── websocket_inspector_sdk_noop.dart

Step 3: Configure build_prepare

# build_prepare.yaml
flavors:
  debug:
    app_debugger_websocket:
      dependency: app_debugger_websocket
  release:
    app_debugger_websocket:
      dependency: app_debugger_websocket_noop

Step 4: Configure the Ring Buffer

The default WebSocketInspectorConfig works for most projects. Override it in your DI module if you need different limits:

// In your bootstrap or DI module, before registering the SDK
getIt.registerSingleton<WebSocketInspectorConfig>(
  WebSocketInspectorConfig(
    maxEntries: 500,           // default: 500 frames total
    capturePayloads: true,     // default: true
    payloadTruncateLength: 2048, // default: 2048 bytes
  ),
);

Payloads larger than payloadTruncateLength are stored as truncated strings with a [truncated] suffix — the full frame is still delivered to your app.

Step 5: Wire the Interceptor in bootstrap.dart

After DI is initialised:

final wsInspector = getIt<WebSocketInspectorSDK>();
if (wsInspector.interceptor != null) {
  getIt<WebSocketClient>().addInterceptor(wsInspector.interceptor!);
}

The interceptor is null in the noop implementation, so this guard is safe to leave in shared bootstrap code.

Step 6: Verify in Debug Mode

Run the app and open any WebSocket connection. Open the debug panel and tap WebSocket. You should see a live tree organised as:

wss://api.example.com/socket
  └── chat
        ├── message.new         (12 frames)
        ├── message.read        (3 frames)
        └── presence.join       (1 frame)

Tap any event row to see the individual frames with timestamps and payloads.

Ring Buffer Reference

Config Key	Default	Notes
maxEntries	500	Oldest frames evicted when full
capturePayloads	true	Set false to capture metadata only
payloadTruncateLength	2048	Bytes; [truncated] appended beyond limit

Next Steps

• Set up App Debugger if you haven't already
• Configure WebSocket SDK to manage connections and topics