MQTT Explorer : inspecter et déboguer un broker

MQTT Explorer est un client de bureau gratuit qui s'abonne à un broker et affiche tout ce qu'il reçoit sous forme d'arbre de topics vivant et repliable. C'est le moyen le plus rapide de répondre à « qu'y a-t-il vraiment sur ce broker ? » : quels topics existent, lesquels portent des messages retenus, ce qui a changé dans le dernier payload et comment une valeur évolue dans le temps. Ce guide couvre l'installation, la connexion sécurisée et les fonctionnalités utiles au débogage.

Installer MQTT Explorer

MQTT Explorer, de Thomas Nordquist, fonctionne sous Windows, macOS et Linux. Téléchargez-le sur mqtt-explorer.com ou depuis les releases GitHub du projet, ou utilisez un gestionnaire de paquets :

# macOS (Homebrew)
brew install --cask mqtt-explorer

# Linux (Snap)
sudo snap install mqtt-explorer

# Windows (winget)
winget install thomasnordquist.MQTT-Explorer

Sous Linux, l'AppImage fonctionne aussi sans installation. Les noms de paquets peuvent changer d'une version à l'autre ; si l'un d'eux échoue, récupérez le build sur la page des releases.

Se connecter à un broker

La fenêtre de connexion s'ouvre au démarrage. Renseignez :

Privilégiez TLS dès que des identifiants sont en jeu — sur le port 1883 en clair, le mot de passe circule en texte lisible. Laissez Validate certificate activé ; le désactiver masque de vrais problèmes, comme un nom d'hôte qui ne correspond pas. Pour un broker avec une CA privée, ajoutez plutôt le fichier CA sous Advanced → Certificates.

Dans Advanced, vous pouvez aussi définir le MQTT Client ID. Donnez-lui un nom reconnaissable comme explorer-votrenom ; si vous réutilisez l'ID d'un appareil en fonctionnement, le broker déconnecte l'un des deux et vous traquerez un bug fantôme (« session taken over »). Le générateur de client IDs vous aide si vous avez besoin d'un identifiant unique.

Générer des données à observer

Pour suivre ce guide, publiez quelques messages sur votre préfixe de test — des messages de statut retenus et une valeur de télémétrie qui change :

H=broker.connectmq.com
P=testmqtt/explorer

mosquitto_pub -h $H -t "$P/device-1/status" -m online -r
mosquitto_pub -h $H -t "$P/device-2/status" -m offline -r
mosquitto_pub -h $H -t "$P/config" -m '{"interval":5,"unit":"C"}' -r

for i in $(seq 1 30); do
  T=$(awk -v s=$RANDOM 'BEGIN{srand(s); printf "%.1f", 20+rand()*3}')
  mosquitto_pub -h $H -t "$P/device-1/temperature" -m "{\"temp\":$T,\"seq\":$i}"
  sleep 2
done

Si vous n'avez pas les outils mosquitto, vous pouvez faire la même chose depuis le navigateur avec le client MQTT en ligne.

Lire l'arbre des topics

Le panneau de gauche construit la hiérarchie à partir des niveaux de topic : testmqtt → explorer → device-1 → temperature. Chaque nœud indique combien de sous-topics et de messages il contient, et les nœuds s'illuminent brièvement à l'arrivée d'un nouveau message : les branches actives sautent aux yeux.

Servez-vous de l'arbre pour vérifier votre conception de topics :

• Fautes de frappe et différences de casse apparaissent immédiatement — Device-1 et device-1 sont deux branches distinctes, car les topics MQTT sont sensibles à la casse.
• Barres obliques en début ou en fin créent un niveau vide (/testmqtt/... a un nœud racine vide).
• Profondeur inattendue — des données de payload encodées par erreur dans le topic (.../temperature/21.5) apparaissent sous forme de centaines de nœuds frères.

Le champ de recherche en haut filtre l'arbre par nom de topic. Pour vérifier comment un abonnement avec wildcards se comporterait face à ces topics, utilisez le topic matcher. Plus d'informations sur la structure dans topics et wildcards MQTT.

