Query Client Events
Last updated:2026-01-30 14:55:29
What Is a Client Event?
A Client Event refers to a series of state changes and interaction notifications triggered by a client during MQTT protocol communication. By tracking system events, it helps users promptly troubleshoot, pinpoint, and analyze issues to ensure system stability.
Event Examples
A challenge in managing a large number of IoT devices is how to respond promptly when devices go offline. A well-designed business system typically needs to inspect and categorize the reasons for device disconnections, then activate corresponding contingency measures.
To achieve such business objectives, business applications can subscribe to the $events/client_disconnect topic. Once a device goes offline, the MQTT system will trigger client event messages. The business system will promptly receive event content similar to the following:
{ "clientid": "V622-XXX-XXX","username": "sample-user","event": "client.disconnected","reason": "authentication_expired","node": "sz-h-125xm","peername": "10.0.0.1:5768","disconnected_at": 1724136603064}
View Client Events
Method 1:
1. Log in to the MQTT Console.
2. Click Resource > Cluster in the left sidebar. After selecting a region, click the "ID" of the target cluster to enter the cluster basic information page.
3. In the left tab bar, select Client to go to the specific client details page. You can then scroll down to view client events.
Method 2:
Subscribe to system event topics (such as
$events/client_connected) to receive event messages containing detailed information. For specifics, refer to the Event Topics section below.Event Topic
The MQTT system publishes triggered events to the following system topics as QoS=0 messages. Business systems can subscribe to them based on business needs.
Topic Name | Remarks |
$events/client_connected | Client connected. |
$events/client_disconnected | Client disconnected. |
$events/session_subscribed | A subscription was added to the client session. |
$events/session_unsubscribed | A subscription was removed from the client session. |
$events/certificate_registered | Client registered a device certificate. |
$events/certificate_rejected | Client device certificate was rejected. The certificate status is inactive, such as PENDING_ACTIVATION. |
Connection Events
After a client connects or disconnects, the MQTT Broker triggers client connection or disconnection events.
The event message body is a JSON string encoded in UTF-8, containing the following fields.
Client Connection Event
After the client successfully connects, the MQTT Broker triggers a client connection event and sends a message to the topic
$events/client_connected.The event message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
clientid | Client ID, often a unique code such as product serial number or vehicle identification number. | 306520284186458 |
clean_start | Whether the session is clean-start. | true |
connected_at | Session connection time in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
event | event type, fixed value "client.connected". | client.connected |
keepalive | Client "keep-alive" period, unit: seconds. | 60 |
node | MQTT Broker node information (IP: port). | 10.0.0.1:1883 |
proto_ver | Protocol version 3/4/5. | 4 |
timestamp | Event generation time in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
username | Username. | sample_user |
Client Disconnect Event
When a client disconnects, the MQTT Broker triggers a client disconnect event and sends a message to the topic
$events/client_disconnected. Subscribers can inspect fields such as clientid and reason to take appropriate actions.The event message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
clientid | Client ID, often a unique code such as product serial number or vehicle identification number. | 306520284186458 |
event | event type, fixed value: "client.disconnected". | client.disconnected |
disconnected_at | Event generation time in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
node | MQTT Broker node. | 10.0.0.1:1883 |
reason | Reason for client disconnection, enumeration value, see details in the table below client disconnection reason. | normal |
username | Username. | sample_user |
peername | Client network address. | IP:Port |
sockname | MQTT Broker network address. | IP:Port |
Reason for Client Disconnection
Disconnection Reason | Semantics | Recommended Solution |
normal | The server received the DISCONNECT message and disconnected normally. | Normal event. Confirm whether the client-initiated disconnection is expected by business logic (for example, the client actively exits upon task completion). |
takeovered | The client was disconnected by a device with the same client ID. | Client ID conflict. Check the client ID generation policy to ensure each online device has a unique client ID. (If it is an occasional single occurrence, it may be an automatic recovery after network fluctuation, and no action is required.) |
kicked | The client was forced to log out by management. | Administrative action. Please check the management console or API call logs of the MQTT service to confirm which administrator or automated policy performed the force-logout action and why. |
keepalive_timeout | The MQTT Broker node did not receive an interactive message from the client within 1.5 times the keep-alive period. | Network or client issue. 1. Check whether the device network connection is stable. 2. Check whether the device CPU/memory load is too high, resulting in failure to send heartbeat packets in time. 3. In a weak network environment, you may appropriately increase the keep-alive value. |
not_authenticated | Unauthenticated, similar to HTTP status code 401. | Authentication information error. Check whether the username, password, certificate, or Token configured for the client is correct and whether it matches the server-side configuration. |
not_authorized | Unauthorized, similar to HTTP status code 403. | Insufficient permissions. The client is authenticated but lacks permission to connect or perform operations (such as publishing/subscribing to specific topics). Check the ACL policy configuration and grant necessary permissions to this client. |
tcp_closed | TCP connection closed. | Network layer disconnected. Possible causes include device network interruption, NAT Gateway timeout, or firewall policy blocking. |
ping_without_connect | The client sent a PING before sending the CONNECT packet. | Client SDK/firmware Bug. Check and fix the client MQTT protocol implementation code to ensure strict adherence to the connection establishment sequence: CONNECT -> other packets. |
authentication_expired | Authentication failed. JWT/SAS tokens have expired. | Credentials expired. The client program should have the capability to refresh Token. |
too_many_connection | Exceeding the maximum cluster/node connections. | Server-side capacity issue. 1. Contact Us to upgrade your service specifications or increase the maximum connection limit. 2. Troubleshoot whether client-side exceptions (such as code bugs) are causing the creation of a large number of invalid connections. |
go_away | MQTT Broker node restart, graceful shutdown. | Usually caused by server-side upgrades or maintenance. The client should implement an automatic reconnection mechanism to automatically reconnect after the server recovers. |
client_id_too_long | Client ID exceeds the maximum limit. | Client ID exceeds the maximum length. Check the ID length (the MQTT protocol's inherent limit of 23 characters) and modify the client ID generation logic. |
client_id_required | Persistent session connection lacks the required client ID field. | Client protocol error. When CleanSession=false, the client ID cannot be empty. Please fix the client logic: either provide an ID or set CleanSession to true. |
client_id_invalid | Client ID is non-compliant. Client ID can only contain [0-9a-zA-Z] characters. Please modify the client ID generation logic to remove or replace invalid characters. | |
bad_will_message | Illegal will message. | Will message configuration error. Check the will message (Will Message) set by the client, ensure its topic (Topic) and payload (Payload) formats are correct, and verify that the client has permission to publish messages to the specified will topic. |
server_internal_error | Internal server error. | Server issue. Please contact us and provide relevant information (such as timestamp, instance ID, and client ID) to troubleshoot server issues. |
Subscription Events
Subscribing to Client Events
After a client session adds a new subscription, the MQTT Broker will trigger a client subscription event and send a message to the topic
$events/session_subscribed.The event message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
clientid | Client ID, often a unique code such as product serial number or vehicle identification number. | 306520284186458 |
event | event type, fixed value: "client.subscribed". | client.subscribed |
node | MQTT Broker node. | 10.0.0.1:1883 |
peerhost | Client address. | 10.0.0.1:1234 |
qos | Subscribe to QoS. | 0/1/2 |
timestamp | Event generation time of subscription in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
topic | subscribed Topic Filter. | home/# |
Canceling Client Subscription Event
After a client session unsubscribes, the MQTT Broker will trigger a client unsubscription event and send a message to the topic
$events/session_unsubscribedThe event message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
clientid | Client ID, often a unique code such as product serial number or vehicle identification number. | 306520284186458 |
event | event type, fixed value: "client.unsubscribed". | client.unsubscribed |
node | MQTT Broker node. | 10.0.0.1:1883 |
peerhost | Client address. | 10.0.0.1:1234 |
qos | Subscribe to QoS. | 0/1/2 |
timestamp | Event generation time of unsubscription in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
topic | subscribed Topic Filter. | home/# |
Certificate Lifecycle Event
If the X.509 is configured to use the "one device, one certificate" mode, the following event types may occur.
Client Certificate Registration Event
In automatic registration mode, client certificates are automatically registered to the cloud service when the client first connects. To identify new devices joining the cluster, the MQTT service will trigger a client registration event and send a message to the topic:
$events/certificate_registered.The event message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
event | event type, fixed value: "certificate.registered" | certificate.registered |
timestamp | Event generation time in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
node | MQTT Broker node. | 10.0.0.1:1234 |
peerName | Client address IP:port. | 10.0.0.2:1234 |
caSn | CA certificate serial number. | 7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
sn | Device certificate serial number. | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5 |
commonName | Common name of device certificate. | VIN-1234-5678 |
status | Device certificate status. | pending_activation/active/inactive/revoked |
certificateChainSn | Device certificate chain serial number. | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
Client Certificate Rejection Event
If the client certificate status is (PENDING_ACTIVATION), when the client attempts to connect, it will trigger a client rejection event and send event messages to the topic:
$events/certificate_rejectedThe message body is a UTF-8 encoded JSON string and contains the following fields:
Field | Semantics | Example Value |
event | event type, fixed value: "certificate.rejected" | certificate.rejected |
timestamp | Event generation time in number of milliseconds since 1970/01/01 00:00:00. | 1717651184811 |
node | MQTT Broker node. | 10.0.0.1:1234 |
peerName | Client address IP:port. | 10.0.0.2:1234 |
caSn | CA certificate serial number. | 7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
sn | Device certificate serial number. | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5 |
commonName | Common name of device certificate. | VIN-1234-5678 |
status | Device certificate status. | inactive/revoked/pending_activation/active |
certificateChainSn | Device certificate chain serial number. | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
Client Certificate Rejection Reason
Rejection Reason | Semantics | Handling Recommendation |
inactive | Certificate is unregistered | |
revoked | Certificate Revocation | Replace the certificate. This certificate has been added to the Certificate Revocation List (CRL), typically for security reasons (such as private key compromise). Please confirm the revocation reason. To restore device connectivity, issue and configure a new certificate for the device. |
pending_activation | Certificate is inactive | Activate the certificate. The certificate has been registered on the platform but has not yet been activated. Go to the console, locate the certificate, and complete the activation process to allow it to establish connections. |
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback