app_debugger_mqtt Enterprise

Docs/Bricks/app_debugger_mqtt

Tier

Enterpriseversion 1.1.4

Command

archipelago generate app_debugger_mqtt

Generates

• features/app_debugger_mqtt/app_debugger_mqtt
• features/app_debugger_mqtt/app_debugger_mqtt_api
• features/app_debugger_mqtt/app_debugger_mqtt_noop

Generates first

app_debuggerwhen needed and missing, so there is nothing to install first

MQTT signal-channel debugger tool sub-brick for app_debugger. Adds an MQTT tool to the debugger that lists live connect/subscribe/error/retry diagnostics, newest first. Automatically swapped to a no-op stub in production-flavor builds via build_prepare.yaml.

What it is / when to use it

Unlike the WebSocket and Network inspector sub-bricks, app_debugger_mqtt has no interceptor to auto-capture traffic — there is no bundled MQTT client in Archipelago to intercept. Instead it gives you MqttDebugLog, a simple sink you call record(String message) on from wherever your own MQTT client (any package/implementation) reports diagnostics: connect attempts, subscribe confirmations, received hints, errors, retries. Use this brick when your app has its own MQTT signal channel and you want its diagnostics visible in the same debugger as your other inspectors, without hand-rolling a debug UI.

Variables

This brick has no generation-time variables. The log works with any MQTT client implementation at runtime.

Prerequisites

• app_debugger is generated first when the project lacks it. It provides the archipelago:debug_panel_pages sentinel inside app_debugger's own AppDebuggerSDKImpl — the post_gen hook patches that file to eagerly resolve MqttDebugLog).
• An MQTT client of your own (any implementation) to feed diagnostics into MqttDebugLog.

Usage

Interactive

archipelago generate app_debugger_mqtt

Non-interactive (CI)

archipelago generate app_debugger_mqtt --config my_config.json

Generated Structure

features/
└── app_debugger_mqtt/
    ├── app_debugger_mqtt_api/
    │   └── lib/src/
    │       ├── models/
    │       │   └── mqtt_debug_event.dart
    │       └── mqtt_debug_log.dart          # MqttDebugLog contract
    ├── app_debugger_mqtt/
    │   └── lib/src/
    │       ├── di/
    │       ├── mqtt_debug_log_impl.dart
    │       └── mqtt_inspector_page.dart
    └── app_debugger_mqtt_noop/
        └── lib/src/
            ├── di/
            └── mqtt_debug_log_impl.dart

Public API

abstract interface class MqttDebugLog() {
  /// Records a diagnostic message -- a connect attempt, subscribe
  /// confirmation, received hint, error, or retry.
  void record(String message);

  /// The retained event history, oldest first, capped so a long-running
  /// debug session cannot grow it unbounded.
  ValueListenable<List<MqttDebugEvent>> get events;
}

The debug implementation (MqttDebugLogImpl) keeps a ring buffer of the last 200 events and self-registers an MqttInspectorPage with DebuggerPanelPageRegistry on construction. The noop stub's record is fully inert and events stays permanently empty — no panel page is registered.

Required Setup — call record() yourself

There is no interceptor to auto-wire. Call record() from wherever your MQTT client reports diagnostics:

import 'package:app_debugger_mqtt_api/app_debugger_mqtt_api.dart';

getIt<MqttDebugLog>().record('subscribed to workspace/$id/changed');

The hook already adds GetIt.I<MqttDebugLog>() inside the archipelago:debug_panel_pages sentinel in di/debug_tools.dart, so the panel page registers before the first frame renders — the MQTT tool appears even if record() is never called, just empty until it is.

Wiring (Auto-Patched by post_gen.dart)

Patched into features/app_debugger/app_debugger/lib/src/di/debug_tools.dart on a current project. The marker moved between app_debugger versions, so the hook uses the first file that has it: app_debugger's lib/src/di/debug_tools.dart (2.0.0 and later), its lib/src/app_debugger_sdk_impl.dart (1.3.0 to 1.15.x), then the app's lib/bootstrap.dart (older), and adds the imports and path dependencies to that package. A file that already resolves the SDK is left as it is. If no file has the marker, pre_gen prints the lines to add and stops before it writes any file.

// archipelago:debug_panel_pages:start
GetIt.I<MqttDebugLog>();
// archipelago:debug_panel_pages:end

If the sentinel can't be found (e.g. a hand-edited app_debugger without the marker), the hook logs a warning and the eager resolution must be added manually.

How It Works

1. MqttDebugLogImpl keeps a bounded ring buffer (last 200 events) and registers an MqttInspectorPage with DebuggerPanelPageRegistry on construction.
2. The debugger home reads DebuggerPanelPageRegistry.instance.pages and lists each page as a tool on its own route — no import of app_debugger_mqtt required.
3. MqttInspectorPage lists events newest-first, updating live via ValueListenableBuilder.
4. build_prepare.yaml swaps app_debugger_mqtt → app_debugger_mqtt_noop for production-flavor builds, stripping all inspector code from the binary.

Dependencies

• app_debugger — generated first when missing.

Changelog

Run archipelago brick info app_debugger_mqtt to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.