# $SYS - System Topic

The EMQ X Broker 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}/. {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

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

broker.sys_interval = 1m

WARNING

By default, only MQTT clients on localhost is allowed to subscribe to the $ SYS topic. Please refer to build-in ACL to modify the ACL rules for publish and subscription.

Most of the data of the $ SYS topic in EMQ X Broker can be obtained through other method with lower Couplings. The device online and offline status can be obtained through Webhook), and the node and cluster status can be obtained through HTTP API - Statistics Metrics.

# Cluster status information

TopicDescription
$SYS/brokerscluster node list
$SYS/brokers/${node}/versionEMQ X Broker version
$SYS/brokers/${node}/uptimeEMQ X Broker startup time
$SYS/brokers/${node}/datetimeEMQ X Broker time
$SYS/brokers/${node}/sysdescrEMQ X Broker description

# Client Online and Offline Events

$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":"undefined",
    "ts":1582687922392,
    "sockport":1883,
    "proto_ver":5,
    "proto_name":"MQTT",
    "keepalive":300,
    "ipaddress":"127.0.0.1",
    "expiry_interval":0,
    "connected_at":1582687922,
    "connack":0,
    "clientid":"emqtt-8348fe27a87976ad4db3",
    "clean_start":true
}

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

{
    "username":"undefined",
    "ts":1582688032203,
    "reason":"tcp_closed",
    "disconnected_at":1582688032,
    "clientid":"emqtt-8348fe27a87976ad4db3"
}

# 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 QoS0
messages/qos0/sentAccumulative sent messages of QoS0
messages/qos1/receivedAccumulative received messages QoS1
messages/qos1/sentAccumulative sent messages QoS1
messages/qos2/receivedAccumulative received messages of QoS2
messages/qos2/sentAccumulative sent messages of QoS2
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 acked 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_gcGC Overtime alarm
long_scheduleAlarm for Excessive Scheduling Time
large_heapALarm for Heap Memory Occupancy
busy_portAlarm for Port busy
busy_dist_portAlarm for Dist Port busy