Operations and Debugging
Why MQTT Devices Still Need Local Logs
When an MQTT device works, logging feels unnecessary. Values arrive at the broker, dashboards update, and everything looks fine. The need appears when data stops. A server can tell you that no message arrived; it cannot always tell you whether the device lost Wi-Fi, failed authentication, rebooted, or could not read the sensor.
The limit of server-side logs
Server logs only show events that reached the server. If a device never connected, the most important clue may exist only on the device. In real installations, that device may be inside a case, on a ceiling, or in a cabinet where attaching a USB serial cable is inconvenient.
Minimum useful logs
- Boot count and last boot time.
- Reset reason when available.
- Wi-Fi connection failures and RSSI.
- MQTT connection failure codes.
- Last successful publish time.
- Sensor read failure count.
- Firmware version.
Use a small ring buffer
ESP devices do not need huge log files. A ring buffer with the latest 20 or 50 events is often enough. Store time, event code, and one short value. This gives field diagnostics without turning the device into a server.
| Event | Example value | What it tells you |
|---|---|---|
| BOOT | power_on | The device restarted |
| WIFI_OK | -58dBm | Signal is usable |
| MQTT_FAIL | auth | Broker credentials may be wrong |
| SENSOR_FAIL | timeout | Wiring or sensor may be bad |
| PUBLISH_OK | timestamp | Last known successful delivery |
How to read the logs
A small local status page is often the most practical approach. On the same network, opening the device IP can show Wi-Fi status, MQTT state, firmware version, and recent events. Devices with OLED screens can show short status codes. Devices with only LEDs can still use blink patterns to distinguish Wi-Fi, MQTT, and sensor failures.
What to send to the server
Send long-term health indicators to the server: firmware version, reboot count, last publish time, battery voltage, and consecutive failure count. Keep detailed recent events locally. Do not publish secrets, Wi-Fi credentials, tokens, or unnecessary internal network details.
Field example
If a temperature node disappears for six hours, the server only shows missing data. Local logs can immediately separate likely causes. Repeated BOOT events point to power. WIFI_FAIL points to signal or router changes. MQTT_FAIL auth points to credentials. SENSOR_FAIL with normal Wi-Fi points to wiring or the sensor itself.
The goal of local logging is not to store everything. The goal is to decide the next field action without guessing.