Visualiser des données MQTT dans Grafana avec la source MQTT

Grafana peut s'abonner directement à un broker MQTT. Avec le plugin officiel MQTT data source (grafana-mqtt-datasource), chaque requête de panneau est un abonnement à un topic, et les nouveaux messages apparaissent sur le dashboard quelques instants après leur publication, sans base de données intermédiaire. C'est le moyen le plus rapide d'afficher une jauge ou un graphique en direct sur des données de capteurs.

Ce tutoriel installe le plugin, le connecte à un broker en TLS, publie de la télémétrie de test et construit des panneaux en temps réel. Il couvre aussi ce que l'on découvre souvent trop tard : la source de données diffuse, elle ne stocke pas.

Fonctionnement de la source de données MQTT

Le plugin s'exécute dans le serveur Grafana. Quand un panneau demande des données, le backend ouvre une connexion MQTT (une par source de données), s'abonne au topic de la requête et transmet chaque message au navigateur via Grafana Live, le canal de streaming WebSocket de Grafana.

Comme le serveur Grafana est le client MQTT, le broker doit être joignable depuis l'endroit où tourne Grafana, et les identifiants résident dans la configuration de la source de données, pas dans le navigateur.

Lancer Grafana avec le plugin

Le plus rapide est Docker. Le plugin est installé au démarrage depuis le catalogue de plugins Grafana :

docker run -d --name grafana -p 3000:3000 \
  -e GF_INSTALL_PLUGINS=grafana-mqtt-datasource \
  grafana/grafana:latest

Sur les versions récentes de Grafana, GF_PLUGINS_PREINSTALL=grafana-mqtt-datasource est la méthode plus récente pour obtenir le même résultat. Sur une installation existante, utilisez la CLI puis redémarrez le service :

grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-server

Ouvrez http://localhost:3000, connectez-vous (par défaut admin / admin, à changer ensuite) et allez dans Connections → Data sources → Add data source → MQTT.

Connecter la source de données au broker

La page de configuration demande une URI, des identifiants facultatifs et des options TLS :

• URI : tcp://broker.connectmq.com:1883 pour un test rapide en clair, tls://broker.connectmq.com:8883 pour TLS (certaines versions du plugin acceptent aussi ssl://). Utilisez TLS pour tout ce qui dépasse la démo.
• Username / Password : les identifiants de votre broker. Avec des ACL par topic, donnez à cet utilisateur un accès en lecture seule aux topics dont les dashboards ont besoin.
• TLS : activez « With CA Cert » si votre broker utilise une CA privée, ou l'authentification par certificat client pour le mTLS.

Cliquez sur Save & test. Un test réussi signifie que le serveur Grafana a pu ouvrir une connexion MQTT. En cas d'échec, l'erreur provient du CONNACK du broker ou du réseau : consultez les erreurs de connexion MQTT et recherchez les codes avec l'outil reason codes.

Pour des déploiements reproductibles, provisionnez la source de données à partir d'un fichier plutôt qu'en cliquant :

apiVersion: 1
datasources:
  - name: MQTT
    type: grafana-mqtt-datasource
    access: proxy
    jsonData:
      uri: tls://broker.connectmq.com:8883
      username: ${MQTT_USER}
    secureJsonData:
      password: ${MQTT_PASS}

Grafana remplace les variables d'environnement dans les fichiers de provisioning : le mot de passe ne finit donc jamais dans Git. Les noms de champs peuvent légèrement varier selon la version du plugin ; si une valeur est ignorée, configurez-la une fois dans l'interface et comparez avec le README du plugin.

Publier de la télémétrie de test

Un panneau n'affiche que les messages reçus pendant qu'il est ouvert : il vous faut donc un flux continu pour travailler. Ce script paho-mqtt 2.x publie une mesure JSON chaque seconde :

import json, math, os, random, time
import paho.mqtt.client as mqtt

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="grafana-demo-sensor")
client.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASS"])
client.tls_set()                       # magasin de CA du système
client.connect("broker.connectmq.com", 8883)
client.loop_start()

