MQTT Topic Browser: Live-Topic-Bäume erkunden

Ein MQTT Topic Browser zeigt jedes Topic, das durch einen Broker fließt, als live aktualisierten, aufklappbaren Baum, mit dem neuesten Payload neben jedem Knoten. In diesem Tutorial erzeugen Sie eine realistische Topic-Hierarchie, erkunden sie im Live-Topic-Explorer von ConnectMQ und auf der Kommandozeile und lernen die Muster kennen, die Namensfehler, veraltete Retained Messages und fehlerhafte Payloads in Sekunden sichtbar machen.

Was ein MQTT Topic Browser tut

MQTT hat keinen eingebauten Befehl zum Auflisten von Topics. Topics werden weder angelegt noch registriert; sie existieren nur, weil jemand auf sie publiziert. Ein Topic Browser umgeht das, indem er eine breite Wildcard wie # (oder eine Projektwurzel wie factory1/#) abonniert und aus den empfangenen Topic-Strings einen Baum baut. Jeder Schrägstrich wird zu einer Ebene, jede Ebene zu einem Ordner, und der jüngste Payload wird am Blatt angezeigt.

Diese einfache Idee ist erstaunlich wirkungsvoll. Ein flacher Nachrichtenstrom aus mosquitto_sub ist ab einem Dutzend Geräten schwer zu lesen. Ein Baum zeigt Ihnen auf einen Blick:

Welche Zweige existieren und welche nicht existieren sollten.
Welche Blätter sich gerade aktualisieren und welche vor Stunden verstummt sind.
Welche Werte retained sind, also einem neuen Subscriber sofort zugestellt werden.
Wie groß und wie wohlgeformt die Payloads sind.

Wenn Ihnen Topic-Strukturen neu sind, hilft es, vorher zu verstehen, was ein MQTT-Broker mit Topics und Subscriptions macht.

Einen Topic-Baum zum Erkunden erzeugen

Zum Durchsuchen brauchen Sie Verkehr. Das folgende Skript publiziert eine kleine Fabrikhierarchie auf den kostenlosen öffentlichen MQTT-Broker unter broker.connectmq.com. Es enthält absichtlich drei häufige Fehler, die Sie anschließend im Browser finden können. Installieren Sie den Client mit pip install "paho-mqtt>=2.0".

import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

RUN_ID = uuid.uuid4().hex[:6]
ROOT = f"connectmq/demo/{RUN_ID}"

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id=f"tree-gen-{RUN_ID}",
)
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_start()
print(f"Publishing under {ROOT}/  (subscribe to {ROOT}/#)")

# Gerätemetadaten als Retained Messages
for line in ("line1", "line2"):
    for machine in ("cnc1", "cnc2"):
        meta = {"vendor": "demo", "model": "X200", "line": line}
        client.publish(f"{ROOT}/factory1/{line}/{machine}/meta",
                       json.dumps(meta), qos=1, retain=True)

# Fehler 1: inkonsistente Groß-/Kleinschreibung erzeugt einen parallelen Zweig
client.publish(f"{ROOT}/factory1/Line1/cnc1/meta", "{}", qos=1, retain=True)
# Fehler 2: abschließender Schrägstrich erzeugt eine leere letzte Ebene
client.publish(f"{ROOT}/factory1/line2/cnc2/telemetry/", "42", qos=0)

try:
    while True:
        for line in ("line1", "line2"):
            for machine in ("cnc1", "cnc2"):
                payload = {
                    "spindle_rpm": random.randint(9000, 12000),
                    "temperature": round(random.uniform(35, 60), 1),
                    "ts": int(time.time()),
                }
                client.publish(f"{ROOT}/factory1/{line}/{machine}/telemetry",
                               json.dumps(payload), qos=0)
        # Fehler 3: ein Payload, der kein gültiges JSON ist
        client.publish(f"{ROOT}/factory1/line1/cnc2/telemetry",
                       "temp=48.2;rpm=10100", qos=0)
        time.sleep(2)
except KeyboardInterrupt:
    client.loop_stop()
    client.disconnect()

Das Skript publiziert pro Durchlauf vier Nachrichten plus die fehlerhafte und bleibt damit bequem unter dem Limit des öffentlichen MQTT-Brokers von 10 Nachrichten pro Sekunde und Client. Lassen Sie es laufen und notieren Sie die ausgegebene Wurzel.

Den Baum im ConnectMQ Topic-Explorer erkunden

