MQTT Explorer: como inspecionar e depurar um broker

O MQTT Explorer é um cliente desktop gratuito que se inscreve em um broker e mostra tudo o que recebe como uma árvore de topics ao vivo e recolhível. É o jeito mais rápido de responder "o que de fato está neste broker?": quais topics existem, quais guardam mensagens retidas, o que mudou no último payload e como um valor evolui ao longo do tempo. Este guia cobre a instalação, a conexão segura e os recursos que importam na depuração.

Instalar o MQTT Explorer

O MQTT Explorer, de Thomas Nordquist, roda em Windows, macOS e Linux. Baixe em mqtt-explorer.com ou nas releases do projeto no GitHub, ou use um gerenciador de pacotes:

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

# Linux (Snap)
sudo snap install mqtt-explorer

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

No Linux, a AppImage também funciona sem instalação. Os nomes dos pacotes podem mudar entre versões; se algum falhar, pegue o build na página de releases.

Conectar a um broker

A janela de conexão abre ao iniciar. Preencha:

Prefira TLS sempre que houver credenciais envolvidas — na 1883 pura a senha trafega em texto claro. Deixe Validate certificate ligado; desligá-lo esconde problemas reais, como um hostname que não confere. Para um broker com CA privada, adicione o arquivo da CA em Advanced → Certificates.

Em Advanced você também define o MQTT Client ID. Dê um nome reconhecível como explorer-seunome; se você reutilizar o ID de um dispositivo em funcionamento, o broker desconecta um dos dois e você vai caçar um bug fantasma ("session taken over"). O gerador de client IDs ajuda se você precisar de um único.

Gere algo para observar

Para acompanhar, publique algumas mensagens no seu prefixo de teste — mensagens de status retidas e um valor de telemetria que muda:

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

Se você não tem as ferramentas do mosquitto instaladas, dá para fazer o mesmo no navegador com o cliente MQTT online.

Ler a árvore de topics

O painel esquerdo monta a hierarquia a partir dos níveis do topic: testmqtt → explorer → device-1 → temperature. Cada nó mostra quantos subtopics e mensagens contém, e os nós piscam rapidamente quando chega uma mensagem nova, então ramos movimentados ficam fáceis de notar.

Use a árvore para revisar seu design de topics:

• Erros de digitação e diferenças de maiúsculas aparecem na hora — Device-1 e device-1 são ramos separados, porque topics MQTT diferenciam maiúsculas de minúsculas.
• Barras no início ou no fim criam um nível vazio (/testmqtt/... tem um nó raiz em branco).
• Profundidade inesperada — dados do payload codificados por engano no topic (.../temperature/21.5) aparecem como centenas de nós irmãos.

A caixa de busca no topo filtra a árvore pelo nome do topic. Para verificar como uma inscrição com wildcards se comportaria com esses topics, use o topic matcher. Mais sobre estrutura em topics e wildcards MQTT.

Inspecionar valores, histórico e diffs

Clique em um topic e a barra lateral mostra o valor mais recente, formatado como JSON quando o payload é válido, junto com QoS, flag de retida e horário de recebimento. Abaixo fica o histórico das mensagens recentes daquele topic.

Quando um payload muda, o MQTT Explorer pode mostrar um diff em relação à mensagem anterior, deixando óbvio um único campo alterado em um JSON grande. Isso é ideal para perguntas como "qual campo o firmware atualiza a cada envio?" ou "a configuração mudou depois do deploy?".

Para valores numéricos — um número simples ou um campo numérico dentro de um JSON — use a opção de gráfico do histórico para plotar o valor ao longo do tempo. Um padrão dente de serra, um sensor travado ou um valor que volta a zero a cada reconexão ficam muito mais visíveis em um gráfico do que em uma lista de mensagens.

Encontrar e apagar mensagens retidas

Mensagens retidas são a fonte mais comum de dados "fantasma": um dispositivo offline há meses continua aparecendo online porque seu último status retido ainda está no broker. No MQTT Explorer, as mensagens retidas são marcadas no painel de valor, então você pode percorrer a árvore e ver quais topics guardam uma.

Para removê-la, selecione o topic e clique no ícone de excluir na seção Topic. O cliente publica uma mensagem retida vazia nesse topic, que é a forma padrão de limpá-la. Para um ramo inteiro, use a exclusão recursiva. Dois cuidados:

• Seu usuário precisa de permissão de publicação nesses topics. Se a ACL negar, em muitos brokers a exclusão simplesmente não faz nada, sem aviso — veja ACL negada silenciosamente.
• Um dispositivo que republica seu estado retido ao reconectar traz a mensagem de volta. Corrija a origem, não só o broker.

Se uma mensagem retida continua voltando mesmo assim, mensagem retida que não some passa pelas demais causas.

Publicar mensagens de teste

A seção Publish da barra lateral envia uma mensagem para qualquer topic, com editor de payload (raw, JSON ou XML) e opções de QoS e retain. Clicar em um topic na árvore preenche o nome automaticamente, o que torna rápido reenviar ou ajustar uma mensagem existente — por exemplo, mandar um comando para testmqtt/explorer/device-1/set e ver o topic de status do dispositivo mudar.

Acompanhar o $SYS para a saúde do broker

Muitos brokers publicam estatísticas em $SYS/ — clientes conectados, taxas de mensagens, uptime. Mantenha a inscrição em $SYS/# se o seu broker suportar e plote $SYS/broker/clients/connected ou os contadores de carga enquanto testa. Quais topics existem depende do broker; topics $SYS do MQTT lista os mais comuns. Serviços gerenciados podem restringir ou omitir o $SYS.

Problemas comuns

MQTT Explorer ou outro cliente?

O MQTT Explorer é imbatível para navegar: árvores de topics, mensagens retidas, diffs e gráficos rápidos. Ele é menos indicado para testar recursos do MQTT 5 ou lidar com muitas conexões em paralelo — ali o MQTTX é mais forte, e a comparação de clientes MQTT desktop cobre o resto. Para uma verificação sem instalar nada, de qualquer máquina, use o cliente no navegador.

Publique dados de teste pelo navegador

Mantenha o MQTT Explorer aberto enquanto desenvolve: aponte-o para um prefixo restrito em uma conexão TLS, deixe a árvore mostrar o que seus dispositivos realmente publicam e use as visões de diff, gráfico e retidas para transformar "algo está errado" em um topic e um campo específicos. Ele complementa — não substitui — os testes automatizados que verificam as mesmas coisas.

Perguntas frequentes