Grafana MQTT Datasource: Painéis com Streaming ao Vivo a Partir do Seu Broker

O plugin Grafana MQTT datasource permite que um dashboard assine topics do broker e desenhe os valores no instante em que são publicados, sem nenhum banco de dados no meio. Neste tutorial você vai instalar o plugin, conectá-lo ao servidor MQTT público (gratuito) broker.connectmq.com, montar painéis ao vivo a partir de payloads numéricos e JSON e entender exatamente quando vale a pena adicionar um banco de dados de séries temporais.

Como funciona o Grafana MQTT Datasource

A maioria dos data sources do Grafana é baseada em consultas: um painel pede a um banco de dados um intervalo de tempo e desenha o resultado. O data source MQTT é diferente. Ele é um data source de streaming construído sobre o Grafana Live. Quando um painel é aberto, o servidor do Grafana assina o topic que você especificou, e cada mensagem é enviada ao navegador por uma WebSocket e acrescentada ao gráfico.

Esse design tem duas consequências que você precisa entender antes de construir algo sério:

1. A latência é excelente. Um valor publicado por um dispositivo aparece no painel quase imediatamente, o que é ideal para comissionamento, demonstrações ao vivo e visões no estilo sala de controle.
2. Não há histórico. O plugin mostra apenas o que chegou enquanto o painel estava aberto. Recarregue o dashboard e o gráfico começa vazio. Não dá para afastar o zoom até ontem, porque ontem nunca foi armazenado.

Tenha os dois pontos em mente. O data source MQTT é uma janela para o fluxo ao vivo, não um registro dele.

Instale o plugin

O ID do plugin é grafana-mqtt-datasource. Em uma instalação nativa do Grafana:

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

Versões mais antigas do Grafana usam o binário grafana-cli em vez de grafana cli. Com Docker, deixe o contêiner instalá-lo na inicialização:

services:
  grafana:
    image: grafana/grafana:11.3.0
    ports:
      - "3000:3000"
    environment:
      GF_INSTALL_PLUGINS: grafana-mqtt-datasource
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

Execute docker compose up -d e abra http://localhost:3000. O login padrão é admin / admin, e o Grafana pede que você o altere.

Configure a conexão

No Grafana, vá em Connections, depois Data sources, depois Add data source, e pesquise por MQTT. A página de configurações pede uma URI e credenciais opcionais.

Clique em Save and test. Uma confirmação verde significa que o servidor do Grafana, e não o seu navegador, alcançou o broker. Essa distinção importa em redes restritas: o servidor precisa de acesso de saída à porta 1883 ou 8883. Se a sua versão do plugin exibir um campo de client ID e você se conectar a um broker MQTT gerenciado que vincula client IDs às credenciais, informe o client ID emitido junto com o seu usuário.

Publique alguns dados de teste

Escolha um prefixo único, como connectmq/demo/a1b2c3, para que seus topics de teste fiquem separados no servidor MQTT público. Este loop Bash publica uma temperatura numérica simples a cada dois segundos:

ID=a1b2c3
while true; do
  T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
  mosquitto_pub -h broker.connectmq.com -p 1883 -i "pub-$ID" \
    -t "connectmq/demo/$ID/room1/temperature" -m "$T"
  sleep 2
done

E este publica um objeto JSON com vários valores:

ID=a1b2c3
while true; do
  T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
  H=$(awk -v r=$RANDOM 'BEGIN { printf "%.1f", 40 + r / 32767 * 15 }')
  mosquitto_pub -h broker.connectmq.com -p 1883 -i "pubjson-$ID" \
    -t "connectmq/demo/$ID/room1/telemetry" \
    -m "{\"temperature\": $T, \"humidity\": $H}"
  sleep 2
done

Para muitos dispositivos ao mesmo tempo, rode o simulador de dispositivos MQTT em Python e aponte os painéis para os topics de cada dispositivo.

Monte um painel ao vivo com o Grafana MQTT Datasource

