Skip to main content
Version: Mosquitto 3.0

System Topics

A basic monitoring of the Mosquitto broker is possible by observing so-called "System topics". Clients can find information about the broker by subscribing to topics in the $SYS hierarchy as follows. Topics marked as static are only sent once per client on subscription. All other topics are updated every sys_interval seconds. If sys_interval is 0, then updates are not sent.

System topic description​

$SYS/broker/bytes/received​

The total number of bytes received since the broker started.

$SYS/broker/bytes/sent​

The total number of bytes sent since the broker started.

$SYS/broker/clients/connected,​

$SYS/broker/clients/active (deprecated)

The number of currently connected clients.

$SYS/broker/clients/expired​

The number of disconnected persistent clients that have been expired and removed through the persistent\_client\_expiration option.

$SYS/broker/clients/disconnected,​

$SYS/broker/clients/inactive (deprecated)

The total number of persistent clients (with clean session disabled) that are registered at the broker but are currently disconnected.

$SYS/broker/clients/maximum​

The maximum number of clients that have been connected to the broker at the same time.

$SYS/broker/clients/total​

The total number of active and inactive clients currently connected and registered on the broker.

$SYS/broker/connection/#​

When bridges are configured to/from the broker, common practice is to provide a status topic that indicates the state of the connection. This is provided within $SYS/broker/connection/ by default. If the value of the topic is 1 the connection is active, if 0 then it is not active. See the Bridges section below for more information on bridges.

$SYS/broker/heap/current size​

The current size of the heap memory in use by mosquitto. Note that this topic may be unavailable depending on compile time options.

$SYS/broker/heap/maximum size​

The largest amount of heap memory used by mosquitto. Note that this topic may be unavailable depending on compile time options.

$SYS/broker/load/connections/+​

The moving average of the number of CONNECT packets received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of connections received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/bytes/received/+​

The moving average of the number of bytes received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/bytes/sent/+​

The moving average of the number of bytes sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes sent in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/messages/sent/+​

The moving average of the number of all types of MQTT messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages send in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/messages/received/+​

The moving average of the number of all types of MQTT messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/dropped/+​

The moving average of the number of publish messages dropped by the broker over different time intervals. This shows the rate at which durable clients that are disconnected are losing messages. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages dropped in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/received/+​

The moving average of the number of publish messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/sent/+​

The moving average of the number of publish messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages sent in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/sockets/+​

The moving average of the number of socket connections opened to the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of socket connections in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/messages/inflight​

The number of messages with QoS>0 that are awaiting acknowledgments.

$SYS/broker/messages/received​

The total number of messages of any type received since the broker started.

$SYS/broker/messages/sent​

The total number of messages of any type sent since the broker started.

$SYS/broker/publish/messages/dropped​

The total number of publish messages that have been dropped due to inflight/queuing limits. See the max\_inflight\_messages and max\_queued\_messages options in [Mosquitto Configuration] (NEW_mosquitto-configuration.md) for more information.

$SYS/broker/publish/messages/received​

The total number of PUBLISH messages received since the broker started.

$SYS/broker/publish/messages/sent​

The total number of PUBLISH messages sent since the broker started.

$SYS/broker/retained messages/count​

The total number of retained messages active on the broker.

$SYS/broker/store/messages/count,​

$SYS/broker/messages/stored (deprecated)

The number of messages currently held in the message store. This includes retained messages and messages queued for durable clients.

$SYS/broker/store/messages/bytes​

The number of bytes currently held by message payloads in the message store. This includes retained messages and messages queued for durable clients.

$SYS/broker/subscriptions/count​

The total number of subscriptions active on the broker.

$SYS/broker/version​

The version of the broker. Static.

Topics marked as static are only sent once per client on subscription. All other topics are updated every sys_interval seconds. If sys_interval is 0, then updates are not sent.

note

Note that if you are using a command line client to interact with the $SYS topics and your shell interprets $ as an environment variable, you need to place the topic in single quotes '$SYS/...' or to escape the dollar symbol: \\$SYS/... otherwise the $SYS will be treated as an environment variable.