System Topic

EMQX periodically publishes its running status, message statistics, client online and offline events to the system topic starting with $SYS/.

The $SYS topic path begins with $SYS/brokers/{node}/, where {node} is the name of the node where the event/message is generated, for example:

  1. $SYS/brokers/emqx@127.0.0.1/version
  2. $SYS/brokers/emqx@127.0.0.1/uptime

$SYS system message publish interval is configured via Dashboard‘s Management/MQTT Setting/System Topic.

TIP

By default, only MQTT clients on localhost are allowed to subscribe to the $SYS topic. Please refer to File Authorization to modify the ACL rules for publish and subscribe.

Most of the data of the $SYS topic in EMQX can be obtained through other methods with lower Couplings. The device online and offline status can be captured and processed in the Rule Engine.

Cluster Status Information

TopicDescription
$SYS/brokerscluster node list
$SYS/brokers/${node}/versionEMQX version
$SYS/brokers/${node}/uptimeEMQX startup time
$SYS/brokers/${node}/datetimeEMQX time
$SYS/brokers/${node}/sysdescrEMQX description

Client Online and Offline Events

Those events is enabled by default, please refer to sys_topics.sys_event_messages to turn it off.

$SYS topic prefix: $SYS/brokers/${node}/clients/

TopicDescription
${clientid}/connectedOnline event. This message is published when a client goes online
${clientid}/disconnectedOffline event. This message is published when a client is offline

The Payload of the connected event message can be parsed into JSON format:

  1. {
  2. "username": "foo",
  3. "ts": 1625572213873,
  4. "sockport": 1883,
  5. "proto_ver": 4,
  6. "proto_name": "MQTT",
  7. "keepalive": 60,
  8. "ipaddress": "127.0.0.1",
  9. "expiry_interval": 0,
  10. "connected_at": 1625572213873,
  11. "connack": 0,
  12. "clientid": "emqtt-8348fe27a87976ad4db3",
  13. "clean_start": true
  14. }

The Payload of the disconnected event message can be parsed into JSON format:

  1. {
  2. "username": "foo",
  3. "ts": 1625572213873,
  4. "sockport": 1883,
  5. "reason": "tcp_closed",
  6. "proto_ver": 4,
  7. "proto_name": "MQTT",
  8. "ipaddress": "127.0.0.1",
  9. "disconnected_at": 1625572213873,
  10. "clientid": "emqtt-8348fe27a87976ad4db3"
  11. }

Client Subscribed and Unsubscribed Events

Those events is disenabled by default, please refer to sys_topics.sys_event_messages to turn it on.

$SYS topic prefix: $SYS/brokers/${node}/clients/

TopicDescription
${clientid}/subscribedSubscribed event. This message is published when a client goes online
${clientid}/unsubscribedunsubscribed event. This message is published when a client is offline

The Payload of the subscribed event message can be parsed into JSON format:

  1. {
  2. "username":"foo",
  3. "ts":1625572213878,
  4. "topic":"/the/best/mqtt/broker/is/emqx",
  5. "subopts":{
  6. "sub_props":{},
  7. "rh":0,
  8. "rap":0,
  9. "qos":0,
  10. "nl":0,
  11. "is_new":true
  12. },
  13. "protocol":"mqtt",
  14. "clientid":"emqtt-8348fe27a87976ad4db3"
  15. }

The Payload of the unsubscribed event message can be parsed into JSON format:

  1. {
  2. "username":"foo",
  3. "ts":1625572213899,
  4. "topic":"/the/best/mqtt/broker/is/emqx",
  5. "protocol":"mqtt",
  6. "clientid":"emqtt-8348fe27a87976ad4db3"
  7. }

Statistics

System topic prefix : $SYS/brokers/${node}/stats/

Client Statistics

TopicDescription
connections/countTotal number of current clients
connections/maxMaximum number of clients

Subscription Statistics

TopicDescription
suboptions/countnumber of current subscription options
suboptions/maxtotal number of maximum subscription options
subscribers/countnumber of current subscribers
subscribers/maxmaximum number of subscriptions
subscriptions/counttotal number of current subscription
subscriptions/maxmaximum number of subscriptions
subscriptions/shared/counttotal number of current shared subscriptions
subscriptions/shared/maxmaximum number of shared subscriptions

Topic Statistics

TopicDescription
topics/counttotal number of current topics
topics/maxmaximum number of topics

Routes Statistics

