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

Topic	Description
$SYS/brokers	cluster node list
$SYS/brokers/${node}/version	EMQX version
$SYS/brokers/${node}/uptime	EMQX startup time
$SYS/brokers/${node}/datetime	EMQX time
$SYS/brokers/${node}/sysdescr	EMQX 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/

Topic	Description
${clientid}/connected	Online event. This message is published when a client goes online
${clientid}/disconnected	Offline 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/

Topic	Description
${clientid}/subscribed	Subscribed event. This message is published when a client goes online
${clientid}/unsubscribed	unsubscribed 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

Topic	Description
connections/count	Total number of current clients
connections/max	Maximum number of clients

# Subscription Statistics

Topic	Description
suboptions/count	number of current subscription options
suboptions/max	total number of maximum subscription options
subscribers/count	number of current subscribers
subscribers/max	maximum number of subscriptions
subscriptions/count	total number of current subscription
subscriptions/max	maximum number of subscriptions
subscriptions/shared/count	total number of current shared subscriptions
subscriptions/shared/max	maximum number of shared subscriptions

# Topic Statistics

Topic	Description
topics/count	total number of current topics
topics/max	maximum number of topics

# Routes Statistics

Topic	Description
routes/count	total number of current Routes
routes/max	maximum 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

Topic	Description
bytes/received	Accumulated received bytes
bytes/sent	Accumulated sent bytes

# Sent and Received MQTT Packets Statistics

Topic	Description
packets/received	Accumulative received MQTT packets
packets/sent	Accumulative sent MQTT packets
packets/connect/received	Accumulative received packets of CONNECT
packets/connack/sent	Accumulative sent packets of CONNACK
packets/publish/received	Accumulative received packets of PUBLISH
packets/publish/sent	Accumulative sent packets of PUBLISH
packets/publish/error	Accumulative handling packets of PUBLISH error
packets/publish/auth_error	Accumulative denied packets of PUBLISH
packets/publish/dropped	Accumulative dropped packets of PUBLISH
packets/puback/received	Accumulative received packets of PUBACK
packets/puback/sent	Accumulative sent packets of PUBACK
packets/puback/inuse	Accumulative dropped packets of PUBACK
packets/puback/missed	Accumulative missed packets of PUBACK
packets/pubrec/received	Accumulative received packets of PUBREC
packets/pubrec/sent	Accumulative sent packets of PUBREC
packets/pubrec/inuse	Accumulative dropped packets of PUBREC
packets/pubrec/missed	Accumulative missed packets of PUBREC
packets/pubrel/received	Accumulative received packets of PUBREL
packets/pubrel/sent	Accumulative sent packets of PUBREL
packets/pubrel/missed	Accumulative missed packets of PUBREL
packets/pubcomp/received	Accumulative received packets of PUBCOMP
packets/pubcomp/sent	Accumulative sent packets of PUBCOMP
packets/pubcomp/inuse	Accumulative dropped packets of PUBCOMP
packets/pubcomp/missed	Accumulative missed packets of PUBCOMP
packets/subscribe/received	Accumulative received packets of SUBSCRIBE
packets/subscribe/error	Accumulative handling packets of SUBSCRIBE error
packets/subscribe/auth_error	Accumulative denied packets of SUBSCRIBE
packets/suback/sent	Accumulative sent packets of SUBACK
packets/unsubscribe/received	Accumulative received packets of UNSUBSCRIBE
packets/unsuback/sent	Accumulative sent packets of UNSUBACK
packets/pingreq/received	Accumulative received packets of PINGREQ
packets/pingresp/sent	Accumulative sent packets of PINGRESP
packets/disconnect/received	Accumulative received packets of DISCONNECT
packets/disconnect/sent	Accumulative sent packets of DISCONNECT
packets/auth/received	Accumulative received packets of AUTH
packets/auth/sent	Accumulative sent packets of AUTH

# MQTT Sent and Received Messages Statistics

Topic	Description
messages/received	Accumulative received messages
messages/sent	Accumulative sent messages
messages/qos0/received	Accumulative received messages of QoS 0
messages/qos0/sent	Accumulative sent messages of QoS 0
messages/qos1/received	Accumulative received messages QoS 1
messages/qos1/sent	Accumulative sent messages QoS 1
messages/qos2/received	Accumulative received messages of QoS 2
messages/qos2/sent	Accumulative sent messages of QoS 2
messages/publish	Accumulative PUBLISH messages
messages/dropped	Total number of dropped messages
messages/dropped/expired	Total number of dropped messages (Expired)
messages/dropped/no_subscribers	Total number of dropped messages (No subscriber)
messages/forward	Total number of messages forwarded by the node
messages/retained	Accumulative retained messages
messages/delayed	Accumulative delayed messages
messages/delivered	Accumulative delivered messages
messages/acked	Accumulative acknowledged messages

# Alarms - System Alarms

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

Topic	Description
activate	newly generated alarm
deactivate	cleared alarm

# Sysmon - System Monitoring

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

Topic	Description
long_gc	Garbage collection takes too long
long_schedule	Process scheduling takes too long, taking up too many time slices of the scheduler
large_heap	Process memory usage is too high
busy_port	The process sends a message to a busy port and the process is hung
busy_dist_port	The distributed communication port used for inter-node communication is busy and the process is hung

← Log Trace Integrate with Prometheus →