Grafana puede suscribirse directamente a un broker MQTT. Con el plugin oficial MQTT data source (grafana-mqtt-datasource), cada consulta de un panel es una suscripción a un topic, y los mensajes nuevos aparecen en el dashboard pocos instantes después de publicarse, sin ninguna base de datos de por medio. Es la forma más rápida de poner un gauge o un gráfico en vivo delante de datos de sensores.
Este tutorial instala el plugin, lo conecta a un broker por TLS, publica telemetría de prueba y construye paneles en vivo. También cubre lo que la gente suele descubrir demasiado tarde: el data source transmite, no almacena.
Cómo funciona el MQTT data source
El plugin se ejecuta dentro del servidor de Grafana. Cuando un panel pide datos, el backend abre una conexión MQTT (una por data source), se suscribe al topic de la consulta y reenvía cada mensaje al navegador a través de Grafana Live, el canal de streaming por WebSocket de Grafana.
| Aspecto | Comportamiento |
|---|---|
| Transporte al broker | MQTT sobre TCP o TLS desde el servidor de Grafana (no desde el navegador) |
| Transporte al navegador | Grafana Live (WebSocket), basado en push: no hace falta refrescar el dashboard |
| Parseo del payload | Los objetos JSON se convierten en campos; un número simple se convierte en un único campo de valor |
| Historial | Ninguno: solo los mensajes recibidos mientras el panel está abierto |
| Ideal para | Vistas de operación en vivo, puesta en marcha, demos, depuración |
Como el servidor de Grafana es el cliente MQTT, el broker debe ser accesible desde donde se ejecute Grafana, y las credenciales viven en la configuración del data source, no en el navegador.
Ejecuta Grafana con el plugin
La forma más rápida es Docker. El plugin se instala al arrancar desde el catálogo de plugins de Grafana:
docker run -d --name grafana -p 3000:3000 \
-e GF_INSTALL_PLUGINS=grafana-mqtt-datasource \
grafana/grafana:latestEn las versiones recientes de Grafana, GF_PLUGINS_PREINSTALL=grafana-mqtt-datasource es la forma más nueva de pedir lo mismo. En una instalación existente, usa la CLI y reinicia el servicio:
grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-serverAbre http://localhost:3000, inicia sesión (por defecto admin / admin, y luego cámbiala) y ve a Connections → Data sources → Add data source → MQTT.
Conecta el data source a tu broker
La página de configuración pide una URI, credenciales opcionales y opciones TLS:
- URI:
tcp://broker.connectmq.com:1883para una prueba rápida sin cifrar,tls://broker.connectmq.com:8883para TLS (algunas versiones del plugin también aceptanssl://). Usa TLS para cualquier cosa que no sea una demo. - Username / Password: las credenciales de tu broker. Con ACLs por topic, da a este usuario acceso de solo lectura a los topics que necesitan los dashboards.
- TLS: activa "With CA Cert" si tu broker usa una CA privada, o la autenticación con certificado de cliente para mTLS.
Haz clic en Save & test. Una prueba correcta significa que el servidor de Grafana pudo abrir una conexión MQTT. Si falla, el error es el CONNACK del broker o un error de red: consulta errores de conexión MQTT y busca los códigos con la herramienta de reason codes.
Para configuraciones repetibles, aprovisiona el data source desde un archivo en lugar de hacer clic:
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 expande las variables de entorno en los archivos de aprovisionamiento, así que la contraseña nunca acaba en Git. Los nombres de los campos pueden variar un poco entre versiones del plugin; si se ignora un valor, configúralo una vez en la interfaz y compáralo con el README del plugin.
Publica telemetría de prueba
Un panel solo muestra los mensajes que llegan mientras está abierto, así que necesitas un flujo constante para diseñar. Este script con paho-mqtt 2.x publica una lectura JSON cada segundo:
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() # almacén de CA del sistema
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)Antes de tocar Grafana, confirma el flujo con el cliente MQTT online: suscríbete a testmqtt/grafana/# y observa cómo llegan los mensajes. Si aparecen ahí pero no en Grafana, el problema está en el data source, no en el publicador.
Mira la telemetría de prueba en tu navegador
Crea paneles en vivo
Crea un dashboard, añade una visualización y selecciona el data source MQTT. El editor de consultas tiene un campo importante, Topic: escribe testmqtt/grafana/room1/telemetry.
- Time series: la opción por defecto. Cada clave JSON (
temperature,humidity,battery) se convierte en una serie. Pon el rango de tiempo del dashboard en Last 5 minutes para que el gráfico se desplace en lugar de comprimirse. - Gauge: cambia la visualización, pon Calculation en Last y elige el campo
temperatureen Fields. Añade umbrales (verde por debajo de 25, rojo por encima de 28). - Stat: buena opción para
battery; usa Last y la unidad de porcentaje.
Si solo quieres un campo en un panel, usa la transformación Organize fields o Filter fields by name en lugar de publicar topics separados.
Formatos de payload que funcionan
| Payload | Resultado en Grafana |
|---|---|
23.5 | Un campo numérico (value) |
{"temperature": 23.5, "humidity": 41} | Dos campos numéricos |
{"env": {"temp": 23.5}} | Las claves anidadas se aplanan en nombres de campo |
{"status": "ok"} | Un campo de texto: sirve para una tabla, no para un gráfico |
| Binario, CBOR, Protobuf | No se parsea: decodifícalo antes |
La marca de tiempo es el momento en que Grafana recibió el mensaje, no un campo de tiempo dentro de tu payload. Si los dispositivos almacenan en buffer y envían tarde, el gráfico mostrará la hora de llegada; consulta problemas de timestamps.
Wildcards y muchos dispositivos
Las versiones recientes del plugin aceptan + y # en el campo de topic, así que testmqtt/grafana/+/telemetry puede alimentar un panel con todas las salas. Comprueba qué topics coincidirán con un filtro usando el topic matcher antes de guardarlo: un # descuidado en un broker con mucho tráfico envía al navegador muchos más datos de los que un panel puede dibujar. Para flotas grandes, prefiere un panel por grupo de dispositivos, o agrega en el dispositivo y publica un topic de resumen. Consulta topics y wildcards para diseñar topics que los dashboards puedan filtrar con limpieza.
Solución de problemas
- "No data" en un panel nuevo: no se ha publicado nada desde que se abrió el panel. El plugin no reproduce mensajes antiguos, y los mensajes retenidos solo ayudan si el publicador activa el flag retain. Arranca el publicador de prueba y espera un segundo.
- Save & test falla: comprueba que el servidor de Grafana (o el contenedor) puede llegar al broker:
docker exec grafana nc -vz broker.connectmq.com 8883. Las reglas de salida corporativas suelen bloquear el 8883 aunque tu portátil sí pueda conectarse. - Los datos aparecen y luego se detienen: otro cliente con el mismo client ID está desconectando a Grafana, o el usuario no tiene permiso de lectura y el broker descarta la suscripción en silencio. Revisa los logs del broker y verifica las ACLs.
- Los números aparecen como texto: el publicador envía
"23.5"entre comillas. Corrige el payload o añade una transformación Convert field type. - El panel va con retraso o la pestaña se congela: el filtro de topic es demasiado amplio o los dispositivos publican más rápido de lo necesario. Reduce la frecuencia de publicación o agrega primero.
Cuando necesitas historial
El MQTT data source es perfecto para "qué está pasando ahora mismo". En cuanto alguien pregunta "qué pasó anoche", necesitas almacenamiento. El patrón habitual es mantener el panel en vivo y añadir un segundo data source:
- MQTT a InfluxDB con Telegraf: ingesta solo con configuración en una base de datos de series temporales.
- MQTT a PostgreSQL / TimescaleDB: consultas SQL y joins con datos de negocio.
Grafana puede mostrar ambos en el mismo dashboard: un stat MQTT en vivo arriba y gráficos históricos de InfluxDB o SQL debajo. Si buscas un dashboard solo de navegador sin Grafana, consulta cómo crear un dashboard MQTT en vivo.
El MQTT data source convierte un topic en un panel en vivo en minutos. Apúntalo a un usuario de broker de solo lectura, mantén los payloads como números en JSON plano, verifica primero el flujo con un cliente MQTT y añade una base de datos cuando el dashboard necesite recordar.
Preguntas frecuentes
¿El MQTT data source de Grafana guarda historial?
No. Se suscribe a topics y transmite los mensajes nuevos a los paneles mediante Grafana Live. Los datos solo viven en el buffer del navegador, así que al recargar la página empieza vacío. Para tener historial, escribe los datos MQTT en una base de datos como InfluxDB o TimescaleDB y consulta esa base.
¿Puedo usar wildcards en el campo de topic de Grafana MQTT?
Las versiones recientes del plugin aceptan los wildcards + y #. Las versiones antiguas solo se suscriben a topics exactos. Si una consulta con wildcard no muestra datos, actualiza el plugin o consulta primero un topic concreto para confirmar que la conexión funciona.
¿Por qué mi panel de Grafana MQTT muestra 'No data'?
Normalmente el topic no coincide con lo que publican los dispositivos, no se está publicando nada en ese momento (el plugin solo muestra mensajes nuevos) o el payload no es JSON ni un número simple. Publica un mensaje de prueba desde un cliente MQTT con el panel abierto para acotar el problema.