TopicDescription
routes/counttotal number of current Routes
routes/maxmaximum number of Routes

The topics/count and topics/max are numerically equal to routes/count and routes/max.

Throughput (Bytes/Packets/Message) Statistics

System Topic Prefix : $SYS/brokers/${node}/metrics/

Sent and Received Bytes Statistics

TopicDescription
bytes/receivedAccumulated received bytes
bytes/sentAccumulated sent bytes

Sent and Received MQTT Packets Statistics

TopicDescription
packets/receivedAccumulative received MQTT packets
packets/sentAccumulative sent MQTT packets
packets/connect/receivedAccumulative received packets of CONNECT
packets/connack/sentAccumulative sent packets of CONNACK
packets/publish/receivedAccumulative received packets of PUBLISH
packets/publish/sentAccumulative sent packets of PUBLISH
packets/publish/errorAccumulative handling packets of PUBLISH error
packets/publish/auth_errorAccumulative denied packets of PUBLISH
packets/publish/droppedAccumulative dropped packets of PUBLISH
packets/puback/receivedAccumulative received packets of PUBACK
packets/puback/sentAccumulative sent packets of PUBACK
packets/puback/inuseAccumulative dropped packets of PUBACK
packets/puback/missedAccumulative missed packets of PUBACK
packets/pubrec/receivedAccumulative received packets of PUBREC
packets/pubrec/sentAccumulative sent packets of PUBREC
packets/pubrec/inuseAccumulative dropped packets of PUBREC
packets/pubrec/missedAccumulative missed packets of PUBREC
packets/pubrel/receivedAccumulative received packets of PUBREL
packets/pubrel/sentAccumulative sent packets of PUBREL
packets/pubrel/missedAccumulative missed packets of PUBREL
packets/pubcomp/receivedAccumulative received packets of PUBCOMP
packets/pubcomp/sentAccumulative sent packets of PUBCOMP
packets/pubcomp/inuseAccumulative dropped packets of PUBCOMP
packets/pubcomp/missedAccumulative missed packets of PUBCOMP
packets/subscribe/receivedAccumulative received packets of SUBSCRIBE
packets/subscribe/errorAccumulative handling packets of SUBSCRIBE error
packets/subscribe/auth_errorAccumulative denied packets of SUBSCRIBE
packets/suback/sentAccumulative sent packets of SUBACK
packets/unsubscribe/receivedAccumulative received packets of UNSUBSCRIBE
packets/unsuback/sentAccumulative sent packets of UNSUBACK
packets/pingreq/receivedAccumulative received packets of PINGREQ
packets/pingresp/sentAccumulative sent packets of PINGRESP
packets/disconnect/receivedAccumulative received packets of DISCONNECT
packets/disconnect/sentAccumulative sent packets of DISCONNECT
packets/auth/receivedAccumulative received packets of AUTH
packets/auth/sentAccumulative sent packets of AUTH

MQTT Sent and Received Messages Statistics

TopicDescription
messages/receivedAccumulative received messages
messages/sentAccumulative sent messages
messages/qos0/receivedAccumulative received messages of QoS 0
messages/qos0/sentAccumulative sent messages of QoS 0
messages/qos1/receivedAccumulative received messages QoS 1
messages/qos1/sentAccumulative sent messages QoS 1
messages/qos2/receivedAccumulative received messages of QoS 2
messages/qos2/sentAccumulative sent messages of QoS 2
messages/publishAccumulative PUBLISH messages
messages/droppedTotal number of dropped messages
messages/dropped/expiredTotal number of dropped messages (Expired)
messages/dropped/no_subscribersTotal number of dropped messages (No subscriber)
messages/forwardTotal number of messages forwarded by the node
messages/retainedAccumulative retained messages
messages/delayedAccumulative delayed messages
messages/deliveredAccumulative delivered messages
messages/ackedAccumulative acknowledged messages

Alarms - System Alarms

System Topic Prefix: $SYS/brokers/${node}/alarms/

TopicDescription
activatenewly generated alarm
deactivatecleared alarm

Sysmon - System Monitoring

System Topic Prefix: $SYS/brokers/${node}/sysmon/

TopicDescription
long_gcGarbage collection takes too long
long_scheduleProcess scheduling takes too long, taking up too many time slices of the scheduler
large_heapProcess memory usage is too high
busy_portThe process sends a message to a busy port and the process is hung
busy_dist_portThe distributed communication port used for inter-node communication is busy and the process is hung