Querying Client Events

Mode fokus

Ukuran font

Terakhir diperbarui: 2026-04-01 16:30:54

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.
Example Event
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 causes of device disconnections, and then trigger appropriate contingency measures.
To achieve such business objectives, the business application can subscribe to the $events/client_disconnect topic. Once a device goes offline, the MQTT system will trigger a client event message. 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
}
Viewing Client Events
Method 1:
1. Log in to the MQTT console.
2. In the left sidebar, choose Resource > Cluster, select a region, and click the ID of the target cluster to go to 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 with detailed information. For more information, refer to the Event Topics section below.
Event Topics
The MQTT system publishes triggered events to the following system topics as QoS 0 messages. Business systems can subscribe to these topics as needed.
Topic Name
Remarks
$events/client_connected
The client is connected.
$events/client_disconnected
The client is 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
The client registered a device certificate.
$events/certificate_rejected
The 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 a client connection or disconnection event.
The event message body is a JSON string encoded in UTF-8, containing the following fields.
Client Connection Event
After a client successfully connects, the MQTT Broker triggers a client connection event and sends a message to the $events/client_connected topic.
The event message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
clientid
Client ID, which is often a unique code such as product serial number or vehicle identification number (VIN).
306520284186458
clean_start
Indicates whether the session is clean-start.
true
connected_at
Session connection time, in milliseconds since 00:00:00 UTC on January 1, 1970.
1717651184811
event
Event type. Fixed value: "client.connected".
client.connected
keepalive
Keep-alive interval for the client, in seconds.
60
node
MQTT Broker node information (IP address: port).
10.0.0.1:1883
proto_ver
Protocol version 3/4/5.
4
timestamp
Event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
1717651184811
username
Username.
sample_user
Client Disconnection Event
When a client disconnects, the MQTT Broker triggers a client disconnection event and sends a message to the $events/client_disconnected topic. Subscribers can inspect fields such as clientid and reason to take appropriate actions.
The event message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
clientid
Client ID, which is often a unique code such as product serial number or VIN.
306520284186458
event
Event type. Fixed value: "client.disconnected".
client.disconnected
disconnected_at
Disconnection event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
1717651184811
node
MQTT Broker node.
10.0.0.1:1883
reason
Reason for the client disconnection. It is an enumerated field. For details, see the table Reasons for Client Disconnection below.
normal
username
Username.
sample_user
peername
Client network address.
IP:Port
sockname
MQTT Broker network address.
IP:Port
Reasons for Client Disconnection
Disconnection Reason
Semantics
Recommended Solution
normal
The server disconnected normally after receiving a DISCONNECT packet.
Normal event. Check whether client-initiated disconnections align with the business logic. For example, the client actively exits upon completing a task.
takeovered
The client was disconnected due to another device with the same client ID logging in.
Client ID conflict. Check the client ID generation policy to ensure each online device has a unique client ID.
(If it occurs occasionally, it may be an automatic recovery after a network fluctuation, and no action is required.)
kicked
The client was forced to log out by an administrator.
Administrative action. Check the MQTT service management console or API call logs to determine which administrator or automated policy performed the force-logout action and the reason for it.
keepalive_timeout
The MQTT Broker did not receive any interaction packets from the client within 1.5 times the keep-alive interval.
Network or client issue.
1.  Check whether the device's network connection is stable.
2.  Check whether the device's CPU or memory load is too high, resulting in failure to send heartbeat packets in time.
3.  Under poor network conditions, you can increase the keep-alive value as needed.
not_authenticated
Unauthenticated, similar to HTTP status code 401.
Authentication information error. Check whether the username, password, certificate, and token configured for the client are correct and whether they match the server-side configuration.
not_authorized
Unauthorized, similar to HTTP status code 403.
Insufficient permissions. The client is authenticated but not authorized to connect or perform operations (such as publishing or subscribing to specific topics). Check the ACL policy configuration and grant the 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 or firmware bugs. Check and fix the client's MQTT protocol implementation code to ensure it strictly adheres to the connection sequence: CONNECT > other packets.
authentication_expired
Authentication failed. JWT, SAS, or other tokens have expired.
Credentials expired. Ensure the client program can refresh the token.
too_many_connection
Maximum connections for the cluster or node exceeded.
Server capacity issue.
1. Contact us to upgrade your service specifications or increase the maximum connection limit.
2. Check whether any client exceptions (such as code bugs) are causing a large number of invalid connections.
go_away
The MQTT Broker node is restarting (graceful shutdown).
Typically caused by server upgrades or maintenance. The client should implement an automatic reconnection mechanism to reconnect once the server is available.
client_id_too_long
Max client ID limit exceeded.
The client ID exceeds the length limit. Check the ID length (MQTT limit: 23 characters) and modify the client ID generation logic.
client_id_required
The required client ID field is missing for a persistent session connection.
Client protocol error. When CleanSession is set to false, the client ID cannot be empty. Please fix the client logic by either providing an ID or setting CleanSession to true.
client_id_invalid
The client ID contains invalid characters. For details, see Spec 3.1.3.1.
Invalid client ID. The client ID can only contain digits 0–9, lowercase letters a–z, and uppercase letters A–Z. 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 set for the client, ensure the topic and payload formats are correct, and verify that the client has permission to publish 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
Client Subscription Event
After a new subscription is added to a client session, the MQTT Broker triggers a client subscription event and sends a message to the $events/session_subscribed topic.
The event message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
clientid
Client ID, which is often a unique code such as product serial number or VIN.
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
Subscription QoS.
0/1/2
timestamp
Subscription event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
1717651184811
topic
Subscribed topic filter.
home/#
Client Unsubscription Event
After a client session unsubscribes, the MQTT Broker triggers a client unsubscription event and sends a message to the $events/session_unsubscribed topic.
The event message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
clientid
Client ID, which is often a unique code such as product serial number or VIN.
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
Subscription QoS.
0/1/2
timestamp
Unsubscription event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
1717651184811
topic
Subscribed topic filter.
home/#
Certificate Lifecycle Events
If X.509 is configured in one-device-one-certificate mode, the following event types may occur.
Client Certificate Registration Event
In automatic registration mode, the client certificate is automatically registered to the cloud service when the client connects for the first time. To identify new devices joining the cluster, the MQTT service triggers a client registration event and sends a message to the topic: $events/certificate_registered.
The event message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
event
Event type. Fixed value: "certificate.registered".
certificate.registered
timestamp
Disconnection event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
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
Device certificate common name.
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, any connection attempt will trigger a client rejection event and send an event message to the topic: $events/certificate_rejected
The message body is a JSON string encoded in UTF-8, containing the following fields:
Field
Semantics
Example Value
event
Event type. Fixed value: "certificate.rejected".
certificate.rejected
timestamp
Event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.
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
Device certificate common name.
VIN-1234-5678
status
Device certificate status.
inactive/revoked/pending_activation/active
certificateChainSn
Device certificate chain serial number.
1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5
Reasons for Client Certificate Rejection
Rejection Reason
Semantics
Recommended Solution
inactive
The certificate is unregistered.
Register the certificate. Please register the client certificate in the MQTT console.
revoked
The certificate is revoked.
Replace the certificate. The certificate has been added to the Certificate Revocation List (CRL), typically for security reasons (such as private key compromise). Please identify the revocation reason. To restore device connectivity, issue and configure a new certificate for the device.
pending_activation
The 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.
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿

