Logs - Broker Logs
Broker Logs show the raw event stream from the Mosquitto MQTT broker. Every connection attempt, subscription, authentication failure, and broker error is recorded here. Use broker logs as your primary tool for troubleshooting broker-level issues.
What Broker Logs Show
Broker logs capture events generated directly by Mosquitto:
- Client connections and disconnections (including clean and unexpected disconnects)
- Authentication successes and failures
- Subscription and unsubscription events
- Message delivery events at higher log levels
- Broker startup and shutdown events
- Configuration errors and warnings
- TLS/SSL errors
- Internal broker errors
These are the same logs Mosquitto would write to its log file, surfaced directly in the BunkerM web UI.
How to Access Broker Logs
- Click Logs in the left sidebar.
- Select Broker Logs.
The log viewer shows the most recent log entries. New entries appear as they are generated by Mosquitto.
Log Levels
Mosquitto uses several log levels. The broker logs page shows all levels by default, and you can filter by level:
| Level | Description |
|---|---|
| ERROR | Something went wrong that may affect broker operation |
| WARNING | Non-critical issue that should be investigated |
| NOTICE | Significant events like client connections and disconnections |
| INFORMATION | General informational events |
| DEBUG | Detailed diagnostic information (very verbose, usually disabled in production) |
The active log level is configured in Settings > Broker. Only events at or above the configured level are recorded.
Filtering Logs
Use the filter controls at the top of the log viewer to narrow down what you see:
By level - Select one or more log levels to display (ERROR, WARNING, NOTICE, etc.).
By content - Enter text to search within log messages. For example, enter a client ID to see only log entries mentioning that client.
By time range - Restrict the view to a specific time window.
Filters apply in real time to the displayed entries. The underlying log data is not affected by filtering.
Understanding Common Log Entries
Client connected
1700000000: New connection from 192.168.1.50 on port 1900.
1700000000: New client connected from 192.168.1.50 as sensor-kitchen-01 (p2, c1, k60, u'sensor').
Shows the IP address, client ID, protocol version (p2=MQTT 3.1.1), clean session flag (c1=clean), keep-alive interval (k60), and username.
Client disconnected (clean)
Normal disconnection initiated by the client.
Client disconnected (unexpected)
Client missed keep-alive pings. May indicate a network issue or a crashed device.
Authentication failure
1700000002: Client <unknown> disconnected due to protocol error.
1700000002: Client sensor-bad disconnected, not authorised.
The client provided invalid credentials or was disabled. Authentication failures appear at WARNING or NOTICE level depending on Mosquitto version.
Subscription
A client subscribed to a topic pattern.
Broker startup
1700000000: mosquitto version 2.0.x starting
1700000000: Config loaded from /etc/mosquitto/mosquitto.conf.
1700000000: Starting in local only mode. Connections will only be possible from clients running on this machine.
Shown when the broker starts. "local only mode" is not shown if listener is configured with a bind address or allow_anonymous.
Downloading and Exporting Logs
To save broker logs for offline analysis:
- Open the Broker Logs page.
- Apply any filters you want (time range, level, etc.).
- Click Download or Export.
- A log file is downloaded in plain text format.
This is useful for sharing logs with support, archiving audit trails, or running external analysis tools.
Troubleshooting with Broker Logs
Client cannot connect - Look for entries with the client ID and check for "not authorised", "bad username or password", or protocol errors. - Check that the client is not disabled in ACL > Clients.
Unexpected disconnects - Search for the client ID and look for timeout messages or unexpected disconnect events. - Compare the keep-alive interval in the connect log entry against your client's configured keep-alive.
High error rate - Filter to ERROR level only. Repeated errors from the same source point to a specific issue.
Performance investigation - Enable DEBUG logging temporarily in Settings > Broker. Note that DEBUG logging is very verbose and may impact broker performance.
ACL violations - Look for "not authorised" entries after a connection. These indicate a client is being blocked from publishing or subscribing due to ACL rules.
Log Retention
Broker logs are stored in a rotating log file inside the container. Log retention depends on the configured log file size and rotation settings. With persistent volumes, logs survive container restarts.
If you need longer retention or external log aggregation, configure Mosquitto's log file path to write to a bind-mounted directory, or forward logs to an external system.