# 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:

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

$SYS system message publish interval is configured in etc/emqx.conf:

broker {
  sys_interval: 1m
}
1
2
3

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 Broker version
$SYS/brokers/${node}/uptimeEMQX Broker startup time
$SYS/brokers/${node}/datetimeEMQX Broker time
$SYS/brokers/${node}/sysdescrEMQX Broker 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:

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

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

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

{
    "username":"foo",
    "ts":1625572213878,
    "topic":"/the/best/mqtt/broker/is/emqx",
    "subopts":{
        "sub_props":{},
        "rh":0,
        "rap":0,
        "qos":0,
        "nl":0,
        "is_new":true
    },
    "protocol":"mqtt",
    "clientid":"emqtt-8348fe27a87976ad4db3"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

{
    "username":"foo",
    "ts":1625572213899,
    "topic":"/the/best/mqtt/broker/is/emqx",
    "protocol":"mqtt",
    "clientid":"emqtt-8348fe27a87976ad4db3"
}
1
2
3
4
5
6
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
alertnewly generated alarm
clearcleared 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