Event Topics

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

Event topic name	Explanation
$events/client_connected	Client connect
$events/client_disconnected	Client disconnect
$events/message_delivered	Message delivery
$events/message_acked	Message acknowledged
$events/message_dropped	Message dropped when routing
$events/delivery_dropped	Message dropped when delivering
$events/session_subscribed	Subscribe
$events/session_unsubscribed	Unsubscribe

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, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/client_connected"

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

The fields are explained as follows.

field	Explanation
clean_start	MQTT clean_start
clientid	Client ID
connected_at	Terminal connection completion time (s)
event	Event type, fixed at "client.connected"
expiry_interval	MQTT Session Expiration time
is_bridge	Whether it is MQTT bridge connection
keepalive	MQTT keepalive interval
mountpoint	Mountpoint for bridging messages
node	Node name of the trigger event
peername	IPAddress and Port of terminal
proto_name	Protocol name
proto_ver	Protocol version
sockname	IPAddress and Port listened by emqx
timestamp	Event trigger time (ms)
username	Current MQTT username

Client disconnect

The topic of client disconnect is $events/client_disconnected, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/client_disconnected"

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

The fields are explained as follows.

field	Explanation
clientid	Client ID
disconnected_at	Terminal disconnection completion time (s)
event	Event type, fixed at "client.disconnected"
node	Node name of the trigger event
expiry_interval	MQTT Session Expiration time
sockname	IPAddress and Port listened by emqx
timestamp	Event trigger time (ms)
username	Current MQTT username
peername	IPAddress and Port of terminal
reason	Reason for disconnection of terminal

Here are some common reasons for client disconnections.

types	reason
normal	MQTT client disconnects normally
discarded	Because clients with the same ClientID and have clean_start = true set.
takeovered	Because clients with the same ClientID and have clean_start = false set.
kicked	Using the REST API to kick out clients
keepalive_timeout	MQTT keepalive timeout
not_authorized	Authentication fails, or Pub/Sub without permission will actively disconnect the client when acl_nomatch = disconnect
tcp_closed	The TCP connection is actively closed by the client
receive_maximum_exceeded	When 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_error	Malformed packet parsing error
einval	EMQX wants to send a message to the client, but the Socket has been disconnected
function_clause	MQTT packet format error
etimedout	TCP send timeout (no TCP ACK response received)
proto_unexpected_c	MQTT connection request received repeatedly when there is already an MQTT connection
idle_timeout	15s after the TCP connection is established, the connect message has not been received
others	Please refer to MQTT Reason Code and ACK

Message events

Message delivery

The topic of client disconnect is $events/message_delivered, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/message_delivered"

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

The fields are explained as follows.

field	Explanation
clientid	Client ID
event	Event type, fixed at "message.delivered"
flags	MQTT Message flags
from_clientid	Message source client ID
from_username	Message source username
id	MQTT message ID
node	Node name of the trigger event
payload	MQTT payload
peerhost	Client IPAddress
publish_received_at	Time when PUBLISH message reaches Broker (ms)
qos	Enumeration of message QoS 0,1,2
timestamp	Event trigger time (ms)
topic	MQTT topic
username	Current MQTT username

Message acknowledged

The topic of client disconnect is $events/message_acked, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/message_acked"

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

The fields are explained as follows.

field	Explanation
clientid	Client ID
event	Event type, fixed at "message.acked"
flags	MQTT message flags
from_clientid	Message source client ID
from_username	Message source username
id	MQTT message ID
node	Node name of the trigger event
payload	MQTT payload
peerhost	Client IPAddress
publish_received_at	Time when PUBLISH message reaches Broker (ms)
qos	Enumeration of message QoS 0,1,2
timestamp	Event trigger time (ms)
topic	MQTT topic
username	Current 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. Click on Rules on the left menu bar, click on Create, and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/message_dropped"

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

The fields are explained as follows.

Field	Explanation
id	MQTT message id
reason	Reasons 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
clientid	Client ID of the sender
username	Username of the sender
payload	MQTT payload
peerhost	Client IPAddress
topic	MQTT topic
qos	Enumeration of message QoS 0,1,2
flags	Flags
pub_props	The PUBLISH Properties (MQTT 5.0 only)
timestamp	Event trigger time(millisecond)
publish_received_at	Time when PUBLISH message reaches Broker (ms)
node	Node 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. Click on Rules on the left menu bar, click on Create, and enter the following rule to match the SQL statement:

 SELECT
     *
 FROM
     "$events/delivery_dropped"

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

The fields are explained as follows.

Field	Explanation
id	MQTT message id
reason	Reasons 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)
clientid	Client ID of the sender
from_clientid	Client ID of the sender
from_username	Username of the sender
username	Username of the sender
payload	MQTT payload
peerhost	Client IPAddress
topic	MQTT topic
qos	Enumeration of message QoS 0,1,2
flags	Flags
pub_props	The PUBLISH Properties (MQTT 5.0 only)
timestamp	Event trigger time(millisecond)
publish_received_at	Time when PUBLISH message reaches Broker (ms)
node	Node name of the trigger event

Topic subscribe and unsubscribe events

Subscribe

The topic of client disconnect is $events/session_subscribed, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/session_subscribed"

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

The fields are explained as follows.

field	Explanation
clientid	Client ID
event	Event type, fixed at "session.subscribed"
node	Node name of the trigger event
peerhost	Client IPAddress
qos	Enumeration of message QoS 0,1,2
timestamp	Event trigger time (ms)
topic	MQTT topic
username	Current MQTT username

Unsubscribe

The topic of client disconnect is $events/session_unsubscribed, click on Rules on the left menu bar → Rules, click on Create and enter the following rule to match the SQL statement.

 SELECT
     *
 FROM
     "$events/session_unsubscribed"

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

The fields are explained as follows.

field	Explanation
clientid	Client ID
event	Event type, fixed at "session.unsubscribed"
node	Node name of the trigger event
peerhost	Client IPAddress
qos	Enumeration of message QoS 0,1,2
timestamp	Event trigger time (ms)
topic	MQTT topic
username	Current MQTT username