Documentation › Broker 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 (clean and unexpected)
  • 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

  1. Click Logs in the left sidebar.
  2. 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:

  • 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

  • By level - select one or more log levels to display.
  • By content - enter text to search within log messages. For example, enter a client ID to see only 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.

Understanding Common Log Entries

Client connected

New connection from 192.168.1.50 on port 1900.
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 cleanly

Client sensor-kitchen-01 disconnected.

Normal disconnection initiated by the client.

Client disconnected unexpectedly

Client sensor-kitchen-01 has exceeded timeout, disconnecting.

Client missed keep-alive pings. May indicate a network issue or a crashed device.

Authentication failure

Client sensor-bad disconnected, not authorised.

The client provided invalid credentials or was disabled.

ACL violation

Client sensor-01 not authorised to publish to private/topic.

A client attempted to publish or subscribe to a topic its roles do not permit.

Broker startup

mosquitto version 2.0.x starting
Config loaded from /etc/mosquitto/mosquitto.conf.

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. Also check ACL > Clients to confirm the account is enabled.
  • Unexpected disconnects - search for the client ID and look for timeout messages. 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.

Downloading Logs

To save broker logs for offline analysis, apply any filters you want (time range, level) and click Download or Export. A log file is downloaded in plain text format. Useful for sharing with support or archiving audit trails.

Log Retention

Broker logs are stored in a rotating log file inside the container. 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.

← Agents Client Logs →