How to inspect WebSocket frames in the Flutter debug panel

Docs/Tutorials/app_debugger_websocket

Enterprise Reference for app_debugger_websocket: every variable, option and package it generates. Command: archipelago generate app_debugger_websocket

Generate the WebSocket inspector for app_debugger, size the ring buffer, add the interceptor to your client, and read the endpoint, topic and event tree.

What you'll learn

• Generating the WebSocket inspector sub-brick for app_debugger
• Configuring the ring buffer
• Adding the inspector interceptor to your WebSocket client
• Reading the endpoint, topic and event tree in the panel

Prerequisites

• app_debugger already installed (see App Debugger Setup)
• websocket_sdk already generated (see WebSocket SDK)

Step 1: Generate the Brick

archipelago generate app_debugger_websocket

The brick has no variables. It works with any WebSocket SDK you installed.

Step 2: Understand the Generated Packages

features/app_debugger_websocket/
├── app_debugger_websocket_api/     # WebSocketInspectorSDK, config and entry models
├── app_debugger_websocket/         # Debug implementation and WebSocket tab
│   └── lib/src/
│       ├── websocket_debugger_interceptor.dart
│       ├── websocket_inspector_page.dart
│       └── websocket_inspector_sdk_impl.dart
└── app_debugger_websocket_noop/    # Production-flavor stub

Step 3: Check build_prepare

The brick adds the swap entry to build_prepare.yaml for you:

build_prepare:
  mappings:
    - debug: app_debugger_websocket
      release: app_debugger_websocket_noop

The generated Fastfile runs dart run monorepo_toolkit build-prepare --flavor <flavor> before every build. Internal flavors keep the inspector, also in release mode. The production flavor gets the noop.

Step 4: Configure the Ring Buffer

The defaults suit most projects. Register your own WebSocketInspectorConfig to change them:

getIt.registerSingleton<WebSocketInspectorConfig>(
  const WebSocketInspectorConfig(
    maxEntries: 500,
    capturePayloads: true,
    payloadTruncateLength: 2048,
  ),
);

A payload longer than payloadTruncateLength characters is truncated in the inspector. Your app still gets the full frame.

Step 5: Check the Wiring and Add the Interceptor

The hook adds GetIt.I<WebSocketInspectorSDK>(); at the archipelago:debug_panel_pages marker in app_debugger's lib/src/di/debug_tools.dart. This makes the WebSocket tab appear.

You add the interceptor yourself, after DI is ready:

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

The noop returns a null interceptor. The guard is safe to keep in shared code.

Step 6: Verify in an Internal Flavor

Open a WebSocket connection. Open the debug panel and tap WebSocket. The tab shows a tree:

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

Tap an event row to see its frames with timestamps and payloads.

Ring Buffer Reference

Config Key	Default	Notes
maxEntries	500	The oldest frame goes first when full
capturePayloads	true	Set false to keep metadata only
payloadTruncateLength	2048	Characters kept per payload

Next Steps

• Set up App Debugger if you have not already
• Configure the WebSocket SDK to manage connections and topics