Auf Ihrem eigenen Broker ist der Live-Topic-Explorer im ConnectMQ-Portal der integrierte Topic Browser. Um mitzumachen, legen Sie im Portal einen kostenlosen Broker an und richten das obige Skript darauf aus, indem Sie auf Port 8883 mit TLS wechseln und die vom Portal generierten Zugangsdaten ergänzen (YOUR_USERNAME, YOUR_PASSWORD, YOUR_CLIENT_ID). Für einen schnellen Blick auf den öffentlichen MQTT-Broker kann sich stattdessen jeder MQTT-Explorer mit WebSocket-Unterstützung mit wss://broker.connectmq.com:8084/mqtt verbinden und Ihre Wurzel connectmq/demo/<run-id>/# abonnieren.

Während Nachrichten eintreffen, gehen Sie den Baum von oben durch:

Wurzel aufklappen. Sie sollten factory1 sehen und darunter line1, line2 sowie ein unerwartetes Line1. Topics unterscheiden Groß- und Kleinschreibung, daher ist Line1 ein eigener Zweig, den kein Subscriber von line1/# je empfangen wird.
line2/cnc2 öffnen. Unter telemetry gibt es ein Kind ohne Namen. Das ist der abschließende Schrägstrich: telemetry/ hat eine Ebene mehr als telemetry, und eine Subscription auf .../cnc2/telemetry passt nicht darauf.
line1/cnc2/telemetry öffnen. Der Wert wechselt zwischen JSON und temp=48.2;rpm=10100. Jeder Konsument, der JSON parst, wirft bei jeder zweiten Nachricht einen Fehler.
Die meta-Blätter betrachten. Sie tragen das Retained-Flag. Trennen Sie die Verbindung und verbinden Sie sich neu: Sie erscheinen sofort, während Telemetrie erst mit der nächsten Nachricht auftaucht.

In industriellen Projekten ist der Topic-Baum meist ein Unified Namespace (UNS): Die ISA-95-Ausrüstungshierarchie (Enterprise → Site → Area → Line → Cell) wird zur Topic-Struktur auf dem Broker, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur. Ein Topic Browser ist dann das schnellste Werkzeug, um zu prüfen, ob jede SPS, jedes Gateway und jede Maschine an der richtigen Stelle im UNS publiziert. Das ConnectMQ-Portal bietet dafür außerdem eine Geräteansicht nach ISA-95-Ebenen (Enterprise, Site, Area, Line, Cell). Folgen Ihre Topics diesem UNS-Layout, gruppiert die Ansicht dieselben Daten nach Anlagenhierarchie statt nach rohen Strings, wodurch falsch eingeordnete Geräte auffallen. Unser Artikel zu Sparkplug B und dem Unified Namespace erklärt diese Struktur.

Topics auf der Kommandozeile durchsuchen

Ein grafischer Browser ist nicht immer zur Hand. mosquitto_sub mit dem Flag -v gibt vor jedem Payload das Topic aus, und ein paar zusätzliche Flags machen daraus einen schlanken Browser:

# Jedes Topic unter Ihrer Wurzel, mit Topic-Namen
mosquitto_sub -h broker.connectmq.com -p 1883 -i browse-$RANDOM \
  -t 'connectmq/demo/RUN_ID/#' -v

# Nur Retained Messages: verbinden, Retained-Inhalte ausgeben, nach 3 s beenden
mosquitto_sub -h broker.connectmq.com -p 1883 -i retained-$RANDOM \
  -t 'connectmq/demo/RUN_ID/#' -v --retained-only -W 3

# Eindeutige Topic-Namen, die in 30 Sekunden gesehen wurden
timeout 30 mosquitto_sub -h broker.connectmq.com -p 1883 -i list-$RANDOM \
  -t 'connectmq/demo/RUN_ID/#' -F '%t' | sort -u

Ersetzen Sie RUN_ID durch den Wert, den das Skript ausgegeben hat. Der letzte Befehl kommt einem „Topics auflisten" in MQTT am nächsten und ist ein schneller Weg, die erwarteten Topics mit den tatsächlich vorhandenen abzugleichen. Weitere Rezepte finden Sie in unseren Beispielen für mosquitto_pub und mosquitto_sub.

Debugging-Muster, die ein Topic Browser aufdeckt

Sobald Sie geübt darin sind, einen Baum zu lesen, fallen die meisten Topic-Probleme in eine kleine Zahl von Mustern.

Was Sie im Baum sehen	Was es bedeutet	Lösung
Zwei Zweige, die sich nur in der Schreibweise unterscheiden	Inkonsistente Benennung in Firmware oder Konfiguration	Auf Kleinschreibung standardisieren und im Code-Review durchsetzen
Ein Blatt ohne Namen	Abschließender Schrägstrich im Publish-Topic	Abschließende Schrägstriche vor dem Publizieren entfernen
Eine erste Ebene ohne Namen	Führender Schrägstrich (`/factory1/...`)	Führenden Schrägstrich entfernen; er fügt eine nutzlose Ebene hinzu
Ein Blatt, dessen Wert sich nie ändert	Gerät publiziert nicht mehr, oder der Wert sind veraltete Retained-Daten	Gerät prüfen; die Retained Message löschen, wenn sie überholt ist
Werte, die zwischen Formaten wechseln	Zwei Firmware-Versionen oder zwei Publisher auf einem Topic	Payload versionieren oder Topics trennen
Hunderte Geschwisterblätter mit IDs im Namen	Eindeutige IDs zu weit oben in der Hierarchie	IDs auf die Geräteebene verschieben
Sehr tiefe Zweige	Überstrukturierte Topics	Abflachen; der öffentliche MQTT-Broker erlaubt 8 Ebenen

