MQTT Explorer: cómo inspeccionar y depurar un broker

MQTT Explorer es un cliente de escritorio gratuito que se suscribe a un broker y muestra todo lo que recibe como un árbol de topics vivo y plegable. Es la forma más rápida de responder a "¿qué hay realmente en este broker?": qué topics existen, cuáles tienen mensajes retenidos, qué cambió en el último payload y cómo evoluciona un valor en el tiempo. Esta guía cubre la instalación, la conexión segura y las funciones que importan al depurar.

Instalar MQTT Explorer

MQTT Explorer, de Thomas Nordquist, funciona en Windows, macOS y Linux. Descárgalo de mqtt-explorer.com o de las releases del proyecto en GitHub, o usa un gestor de paquetes:

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

# Linux (Snap)
sudo snap install mqtt-explorer

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

En Linux, la AppImage también funciona sin instalación. Los nombres de los paquetes pueden cambiar entre versiones; si alguno falla, descarga el build desde la página de releases.

Conectarse a un broker

El diálogo de conexión se abre al iniciar. Rellena:

Prefiere TLS siempre que haya credenciales de por medio: en el 1883 plano la contraseña viaja en texto claro. Deja Validate certificate activado; desactivarlo oculta problemas reales como un hostname que no coincide. Para un broker con una CA privada, añade el fichero de la CA en Advanced → Certificates.

En Advanced también puedes definir el MQTT Client ID. Dale un nombre reconocible como explorer-tunombre; si reutilizas el ID de un dispositivo en marcha, el broker desconecta a uno de los dos y perseguirás un bug fantasma ("session taken over"). El generador de client IDs te ayuda si necesitas uno único.

Genera algo que mirar

Para seguir la guía, publica unos cuantos mensajes en tu prefijo de prueba: mensajes de estado retenidos y un valor de telemetría que cambia:

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

Si no tienes instaladas las herramientas de mosquitto, puedes hacer lo mismo desde el navegador con el cliente MQTT online.

Leer el árbol de topics

El panel izquierdo construye la jerarquía a partir de los niveles del topic: testmqtt → explorer → device-1 → temperature. Cada nodo muestra cuántos subtopics y mensajes contiene, y los nodos se resaltan brevemente al llegar un mensaje nuevo, así que las ramas con actividad saltan a la vista.

Usa el árbol para revisar tu diseño de topics:

• Erratas y diferencias de mayúsculas se ven al instante: Device-1 y device-1 son ramas distintas, porque los topics MQTT distinguen mayúsculas y minúsculas.
• Barras al principio o al final crean un nivel vacío (/testmqtt/... tiene un nodo raíz en blanco).
• Profundidad inesperada: datos del payload codificados por error en el topic (.../temperature/21.5) aparecen como cientos de nodos hermanos.

El cuadro de búsqueda superior filtra el árbol por nombre de topic. Para comprobar cómo se comportaría una suscripción con wildcards frente a esos topics, usa el topic matcher. Más sobre estructura en topics y wildcards MQTT.

Inspeccionar valores, historial y diffs

Haz clic en un topic y la barra lateral muestra su valor más reciente, formateado como JSON si el payload se puede parsear, junto con el QoS, el flag de retenido y la hora de recepción. Debajo está el historial de mensajes recientes de ese topic.

Cuando un payload cambia, MQTT Explorer puede mostrar un diff respecto al mensaje anterior, de modo que un único campo modificado en un JSON grande resulta evidente. Es ideal para preguntas como "¿qué campo actualiza el firmware en cada informe?" o "¿cambió la configuración tras el despliegue?".

Para valores numéricos, ya sea un número suelto o un campo numérico dentro de un JSON, usa la opción de gráfico del historial para graficar el valor en el tiempo. Un patrón en diente de sierra, un sensor atascado o un valor que vuelve a cero tras cada reconexión se ven mucho mejor en un gráfico que en una lista de mensajes.

Encontrar y borrar mensajes retenidos

Los mensajes retenidos son la fuente más común de datos "fantasma": un dispositivo que lleva meses desconectado sigue apareciendo online porque su último estado retenido sigue en el broker. En MQTT Explorer, los mensajes retenidos se marcan en el panel de valor, así que puedes recorrer el árbol y ver qué topics guardan uno.

Para eliminarlo, selecciona el topic y pulsa el icono de borrar en la sección Topic. El cliente publica un mensaje retenido vacío en ese topic, que es la forma estándar de limpiarlo. Para una rama entera, usa el borrado recursivo. Dos advertencias:

• Tu usuario necesita permiso de publicación en esos topics. Si la ACL lo deniega, en muchos brokers el borrado no hace nada sin avisar; consulta ACL denegada en silencio.
• Un dispositivo que vuelve a publicar su estado retenido al reconectar hará que el mensaje reaparezca. Corrige el origen, no solo el broker.

Si un mensaje retenido sigue volviendo de todos modos, el mensaje retenido no se borra repasa el resto de causas.

Publicar mensajes de prueba

La sección Publish de la barra lateral envía un mensaje a cualquier topic, con un editor de payload (raw, JSON o XML) y opciones de QoS y retain. Al hacer clic en un topic del árbol, su nombre se rellena automáticamente, lo que facilita reenviar o retocar un mensaje existente; por ejemplo, enviar un comando a testmqtt/explorer/device-1/set y ver cómo cambia el topic de estado del dispositivo.

Vigilar $SYS para la salud del broker

Muchos brokers publican estadísticas bajo $SYS/: clientes conectados, tasas de mensajes, tiempo en marcha. Mantén la suscripción a $SYS/# si tu broker la soporta y grafica $SYS/broker/clients/connected o los contadores de carga mientras pruebas. Qué topics existen depende del broker; los topics $SYS de MQTT enumera los más comunes. Los servicios gestionados pueden restringir u omitir $SYS.

Problemas habituales

¿MQTT Explorer u otro cliente?

MQTT Explorer no tiene rival para explorar: árboles de topics, mensajes retenidos, diffs y gráficos rápidos. Está menos pensado para probar funciones de MQTT 5 o manejar muchas conexiones en paralelo; ahí MQTTX es más fuerte, y la comparativa de clientes MQTT de escritorio cubre el resto. Para una comprobación sin instalar nada desde cualquier equipo, usa el cliente del navegador.

Publica datos de prueba desde tu navegador

Ten MQTT Explorer abierto mientras desarrollas: apúntalo a un prefijo acotado sobre una conexión TLS, deja que el árbol te muestre lo que tus dispositivos publican de verdad y usa las vistas de diff, gráfico y retenidos para convertir "algo va mal" en un topic y un campo concretos. Complementa, sin sustituirlos, a los tests automatizados que comprueban lo mismo de forma automática.

Preguntas frecuentes