Visualize dados MQTT no Grafana com o MQTT Data Source

O Grafana consegue se inscrever diretamente em um broker MQTT. Com o plugin oficial MQTT data source (grafana-mqtt-datasource), cada consulta de painel é uma assinatura de topic, e as mensagens novas aparecem no dashboard poucos instantes depois de publicadas, sem banco de dados no meio. É a forma mais rápida de colocar um gauge ou gráfico ao vivo na frente de dados de sensores.

Este tutorial instala o plugin, conecta-o a um broker via TLS, publica telemetria de teste e monta painéis ao vivo. Também cobre o que as pessoas costumam descobrir tarde demais: o data source transmite, ele não armazena.

Como o MQTT data source funciona

O plugin roda dentro do servidor do Grafana. Quando um painel pede dados, o backend abre uma conexão MQTT (uma por data source), assina o topic da consulta e encaminha cada mensagem ao navegador pelo Grafana Live, o canal de streaming via WebSocket do Grafana.

Como o servidor do Grafana é o cliente MQTT, o broker precisa estar acessível de onde o Grafana roda, e as credenciais ficam nas configurações do data source, não no navegador.

Rode o Grafana com o plugin

O jeito mais rápido é com Docker. O plugin é instalado na inicialização a partir do catálogo de plugins do Grafana:

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

Nas versões recentes do Grafana, GF_PLUGINS_PREINSTALL=grafana-mqtt-datasource é a forma mais nova de pedir a mesma coisa. Em uma instalação existente, use a CLI e reinicie o serviço:

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

Abra http://localhost:3000, faça login (padrão admin / admin, depois troque a senha) e vá em Connections → Data sources → Add data source → MQTT.

Conecte o data source ao seu broker

A página de configuração pede uma URI, credenciais opcionais e opções de TLS:

• URI: tcp://broker.connectmq.com:1883 para um teste rápido sem criptografia, tls://broker.connectmq.com:8883 para TLS (algumas versões do plugin também aceitam ssl://). Use TLS para tudo que não seja demo.
• Username / Password: as credenciais do seu broker. Com ACLs por topic, dê a esse usuário acesso somente leitura aos topics de que os dashboards precisam.
• TLS: ative "With CA Cert" se o seu broker usa uma CA privada, ou a autenticação por certificado de cliente para mTLS.

Clique em Save & test. Um teste bem-sucedido significa que o servidor do Grafana conseguiu abrir uma conexão MQTT. Se falhar, o erro é o CONNACK do broker ou um erro de rede: veja erros de conexão MQTT e consulte os códigos com a ferramenta de reason codes.

Para setups reproduzíveis, provisione o data source a partir de um arquivo em vez de clicar:

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}

O Grafana expande variáveis de ambiente nos arquivos de provisionamento, então a senha nunca vai parar no Git. Os nomes dos campos podem variar um pouco entre versões do plugin; se um valor for ignorado, configure-o uma vez pela interface e compare com o README do plugin.

Publique telemetria de teste

Um painel só mostra mensagens que chegam enquanto ele está aberto, então você precisa de um fluxo constante para trabalhar. Este script com paho-mqtt 2.x publica uma leitura JSON por 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()                       # repositório de CAs do 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 mexer no Grafana, confirme o fluxo com o cliente MQTT online: assine testmqtt/grafana/# e veja as mensagens chegarem. Se elas aparecem ali mas não no Grafana, o problema está no data source, não no publicador.

Veja a telemetria de teste no navegador

Monte painéis ao vivo

Crie um dashboard, adicione uma visualização e selecione o data source MQTT. O editor de consultas tem um campo importante, Topic: digite testmqtt/grafana/room1/telemetry.

1. Time series: o padrão. Cada chave JSON (temperature, humidity, battery) vira uma série. Defina o intervalo de tempo do dashboard como Last 5 minutes para que o gráfico role em vez de se comprimir.
2. Gauge: troque a visualização, defina Calculation como Last e escolha o campo temperature em Fields. Adicione thresholds (verde abaixo de 25, vermelho acima de 28).
3. Stat: bom para battery; use Last e a unidade de porcentagem.

Se você quer apenas um campo em um painel, use a transformação Organize fields ou Filter fields by name em vez de publicar topics separados.

Formatos de payload que funcionam

O timestamp é o momento em que o Grafana recebeu a mensagem, não um campo de tempo dentro do seu payload. Se os dispositivos fazem buffer e enviam atrasado, o gráfico vai mostrar a hora de chegada; veja problemas de timestamp.

Wildcards e muitos dispositivos

As versões recentes do plugin aceitam + e # no campo de topic, então testmqtt/grafana/+/telemetry pode alimentar um painel com todas as salas. Verifique quais topics um filtro vai casar com o topic matcher antes de salvar: um # solto em um broker movimentado manda para o navegador muito mais dados do que um painel consegue desenhar. Para frotas grandes, prefira um painel por grupo de dispositivos, ou agregue no dispositivo e publique um topic de resumo. Veja topics e wildcards para desenhar topics que os dashboards consigam filtrar com clareza.

Solução de problemas

• "No data" em um painel novo: nada foi publicado desde que o painel abriu. O plugin não reproduz mensagens antigas, e mensagens retidas só ajudam se o publicador ativar a flag retain. Inicie o publicador de teste e espere um segundo.
• Save & test falha: verifique se o servidor do Grafana (ou o container) alcança o broker: docker exec grafana nc -vz broker.connectmq.com 8883. Regras de saída corporativas muitas vezes bloqueiam a 8883 mesmo quando seu notebook conecta.
• Os dados aparecem e depois param: outro cliente com o mesmo client ID está derrubando o Grafana, ou o usuário não tem permissão de leitura e o broker descarta a assinatura silenciosamente. Olhe os logs do broker e confira as ACLs.
• Números aparecem como texto: o publicador envia "23.5" entre aspas. Corrija o payload ou adicione uma transformação Convert field type.
• Painel atrasado ou aba travando: o filtro de topic é amplo demais ou os dispositivos publicam mais rápido do que o necessário. Reduza a taxa de publicação ou agregue antes.

Quando você precisa de histórico

O MQTT data source é perfeito para "o que está acontecendo agora". Assim que alguém pergunta "o que aconteceu ontem à noite", você precisa de armazenamento. O padrão comum é manter o painel ao vivo e adicionar um segundo data source:

• MQTT para InfluxDB com Telegraf: ingestão só com configuração em um banco de séries temporais.
• MQTT para PostgreSQL / TimescaleDB: consultas SQL e joins com dados de negócio.

O Grafana mostra os dois no mesmo dashboard: um stat MQTT ao vivo no topo e gráficos históricos do InfluxDB ou SQL embaixo. Se você procura um dashboard só no navegador, sem Grafana, veja como montar um dashboard MQTT ao vivo.

O MQTT data source transforma um topic em um painel ao vivo em minutos. Aponte-o para um usuário de broker somente leitura, mantenha os payloads como números em JSON plano, verifique o fluxo com um cliente MQTT primeiro e adicione um banco de dados quando o dashboard precisar lembrar.

Perguntas frequentes