t = 0
while True:
    reading = {
        "temperature": round(21 + 3 * math.sin(t / 30) + random.uniform(-0.3, 0.3), 2),
        "humidity": round(45 + random.uniform(-2, 2), 1),
        "battery": max(0, 100 - t // 60),
    }
    client.publish("testmqtt/grafana/room1/telemetry", json.dumps(reading), qos=0)
    t += 1
    time.sleep(1)

Avant de toucher à Grafana, vérifiez le flux avec le client MQTT en ligne : abonnez-vous à testmqtt/grafana/# et regardez les messages arriver. S'ils apparaissent là mais pas dans Grafana, le problème vient de la source de données, pas du publieur.

Voir la télémétrie de test dans le navigateur

Construire des panneaux en direct

Créez un dashboard, ajoutez une visualisation et sélectionnez la source de données MQTT. L'éditeur de requêtes comporte un champ important, Topic : saisissez testmqtt/grafana/room1/telemetry.

1. Time series : le choix par défaut. Chaque clé JSON (temperature, humidity, battery) devient une série. Réglez la plage de temps du dashboard sur Last 5 minutes pour que le graphique défile au lieu de se compresser.
2. Gauge : changez de visualisation, réglez Calculation sur Last et choisissez le champ temperature dans Fields. Ajoutez des seuils (vert sous 25, rouge au-dessus de 28).
3. Stat : adapté à battery ; utilisez Last et l'unité pourcentage.

Si vous ne voulez qu'un seul champ dans un panneau, utilisez la transformation Organize fields ou Filter fields by name plutôt que de publier des topics séparés.

Formats de payload pris en charge

L'horodatage est l'instant où Grafana a reçu le message, pas un champ de temps de votre payload. Si les appareils bufferisent et envoient en retard, le graphique affichera l'heure d'arrivée ; voir les problèmes d'horodatage.

Wildcards et nombreux appareils

Les versions récentes du plugin acceptent + et # dans le champ topic : testmqtt/grafana/+/telemetry peut ainsi alimenter un panneau avec toutes les pièces. Vérifiez quels topics un filtre va capter avec le topic matcher avant de l'enregistrer : un # mal placé sur un broker chargé envoie au navigateur bien plus de données qu'un panneau ne peut en afficher. Pour de grandes flottes, préférez un panneau par groupe d'appareils, ou agrégez côté appareil et publiez un topic de synthèse. Voir topics et wildcards pour concevoir des topics que les dashboards filtrent proprement.

Dépannage

• « No data » sur un nouveau panneau : rien n'a été publié depuis l'ouverture du panneau. Le plugin ne rejoue pas les anciens messages, et les messages retenus ne servent que si le publieur active le flag retain. Lancez le publieur de test et attendez une seconde.
• Save & test échoue : vérifiez que le serveur Grafana (ou le conteneur) peut joindre le broker : docker exec grafana nc -vz broker.connectmq.com 8883. Les règles de sortie en entreprise bloquent souvent le 8883, même quand votre portable se connecte.
• Les données apparaissent puis s'arrêtent : un autre client avec le même client ID déconnecte Grafana, ou l'utilisateur n'a pas le droit de lecture et le broker ignore l'abonnement silencieusement. Consultez les logs du broker et vérifiez les ACL.
• Les nombres s'affichent comme du texte : le publieur envoie "23.5" entre guillemets. Corrigez le payload ou ajoutez une transformation Convert field type.
• Le panneau prend du retard ou l'onglet se fige : le filtre de topic est trop large ou les appareils publient plus vite que nécessaire. Réduisez la fréquence de publication ou agrégez d'abord.

Quand il vous faut un historique

La source de données MQTT est parfaite pour « que se passe-t-il maintenant ». Dès que quelqu'un demande « que s'est-il passé cette nuit », il faut du stockage. Le schéma courant consiste à garder le panneau en direct et à ajouter une seconde source de données :

• MQTT vers InfluxDB avec Telegraf : ingestion par simple configuration dans une base de séries temporelles.
• MQTT vers PostgreSQL / TimescaleDB : requêtes SQL et jointures avec les données métier.

Grafana affiche les deux sur le même dashboard : un stat MQTT en direct en haut, des graphiques historiques InfluxDB ou SQL en dessous. Si vous cherchez un dashboard purement navigateur, sans Grafana, consultez créer un dashboard MQTT en direct.

La source de données MQTT transforme un topic en panneau en direct en quelques minutes. Pointez-la vers un utilisateur de broker en lecture seule, gardez des payloads sous forme de nombres en JSON plat, vérifiez d'abord le flux avec un client MQTT et ajoutez une base de données dès que le dashboard doit se souvenir.

Questions fréquentes