1. Crie um novo dashboard e adicione uma visualização.
2. Selecione o data source MQTT.
3. No editor de consultas, informe o topic, por exemplo connectmq/demo/a1b2c3/room1/temperature.
4. Escolha a visualização Time series. Os valores começam a aparecer em segundos.
5. Defina o intervalo de tempo do dashboard para algo curto, como os últimos 5 minutos. A atualização automática não é necessária, porque o painel está em streaming.

Para o topic JSON, o plugin transforma cada chave numérica do objeto em um campo próprio, então temperature e humidity viram duas séries no mesmo painel. Use field overrides para colocar a umidade em um eixo à direita ou dar a cada série a sua unidade. Os painéis Stat e Gauge funcionam bem para valores atuais únicos; defina o cálculo deles como "Last" para que sempre mostrem a leitura mais recente.

As versões recentes do plugin aceitam os curingas + e # no campo de topic, o que é prático para acompanhar um grupo de sensores em um único painel. Se a sua versão rejeitar curingas, adicione uma consulta por topic, já que cada painel pode conter várias consultas.

Problemas comuns e soluções

Quando adicionar um banco de dados de séries temporais

O data source de streaming é a ferramenta certa para um conjunto restrito de tarefas. Assim que você precisar de histórico, agregação ou alertas ao longo do tempo, coloque um banco de dados entre o broker e o Grafana.

Um padrão comum combina os dois: um painel apoiado em banco de dados para a tendência e um painel de streaming para o valor atual. O tutorial do Telegraf MQTT consumer mostra como gravar os mesmos topics no InfluxDB, e a stack TIG com Docker Compose entrega a stack completa em um único arquivo com dashboards provisionados. Quando existe histórico, os alertas do Grafana sobre dados de sensores IoT se tornam possíveis.

Observações para produção

O servidor MQTT público pode ser lido por qualquer pessoa, então use-o apenas para dados de teste. Para equipamentos reais, conecte o Grafana a um broker privado e protegido por TLS. Um broker MQTT gerenciado da ConnectMQ oferece TLS na porta 8883 e credenciais pelo portal, e o Grafana se conecta a ele como a qualquer outro cliente MQTT. Lembre-se de que cada conexão do servidor do Grafana conta para o limite de conexões do seu plano, que no plano Serverless (Free) é de 25.

Para casos de uso apenas no navegador, em que você não quer nenhum servidor Grafana, uma pequena página web usando MQTT sobre WebSocket na porta 8084 pode exibir os valores ao vivo diretamente. Para escolher a stack de cliente certa para isso ou para o código dos dispositivos, veja o guia de bibliotecas de cliente MQTT. A própria página do Grafana MQTT data source documenta as opções atuais do plugin.

Comece com a ConnectMQ

Aponte o plugin para o servidor MQTT público broker.connectmq.com e você terá um painel ao vivo em minutos. Quando o dashboard for mostrar dispositivos reais, rode o seu broker na ConnectMQ, onde você também conta com um cliente MQTT no navegador e um explorador de topics ao vivo para conferir os topics antes de ligar os painéis. Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito. Planejando uma implantação maior? Nosso guia sobre broker MQTT na nuvem explica o que muda em escala.

Perguntas frequentes

O Grafana MQTT datasource armazena dados?

Não. Ele transmite as mensagens para os painéis abertos por meio do Grafana Live e não guarda nada depois que o painel é fechado. Use um banco de dados de séries temporais como o InfluxDB quando precisar de histórico.

Posso usar curingas no campo de topic?

As versões recentes do plugin suportam + e #. Nas versões mais antigas, adicione uma consulta por topic.

Quais formatos de payload funcionam com o plugin?

Payloads numéricos simples e objetos JSON com valores numéricos funcionam melhor. Cada chave numérica do JSON vira um campo separado no painel.

O navegador se conecta diretamente ao broker?

Não. O servidor do Grafana mantém a conexão MQTT e repassa os dados aos navegadores pelo Grafana Live, então apenas o servidor precisa de acesso de rede ao broker.