Statistics and Metrics

EMQX provides metrics monitoring functions, based on which the operation and maintenance personnel can monitor the current service status and troubleshoot possible system malfunctions.

EMQX divides monitoring status into Statistics and Metrics.

  • Statistics are integer-type gauges used to return a single value at the point of time the metric was requested.
  • Metrics are integer-type counters used to measure simple incrementing and decrementing numbers, such as the number of bytes and messages sent or received.

EMQX provides users with multiple ways to view statistics and metrics. Most directly, you can view these data on the EMQX Dashboard. When it is not convenient to access the Dashboard, you can also get the data through REST API and system topic messages. Additionally, you can easily integrate the monitoring functions with your own monitoring system, see Integrate with Prometheus.

View Statistics on Dashboard

On EMQX Dashboard, click Monitoring -> Cluster Overview from the left navigation menu. On the Cluster Overview page, click the Nodes tab. Click the name of the node to see the statistics details on the right.

node-statistics-ee

Statistics include two values: current values and historical maximums, for example, the current number of subscriptions and the historical maximum number of subscriptions. Here is the EMQX statistics list:

StatisticsDescription
connections.countThe number of current connections
connections.maxThe historical maximum number of connections
live_connections.countThe number of currently live connections
live_connections.maxThe historical maximum number of live connections
channels.countThe same as sessions.count
channels.maxThe same as sessions.max
sessions.countThe number of current sessions
sessions.maxThe historical maximum number of sessions
topics.countThe number of current topics
topics.maxThe historical maximum number of topics
suboptions.countThe same as subscriptions.count
suboptions.maxThe same as subscriptions.max
subscribers.countThe number of current subscribers
subscribers.maxThe historical maximum number of subscribers
subscriptions.countThe number of current subscriptions, including shared subscriptions
subscriptions.maxThe historical maximum number of subscriptions
subscriptions.shared.countThe number of current shared subscriptions
subscriptions.shared.maxThe historical maximum number of shared subscriptions
retained.countThe number of currently retained messages
retained.maxThe historical maximum number of retained messages
delayed.countThe number of currently delayed messages
delayed.maxThe historical maximum number of delayed messages

View Metrics on Dashboard

On EMQX Dashboard, click Monitoring -> Cluster Overview from the left navigation menu. On the Cluster Overview page, you can see metrics by clicking the Metrics tab. EMQX Metrics currently covers four dimensions: bytes, packets, messages, and events.

Connection and Session Metrics

You can see the event-related metrics for the cluster or node, such as client connection, connection sessions, and client access.

dashboard-event-metrics-ee

Connections

MetricsDescription
client.connackThe number of connection acknowledgment (CONNACK) messages received by clients
client.connectThe number of connection requests from the client, including both successful and failed connection requests
client.connectedThe number of client connections that have succeeded
client.disconnectedThe number of client disconnections, including active and abnormal disconnections
client.subscribeThe number of successful subscriptions
client.unsubscribeThe number of successful unsubscriptions

Sessions

MetricsDescription
session.createdThe number of sessions that have been created
session.discardedThe number of sessions that have been discarded
session.resumedThe number of sessions that have been resumed
session.takenoverThe number of sessions that have been taken over
session.terminatedThe number of sessions that have been terminated

Access

MetricsDescription
authorization.allowThe total number of client authorization passes, that is, the sum of cache hits (retrieved authorization results) and matched authorization requests (those corresponding to the policy rules).
authorization.denyThe total number of client authorization fails, that is, the sum of cache hits (retrieved authorization results) and unmatched authorization requests (those not corresponding to any policy rules).
authorization.matched.allowThe number of client authorization passes as per the rules
authorization.matched.denyThe number of client authorization fails as rejected by the rules
authorization.nomatchThe number of client authorization requests not matching any rules
authorization.cache_hitThe number of clients getting authorization results (allow or deny) by cache
authorization.superuserThe number of clients being authorized as superuser
client.auth.anonymousThe number of clients that log in anonymously
client.authenticateThe number of triggered authentication
client.authorizeThe number of triggered authorization

Messaging

Scroll down the Metrics page, and you can see message-related metrics, including bytes, packets, messages, and delivery.

dashboard-messaging-metrics-ee

Bytes

MetricsDescription
bytes.receivedThe number of bytes received
bytes.sentThe number of bytes sent

Packets

