Skip to content

Event Topics

The Rule of Data Integrations provides several event topics available for FROM clause.

Event topic nameExplanation
$events/client_connectedClient connect
$events/client_disconnectedClient disconnect
$events/message_deliveredMessage delivery
$events/message_ackedMessage acknowledged
$events/message_droppedMessage dropped when routing
$events/delivery_droppedMessage dropped when delivering
$events/session_subscribedSubscribe
$events/session_unsubscribedUnsubscribe

This article will introduce the usage of event topics, and the meaning of each field from three aspects: client connect and disconnect events, message events, topic subscribe and unsubscribe events.

Client connect and disconnect events

Client connect

The topic of client connect is $events/client_connected. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/client_connected"

You can test the SQL, view the return field after firing this rule. client_connected

The fields are explained as follows.

fieldExplanation
clean_startMQTT clean_start
clientidClient ID
connected_atTerminal connection completion time (s)
eventEvent type, fixed at "client.connected"
expiry_intervalMQTT Session Expiration time
is_bridgeWhether it is MQTT bridge connection
keepaliveMQTT keepalive interval
mountpointMountpoint for bridging messages
nodeNode name of the trigger event
peernameIPAddress and Port of terminal
proto_nameProtocol name
proto_verProtocol version
socknameIPAddress and Port listened by emqx
timestampEvent trigger time (ms)
usernameCurrent MQTT username

Client disconnect

The topic of client disconnect is $events/client_disconnected. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/client_disconnected"

You can test the SQL, view the return field after firing this rule. client_disconnected

The fields are explained as follows.

fieldExplanation
clientidClient ID
disconnected_atTerminal disconnection completion time (s)
eventEvent type, fixed at "client.disconnected"
nodeNode name of the trigger event
expiry_intervalMQTT Session Expiration time
socknameIPAddress and Port listened by emqx
timestampEvent trigger time (ms)
usernameCurrent MQTT username
peernameIPAddress and Port of terminal
reasonReason for disconnection of terminal

Here are some common reasons for client disconnections.

typesreason
normalMQTT client disconnects normally
discardedBecause clients with the same ClientID and have clean_start = true set.
takeoveredBecause clients with the same ClientID and have clean_start = false set.
kickedUsing the REST API to kick out clients
keepalive_timeoutMQTT keepalive timeout
not_authorizedAuthentication fails, or Pub/Sub without permission will actively disconnect the client when acl_nomatch = disconnect
tcp_closedThe TCP connection is actively closed by the client
receive_maximum_exceededWhen a client sends a qos2 message, a large number of messages pile up on the MQTT Broker because it does not reply to the PUBREL in time. When the number of message pileups reaches the upper limit, EMQX will actively disconnect
internal_errorMalformed packet parsing error
einvalEMQX wants to send a message to the client, but the Socket has been disconnected
function_clauseMQTT packet format error
etimedoutTCP send timeout (no TCP ACK response received)
proto_unexpected_cMQTT connection request received repeatedly when there is already an MQTT connection
idle_timeout15s after the TCP connection is established, the connect message has not been received
othersPlease refer to MQTT Reason Code and ACK

Message events

Message delivery

The topic of client disconnect is `$events/message_delivered. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/message_delivered"

You can test the SQL, view the return field after firing this rule. message_delivered

The fields are explained as follows.

fieldExplanation
clientidClient ID
eventEvent type, fixed at "message.delivered"
flagsMQTT Message flags
from_clientidMessage source client ID
from_usernameMessage source username
idMQTT message ID
nodeNode name of the trigger event
payloadMQTT payload
peerhostClient IPAddress
publish_received_atTime when PUBLISH message reaches Broker (ms)
qosEnumeration of message QoS 0,1,2
timestampEvent trigger time (ms)
topicMQTT topic
usernameCurrent MQTT username

Message acknowledged

The topic of client disconnect is $events/message_acked. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/message_acked"

You can test the SQL, view the return field after firing this rule. client_acked

The fields are explained as follows.

fieldExplanation
clientidClient ID
eventEvent type, fixed at "message.acked"
flagsMQTT message flags
from_clientidMessage source client ID
from_usernameMessage source username
idMQTT message ID
nodeNode name of the trigger event
payloadMQTT payload
peerhostClient IPAddress
publish_received_atTime when PUBLISH message reaches Broker (ms)
qosEnumeration of message QoS 0,1,2
timestampEvent trigger time (ms)
topicMQTT topic
usernameCurrent MQTT username

Message dropped

The topic of a message dropped is $events/message_dropped, which triggers the trigger rule when a message has no subscribers. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/message_dropped"

You can test the SQL, view the return field after firing this rule. message_dropped

The fields are explained as follows.

FieldExplanation
idMQTT message id
reasonReasons of dropping, possible reasons:
no_subscribers: no clients subscribes the topic
receive_maximum_exceeded: awaiting_rel queue is full
packet_identifier_inuse: send a qos2 message with unreleased packet ID
clientidClient ID of the sender
usernameUsername of the sender
payloadMQTT payload
peerhostClient IPAddress
topicMQTT topic
qosEnumeration of message QoS 0,1,2
flagsFlags
pub_propsThe PUBLISH Properties (MQTT 5.0 only)
timestampEvent trigger time(millisecond)
publish_received_atTime when PUBLISH message reaches Broker (ms)
nodeNode name of the trigger event

Delivery_dropped

The topic of delivery_dropped is `$events/delivery_dropped, trigger rule when subscriber's message queue is full. On the New Rule step page, enter the following rule to match the SQL statement:

sql
 SELECT
     *
 FROM
     "$events/delivery_dropped"

You can test the SQL, view the return field after firing this rule. delivery_dropped

The fields are explained as follows.

FieldExplanation
idMQTT message id
reasonReasons of dropping, possible reasons:
queue_full: the message queue is full(QoS>0)
no_local: it's not allowed for the client to received messages published by themselves
expired: the message or the session is expired
qos0_msg: the message queue is full(QoS0)
clientidClient ID of the sender
from_clientidClient ID of the sender
from_usernameUsername of the sender
usernameUsername of the sender
payloadMQTT payload
peerhostClient IPAddress
topicMQTT topic
qosEnumeration of message QoS 0,1,2
flagsFlags
pub_propsThe PUBLISH Properties (MQTT 5.0 only)
timestampEvent trigger time(millisecond)
publish_received_atTime when PUBLISH message reaches Broker (ms)
nodeNode name of the trigger event

Topic subscribe and unsubscribe events

Subscribe

The topic of client disconnect is $events/session_subscribed. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/session_subscribed"

You can test the SQL, view the return field after firing this rule. session_subscribed

The fields are explained as follows.

fieldExplanation
clientidClient ID
eventEvent type, fixed at "session.subscribed"
nodeNode name of the trigger event
peerhostClient IPAddress
qosEnumeration of message QoS 0,1,2
timestampEvent trigger time (ms)
topicMQTT topic
usernameCurrent MQTT username

Unsubscribe

The topic of client disconnect is $events/session_unsubscribed. On the New Rule step page, enter the following rule to match the SQL statement.

sql
 SELECT
     *
 FROM
     "$events/session_unsubscribed"

You can test the SQL, view the return field after firing this rule. session_unsubscribed

The fields are explained as follows.

fieldExplanation
clientidClient ID
eventEvent type, fixed at "session.unsubscribed"
nodeNode name of the trigger event
peerhostClient IPAddress
qosEnumeration of message QoS 0,1,2
timestampEvent trigger time (ms)
topicMQTT topic
usernameCurrent MQTT username