Examiner valeurs, historique et diffs

Cliquez sur un topic : la barre latérale affiche sa dernière valeur, formatée en JSON quand le payload est analysable, avec le QoS, le flag retenu et l'heure de réception. En dessous se trouve l'historique des messages récents sur ce topic.

Lorsqu'un payload change, MQTT Explorer peut afficher un diff par rapport au message précédent : un seul champ modifié dans un gros document JSON devient évident. C'est idéal pour des questions comme « quel champ le firmware met-il à jour à chaque envoi ? » ou « la configuration a-t-elle changé après le déploiement ? ».

Pour les valeurs numériques — un nombre seul ou un champ numérique dans un JSON —, utilisez l'option de graphique de l'historique pour tracer la valeur dans le temps. Un motif en dents de scie, un capteur figé ou une valeur qui retombe à zéro à chaque reconnexion se voient bien mieux sur un graphique que dans une liste de messages.

Trouver et supprimer les messages retenus

Les messages retenus sont la source la plus fréquente de données « fantômes » : un appareil hors ligne depuis des mois apparaît toujours en ligne parce que son dernier statut retenu est encore sur le broker. Dans MQTT Explorer, les messages retenus sont signalés dans le panneau de valeur : vous pouvez parcourir l'arbre et voir quels topics en contiennent un.

Pour en supprimer un, sélectionnez le topic et cliquez sur l'icône de suppression dans la section Topic. Le client publie un message retenu vide sur ce topic, ce qui est la méthode standard pour l'effacer. Pour toute une branche, utilisez la suppression récursive. Deux mises en garde :

• Votre utilisateur doit avoir le droit de publication sur ces topics. Si l'ACL le refuse, sur de nombreux brokers la suppression ne fait rien, sans avertissement — voir ACL refusée en silence.
• Un appareil qui republie son état retenu à la reconnexion fera revenir le message. Corrigez la source, pas seulement le broker.

Si un message retenu revient malgré tout, le message retenu ne s'efface pas passe en revue les autres causes.

Publier des messages de test

La section Publish de la barre latérale envoie un message vers n'importe quel topic, avec un éditeur de payload (raw, JSON ou XML) et les options QoS et retain. Un clic sur un topic de l'arbre préremplit son nom, ce qui permet de rejouer ou d'ajuster rapidement un message existant — par exemple envoyer une commande à testmqtt/explorer/device-1/set et observer le topic de statut de l'appareil changer.

Surveiller $SYS pour la santé du broker

De nombreux brokers publient des statistiques sous $SYS/ — clients connectés, débits de messages, uptime. Conservez l'abonnement à $SYS/# si votre broker le prend en charge et tracez $SYS/broker/clients/connected ou les compteurs de charge pendant vos tests. Les topics disponibles dépendent du broker ; les topics $SYS de MQTT liste les plus courants. Les services managés peuvent restreindre ou omettre $SYS.

Problèmes fréquents

MQTT Explorer ou un autre client ?

MQTT Explorer est sans égal pour explorer : arbres de topics, messages retenus, diffs et graphiques rapides. Il est moins adapté au test des fonctions MQTT 5 ou à la gestion de nombreuses connexions en parallèle — MQTTX est plus fort sur ce terrain, et le comparatif des clients MQTT de bureau couvre le reste. Pour une vérification sans installation depuis n'importe quelle machine, utilisez le client du navigateur.

Publier des données de test depuis votre navigateur

Gardez MQTT Explorer ouvert pendant le développement : pointez-le vers un préfixe restreint sur une connexion TLS, laissez l'arbre vous montrer ce que vos appareils publient réellement, et utilisez les vues diff, graphique et messages retenus pour transformer « quelque chose cloche » en un topic et un champ précis. Il complète — sans les remplacer — les tests automatisés qui vérifient les mêmes points.

Questions fréquentes