Veraltete Retained Messages löschen

Retained-Werte bleiben auf dem Broker, bis sie ersetzt werden. Ein stillgelegtes Gerät kann daher in jedem Dashboard weiter einen „aktuellen" Wert anzeigen. Um eine Retained Message zu entfernen, publizieren Sie einen leeren Retained-Payload auf genau dieses Topic:

mosquitto_pub -h broker.connectmq.com -p 1883 -i clear-$RANDOM \
  -t 'connectmq/demo/RUN_ID/factory1/Line1/cnc1/meta' -r -n

Das Flag -n sendet einen Payload der Länge null, und -r setzt das Retain-Flag. Aktualisieren Sie den Topic Browser, und der Zweig Line1 verschwindet, sobald er keine weiteren Kinder hat.

Einen Topic Browser in der Produktion gut nutzen

Ein Browser, der auf einem stark ausgelasteten Produktions-Broker # abonniert, empfängt jede Nachricht. Das kostet Bandbreite und kann Subscription- oder Verbindungsquoten erreichen. Ein paar Gewohnheiten halten ihn nützlich:

Abonnieren Sie die engste Wurzel, die Ihre Frage beantwortet, etwa factory1/line2/# statt #.
Verwenden Sie eigene Zugangsdaten für Debugging-Tools, damit eine Browser-Sitzung niemals die Client ID eines Geräts übernimmt und das Gerät offline wirft.
Prüfen Sie neben den Daten auch den Verbindungszustand. Das Topic $SYS/broker/connection/{clientId}/state auf Ihrem ConnectMQ-Broker zeigt, ob ein bestimmter Client verbunden ist, und trennt so „Gerät offline" von „Gerät online, aber stumm".
Halten Sie Ihre Benennungsregeln schriftlich fest und vergleichen Sie den Baum nach jedem Firmware-Release damit.

Für editorzentrierte Arbeitsabläufe bieten die ConnectMQ-Erweiterung für VS Code und der ConnectMQ-Desktop-MQTT-Explorer dieselbe baumartige Ansicht außerhalb des Portals. Wenn Sie ausschließlich im Browser testen, ergänzt unser Leitfaden zum MQTT Web Client online diesen Artikel gut, und MQTT-Broker-Monitoring behandelt die Metriken, die ein Topic Browser nicht zeigt.

Eigene Topics mit ConnectMQ erkunden

Legen Sie unter app.connectmq.com einen kostenlosen Broker im Serverless-Plan an, ganz ohne Kreditkarte. Das Portal enthält den Live-Topic-Explorer, den Browser-Client und die ISA-95-Geräteansicht aus diesem Leitfaden. Erfahren Sie mehr über ConnectMQ als verwalteten MQTT-Broker oder lesen Sie den umfassenderen Leitfaden zur Wahl eines Cloud-MQTT-Brokers.

Häufig gestellte Fragen

Kann ich alle Topics auf einem MQTT-Broker auflisten?

Nicht direkt; MQTT hat kein Topic-Register. Ein Topic Browser abonniert eine Wildcard und zeigt die Topics, die Nachrichten erhalten, plus alle Retained-Topics, was in der Praxis gleichwertig ist.

Warum zeigt mein Topic Browser ein Topic nicht an, von dem ich weiß, dass es existiert?

Entweder wurde seit Ihrer Subscription nichts darauf publiziert und es hält keine Retained Message, oder Ihre Wildcard deckt es nicht ab. Prüfen Sie Groß- und Kleinschreibung, führende oder abschließende Schrägstriche und die Wurzel der Subscription.

Ist es sicher, auf einem Produktions-Broker # zu abonnieren?

Es funktioniert, empfängt aber jede Nachricht, was viel Last bedeuten kann. Abonnieren Sie die engste Wurzel, die Ihre Frage beantwortet, und nutzen Sie eigene Debugging-Zugangsdaten.

Wie lösche ich ein Topic aus dem Baum?

Topics verschwinden, wenn nichts sie mehr hält. Löschen Sie eine Retained Message, indem Sie einen leeren Retained-Payload auf genau dieses Topic publizieren, und stoppen Sie den Publisher, der es erzeugt.

MQTT Topic Browser: Live-Topic-Bäume erkunden und debuggen