Leer los logs del broker MQTT para depurar clientes

Cuando un cliente dice connection lost, normalmente no tiene ni idea de por qué. El broker sí lo sabe. Cada login rechazado, timeout de keep-alive, client ID duplicado y publicación denegada deja una línea en el log del broker, siempre que el logging esté configurado para guardarla. Leer esas líneas suele ser la forma más rápida de depurar un cliente al que no puedes conectar un depurador.

Esta guía muestra dónde encontrar los logs, qué niveles de log activar, cómo leer las líneas de conexión y desconexión de Mosquitto, cómo trazar un cliente en EMQX y cómo convertir una línea de log en una solución.

Dónde están los logs

Si el archivo de log de Mosquitto se queda vacío, revisa la salida de arranque en busca de Error: Unable to open log file /var/log/mosquitto/mosquitto.log for writing.: el usuario del broker no puede escribir en el directorio. La configuración del logging en detalle está en logging de Mosquitto.

Activa el nivel de log adecuado

El logging por defecto de Mosquitto oculta casi todo lo que necesitas para depurar clientes. Una configuración útil mientras investigas:

log_dest stdout
log_dest file /var/log/mosquitto/mosquitto.log

log_type error
log_type warning
log_type notice
log_type information
log_type subscribe
log_type unsubscribe
# Cada paquete de entrada y salida: muy verboso, actívalo solo al depurar
log_type debug

connection_messages true
log_timestamp true
log_timestamp_format %Y-%m-%dT%H:%M:%S

Reinicia el broker después de cambiar las opciones de logging. connection_messages true genera las líneas de conexión y desconexión en las que se basa casi toda esta guía, y un formato de marca de tiempo legible te ahorra convertir segundos Unix a mano. Puedes generar una configuración completa con el generador de mosquitto.conf.

En EMQX 5, sube el nivel de consola de un contenedor con la variable de entorno EMQX_LOG__CONSOLE__LEVEL=debug, o cámbialo en caliente:

emqx ctl log set-level debug
# ...reproduce el problema...
emqx ctl log set-level warning

Leer las líneas de conexión de Mosquitto

Una conexión correcta produce dos líneas:

2026-10-17T09:12:01: New connection from 192.168.1.20:52144 on port 1883.
2026-10-17T09:12:01: New client connected from 192.168.1.20:52144 as sensor-01 (p2, c1, k60, u'alice').

El paréntesis final describe el paquete CONNECT:

Estos cuatro campos responden a muchas preguntas de golpe: ¿usa el cliente de verdad la versión de protocolo que crees?, ¿pide una sesión persistente?, ¿qué keep-alive ha configurado realmente?

Las líneas de desconexión y su significado

La línea que imprime Mosquitto cuando un cliente se va es la más útil de todo el log:

Cuando dos líneas con already connected, closing old connection se alternan cada pocos segundos, dos dispositivos se están disputando un client ID y reconectan en bucle. Genera ID únicos con el generador de client ID.

Seguir una sesión con nivel debug

Con log_type debug, Mosquitto registra cada paquete. Un suscriptor y un publicador en un topic de prueba se ven más o menos así (Mosquitto 2.x, abreviado):

Received SUBSCRIBE from sub-01
    testmqtt/logs/# (QoS 1)
sub-01 1 testmqtt/logs/#
Sending SUBACK to sub-01
Received PUBLISH from pub-01 (d0, q1, r0, m1, 'testmqtt/logs/a', ... (5 bytes))
Sending PUBACK to pub-01 (m1, rc0)
Sending PUBLISH to sub-01 (d0, q1, r0, m1, 'testmqtt/logs/a', ... (5 bytes))
Received PUBACK from sub-01 (Mid: 1, RC:0)

El paréntesis de las líneas PUBLISH se lee así: d = flag DUP, q = QoS, r = retain, m = message ID, y después el topic y el tamaño del payload. Si ves Received PUBLISH pero ningún Sending PUBLISH, el broker aceptó el mensaje pero no había ninguna suscripción que coincidiera: comprueba el topic filter con el topic matcher. Una línea Denied PUBLISH significa que una ACL lo bloqueó; es el caso tratado en ACL denegada en silencio.

Para reproducir un caso rápidamente, deja el log abierto en una terminal y genera tráfico desde otra:

# Terminal 1 — el lado del broker
docker logs -f mosquitto 2>&1 | grep --line-buffered -E 'sub-01|pub-01'

# Terminal 2 — el lado del cliente, con salida de depuración del cliente
mosquitto_sub -d -h localhost -i sub-01 -t 'testmqtt/logs/#' -q 1 &
mosquitto_pub -d -h localhost -i pub-01 -t 'testmqtt/logs/a' -q 1 -m 'hello'

-d hace que los clientes impriman su propio log de paquetes (Client sub-01 sending CONNECT, received CONNACK (0)), así puedes comparar ambas vistas línea por línea.

Trazar un cliente en EMQX

En un broker EMQX con mucho tráfico, el log de depuración global es demasiado ruidoso. Traza un solo cliente:

emqx ctl trace start client sensor-01 /tmp/sensor-01.log
# ...deja que el cliente conecte, publique y falle...
emqx ctl trace stop client sensor-01

El archivo de trace contiene los eventos de conexión, autenticación, suscripción, publicación y desconexión de ese cliente, incluido el motivo cuando el broker cierra la conexión. El dashboard tiene una página de log trace que hace lo mismo y permite descargar el resultado. También puedes trazar por topic o por IP del cliente cuando no sabes qué client ID se está portando mal.

Buscar y correlacionar

Unos pocos comandos cubren la mayoría de búsquedas en los logs:

# Todo sobre un cliente en la última hora
journalctl -u mosquitto --since "1 hour ago" | grep -F 'sensor-01'

# ¿Qué clientes dan timeout más a menudo?
grep -o 'Client [^ ]* has exceeded timeout' /var/log/mosquitto/mosquitto.log | sort | uniq -c | sort -rn

# Convertir una marca de tiempo Unix de una línea de log por defecto de Mosquitto
date -d @1792228321        # GNU date; en macOS: date -r 1792228321

Correlaciona la hora del broker con los logs del propio cliente. Si los relojes difieren, alinéalos con un evento que ambos lados vean, como el CONNACK.

Cuando no hay log del broker

Sin acceso a los logs del broker, construye la misma imagen desde el lado del cliente:

• Registra cada reason code que reporte tu librería y búscalo en los reason codes de MQTT explicados o en la herramienta de reason codes.
• Suscríbete a los topics $SYS del broker si están expuestos: los contadores de clientes conectados y de mensajes descartados suelen mostrar la misma tendencia que el log. Consulta monitorizar con topics $SYS.
• Reproduce el problema con el cliente MQTT online contra el mismo broker. Si ahí funciona, la causa está en el código o la red del dispositivo, no en el broker.

Confirma la solución en el log

Una línea de log también es tu prueba de aceptación. Tras un cambio, reproduce el escenario original y vigila el log: la línea has exceeded timeout o already connected ya no debería aparecer, y la línea New client connected debería mostrar los parámetros que pretendías (protocolo, flag clean, keep-alive). Después vuelve a desactivar el log de depuración.

El broker ve los errores de todos los clientes, pero solo los apunta si se lo pides. Configura los mensajes de conexión y una marca de tiempo legible, sube el nivel solo mientras investigas y aprende el puñado de líneas de desconexión: corresponden casi una a una con la solución.

Preguntas frecuentes