Bantuan dan Dukungan

Apakah halaman ini membantu?

Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.

masukan

tencent cloud

TDMQ for MQTT

Querying Client Events

What Is a Client Event?

Example Event

Viewing Client Events

Event Topics

Connection Events

Client Connection Event

Client Disconnection Event

Reasons for Client Disconnection

Subscription Events

Client Subscription Event

Client Unsubscription Event

Certificate Lifecycle Events

Client Certificate Registration Event

Client Certificate Rejection Event

Reasons for Client Certificate Rejection

Bantuan dan Dukungan

Topic Name	Remarks
$events/client_connected	The client is connected.
$events/client_disconnected	The client is 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	The client registered a device certificate.
$events/certificate_rejected	The client device certificate was rejected. The certificate status is inactive, such as PENDING_ACTIVATION.

Field	Semantics	Example Value
clientid	Client ID, which is often a unique code such as product serial number or vehicle identification number (VIN).	306520284186458
clean_start	Indicates whether the session is clean-start.	true
connected_at	Session connection time, in milliseconds since 00:00:00 UTC on January 1, 1970.	1717651184811
event	Event type. Fixed value: "client.connected".	client.connected
keepalive	Keep-alive interval for the client, in seconds.	60
node	MQTT Broker node information (IP address: port).	10.0.0.1:1883
proto_ver	Protocol version 3/4/5.	4
timestamp	Event occurrence time, in milliseconds since 00:00:00 UTC on January 1, 1970.	1717651184811
username	Username.	sample_user

