# Rule engine events

EMQ X Cloud Rule Engine provide event topic 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
$events/session_subscribedSubscribe
$events/session_unsubscribedUnsubscribe

This article will introduce the use of rule engine events, 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"
1
2
3
4

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, 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"
1
2
3
4

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
peernameIPAddress and Port of terminal
reasonReason for disconnection of terminal:
normal: the client is actively disconnected
kicked: the server kicks out, and it is kicked out through REST API
keepalive_timeout: keepalive timeout
not_authorized: auth failed,or acl_nomatch = disconnect, Pub/Sub without permission will disconnect the client
tcp_closed: bad protocol
internal_error: malformed message parsing error
socknameIPAddress and Port listened by emqx
timestampEvent trigger time (ms)
usernameCurrent MQTT username
peernameIPAddress and Port of terminal

# 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"
1
2
3
4

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, 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"
1
2
3
4

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 client disconnect is $events/message_dropped, 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_dropped"
1
2
3
4

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

The fields are explained as follows.

fieldExplanation
clientidClient ID
eventEvent type, fixed at "message.dropped"
flagsMQTT message flags
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
reasonReason for message dropped
timestampEvent trigger time (ms)
topicMQTT topic
usernameCurrent MQTT username

# 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"
1
2
3
4

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, 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"
1
2
3
4

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