MetricsDescription
packets.receivedThe number of received packets
packets.sentThe number of sent packets
packets.connect.receivedThe number of received CONNECT packets
packets.connack.auth_errorThe number of sent CONNACK messages with reason codes 0x86 and 0x87
packets.connack.errorThe number of sent CONNACK packets with reason codes apart from 0x00. The value of this indicator is greater than or equal to the value of packets.connack.auth_error
packets.connack.sentThe number of sent CONNACK packets
packets.publish.receivedThe number of received PUBLISH packets
packets.publish.sentThe number of sent PUBLISH packets
packets.publish.inuseThe number of received PUBLISH packets with occupied packet identifiers
packets.publish.auth_errorThe number of received PUBLISH packets that failed the ACL check
packets.publish.errorThe number of received PUBLISH packets that cannot be published
packets.publish.droppedThe number of PUBLISH packets that are discarded due to the receiving limit
packets.puback.receivedThe number of received PUBACK packets
packets.puback.sentThe number of sent PUBACK packets
packets.puback.inuseThe number of received PUBACK messages with occupied identifiers
packets.puback.missedThe number of received PUBACK packets with unknown identifiers
packets.pubrec.receivedThe number of received PUBREC packets
packets.pubrec.sentThe number of sent PUBREC packets
packets.pubrec.inuseThe number of received PUBREC messages with occupied identifiers
packets.pubrec.missedThe number of received PUBREC packets with unknown identifiers
packets.pubrel.receivedThe number of received PUBREL packets
packets.pubrel.sentThe number of sent PUBREL packets
packets.pubrel.missedThe number of received PUBREL packets with unknown identifiers
packets.pubcomp.receivedThe number of received PUBCOMP packets
packets.pubcomp.sentThe number of sent PUBCOMP packets
packets.pubcomp.inuseThe number of received PUBCOMP messages with occupied identifiers
packets.pubcomp.missedThe number of missed PUBCOMP packets
packets.subscribe.receivedThe number of received SUBSCRIBE packets
packets.subscribe.errorThe number of received SUBSCRIBE packets with failed subscriptions
packets.subscribe.auth_errorThe number of received SUBACK packets that failed the ACL check
packets.suback.sentThe number of sent SUBACK packets
packets.unsubscribe.receivedThe number of received UNSUBSCRIBE packets
packets.unsubscribe.errorThe number of received UNSUBSCRIBE packets with failed unsubscriptions
packets.unsuback.sentThe number of sent UNSUBACK packets
packets.pingreq.receivedThe number of received PINGREQ packets
packets.pingresp.sentThe number of sent PUBRESP packets
packets.disconnect.receivedThe number of received DISCONNECT packets
packets.disconnect.sentThe number of sent DISCONNECT packets
packets.auth.receivedThe number of received AUTH packets
packets.auth.sentThe number of sent AUTH packets

Message (PUBLISH packet)

MetricsDescription
messages.ackedThe number of acknowledged messages
messages.delayedThe number of messages for delayed publish that are stored by EMQX
messages.deliveredThe number of messages forwarded to the subscription process internally by EMQX
messages.droppedThe total number of messages dropped by EMQX before forwarding to the subscription process
messages.dropped.no_subscribersThe number of messages dropped due to no subscribers
messages.dropped.await_pubrel_timeoutThe number of messages dropped due to await PUBREL timeout
messages.forwardThe number of messages forwarded to other nodes
messages.publishThe number of messages published in addition to system messages
messages.qos0.receivedThe number of QoS 0 messages received from clients
messages.qos1.receivedThe number of QoS 2 messages received from clients
messages.qos2.receivedThe number of QoS 1 messages received from clients
messages.qos0.sentThe number of QoS 0 messages sent to clients
messages.qos1.sentThe number of QoS 1 messages sent to clients
messages.qos2.sentThe number of QoS 2 messages sent to clients
messages.receivedThe number of messages received from the client, which is equal to the sum of messages.qos0.received, messages.qos1.received, and messages.qos2.received
messages.sentThe number of messages sent to the client, which is equal to the sum of messages.qos0.sent, messages.qos1.sent, and messages.qos2.sent

Delivery

MetricsDescription
delivery.droppedThe total number of dropped messages during transmission
delivery.dropped.expiredThe number of dropped messages during transmission because the message is expired
delivery.dropped.no_localThe number of dropped messages during transmission due to the No Local subscription option
delivery.dropped.qos0_msgThe number of dropped QoS 0 messages during transmission due to a full message queue
delivery.dropped.queue_fullThe number of dropped non-zero QoS level messages during transmission due to a full message queue
delivery.dropped.too_largeThe number of dropped messages during transmission due to exceeding length limits

Request Monitoring Status via REST API

You can also get the metrics and statistics through the API. Click Metrics on the left navigation menu on the UI to execute this API request. For how to work with EMQX API, see REST API.

metrics-api-doc

Get Monitoring Status via System Topics

EMQX periodically publishes messages about the running status, message statistics, and client online and offline events through system topics. Clients can subscribe to system topics by adding the prefix $SYS/ before the topic name. For more information on different types of system topics, see System Topic.

You can configure system topic settings on Dashboard. Click Management -> MQTT Settings from the left navigation menu. Select System Topic tab.

system-topic-setting

  • Messages publish interval: Set the time interval for sending $sys topic.
  • Heartbeat interval: Set the time interval for sending heartbeat messages.
  • Client connected notification: Enabled by default and event messages about client being connected will be published.
  • Client disconnected notification: Enabled by default and event messages about client being disconnected will be published.
  • Client subscribed notification: Disabled by default; When enabled, event messages about a client subscribing to a topic will be published.
  • Client unsubscribed notification: Disabled by default; When enabled, event messages about a client unsubscribing to a topic will be published.