Disconnection Reason	Semantics	Recommended Solution
normal	The server disconnected normally after receiving a DISCONNECT packet.	Normal event. Check whether client-initiated disconnections align with the business logic. For example, the client actively exits upon completing a task.
takeovered	The client was disconnected due to another device with the same client ID logging in.	Client ID conflict. Check the client ID generation policy to ensure each online device has a unique client ID. (If it occurs occasionally, it may be an automatic recovery after a network fluctuation, and no action is required.)
kicked	The client was forced to log out by an administrator.	Administrative action. Check the MQTT service management console or API call logs to determine which administrator or automated policy performed the force-logout action and the reason for it.
keepalive_timeout	The MQTT Broker did not receive any interaction packets from the client within 1.5 times the keep-alive interval.	Network or client issue. 1. Check whether the device's network connection is stable. 2. Check whether the device's CPU or memory load is too high, resulting in failure to send heartbeat packets in time. 3. Under poor network conditions, you can increase the keep-alive value as needed.
not_authenticated	Unauthenticated, similar to HTTP status code 401.	Authentication information error. Check whether the username, password, certificate, and token configured for the client are correct and whether they match the server-side configuration.
not_authorized	Unauthorized, similar to HTTP status code 403.	Insufficient permissions. The client is authenticated but not authorized to connect or perform operations (such as publishing or subscribing to specific topics). Check the ACL policy configuration and grant the 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 or firmware bugs. Check and fix the client's MQTT protocol implementation code to ensure it strictly adheres to the connection sequence: CONNECT > other packets.
authentication_expired	Authentication failed. JWT, SAS, or other tokens have expired.	Credentials expired. Ensure the client program can refresh the token.
too_many_connection	Maximum connections for the cluster or node exceeded.	Server capacity issue. 1. Contact us to upgrade your service specifications or increase the maximum connection limit. 2. Check whether any client exceptions (such as code bugs) are causing a large number of invalid connections.
go_away	The MQTT Broker node is restarting (graceful shutdown).	Typically caused by server upgrades or maintenance. The client should implement an automatic reconnection mechanism to reconnect once the server is available.
client_id_too_long	Max client ID limit exceeded.	The client ID exceeds the length limit. Check the ID length (MQTT limit: 23 characters) and modify the client ID generation logic.
client_id_required	The required client ID field is missing for a persistent session connection.	Client protocol error. When CleanSession is set to false, the client ID cannot be empty. Please fix the client logic by either providing an ID or setting CleanSession to true.
client_id_invalid	The client ID contains invalid characters. For details, see Spec 3.1.3.1.	Invalid client ID. The client ID can only contain digits 0–9, lowercase letters a–z, and uppercase letters A–Z. 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 set for the client, ensure the topic and payload formats are correct, and verify that the client has permission to publish 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.

Rejection Reason	Semantics	Recommended Solution
inactive	The certificate is unregistered.	Register the certificate. Please register the client certificate in the MQTT console.
revoked	The certificate is revoked.	Replace the certificate. The certificate has been added to the Certificate Revocation List (CRL), typically for security reasons (such as private key compromise). Please identify the revocation reason. To restore device connectivity, issue and configure a new certificate for the device.
pending_activation	The 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.