Client and subscription management

Why this matters

The most common situation in a smart home is a device that is "set up correctly and still receives nothing". To track that down, you first have to be able to answer a few things: which client is connected, which topics it actually subscribed to, and whether the messages went out at all. The Clients and Subscriptions pages in EMQX are where those connection facts are spelled out.

This chapter gives you a routine for diagnosing a dropped connection: start at the Clients list to see who is online and which device still has a session, move to Subscriptions for the subscription details, and finish with the slow subscription and topic monitoring tools (and the license each one needs). After that, a problem like "nothing is coming through" no longer takes guesswork — you can narrow it down in the Dashboard first.

Core concepts

The Clients page in EMQX shows the clients connected right now, and the sessions that have not expired yet. A connection is one live MQTT channel; a session is the state EMQX keeps on that client's behalf, and once the connection drops it still exists for some seconds if the client asked for a persistent session and gave a session expiry interval. So the Clients list is not only the devices that are online this second.

The Subscriptions page lists every subscription as one client ID and topic pair, and adds QoS and the new MQTT 5.0 subscription options; the Topics tab deduplicates by topic name, so the same subscription on one node is listed only once.

One boundary before anything else: Slow Subscriptions and Topic Metrics are EMQX Enterprise features, and the Diagnose group in the sidebar of Open Source 5.8.9 does not show them. Knowing where that line falls saves you from hunting for a tool that a self-hosted Open Source install never had.

Terms at a glance

Hands-on

1. Open the Clients list

   In the sidebar, pick Monitoring → Clients. It shows the currently connected clients by default, with columns for client ID, username, connection status, IP, heartbeat, session information and the time the connection completed.

2. Find one device with a filter

   The search bar at the top does a fuzzy search on client ID or username; expand the arrow on the right for filter fields such as connection status, time range and target IP.

3. Look at one client in detail

   Click a client ID in the list to open its connection detail page. The top right lets you refresh by hand and clear the session by hand; further down you can see the topics this connection currently subscribes to.

4. Kick a client out

   Back in the list, tick a client and press Kick Out to break the connection. If that client has a persistent session with a session expiry, it maps back onto the same session when it reconnects.

The Clients list and client details

At the top of the list, Select Column lets you choose which columns are shown; Refresh resets every filter and reloads. The IP address column puts the client's source IP and the port it came in on together in one field.

The detail page adds a few things to the basics already in the list: the protocol version the connection uses (MQTT 3.1.1 or 5.0, for example), whether the session is to be cleaned up once the client goes offline, and — if it is offline already — the time it last went offline.

The information at the top of the detail page splits into two panels: Connection Information, and Session Information on the right. The session fields cover the session expiry interval, the creation time, the number of subscriptions, the message queue length, the inflight window length and the QoS2 receive queue length.

Below that come the traffic, message and packet statistics, which make it easy to read the in and out volume of a single client. The bottom of the page is the topics it subscribes to right now: press Add Subscription to add a simple subscription, or Unsubscribe in the list to cancel one.

Subscriptions and Topics

The Subscriptions page lists the subscriptions of every connection in columns keyed on "client ID + topic", including QoS and the new MQTT 5.0 subscription options:

• No Local: set to 1, the server does not forward your own messages back to you.
• Retain As Published: sets whether the RETAIN flag is kept when a message is forwarded (this has nothing to do with the RETAIN flag on a retained message itself).
• Retain Handling: when the server sends retained messages on subscribe. 0 = send as soon as the subscription succeeds; 1 = send only when no earlier subscription exists; 2 = never send.

The search bar carries three filter fields by default: Node, Client ID and Topic; expand the arrow and you can also fill in QoS and the shared subscription name (Shared Name).

The Topics page takes the topics currently subscribed to on every node, deduplicates them into one list, and lets you fuzzy-search it. Create Monitor on a row takes you to Diagnose → Topic Metrics to set up monitoring for that topic.

Reminder: Subscriptions counts per client, Topics counts per topic; the same topic can be subscribed to by several clients at once, which is why both views matter.

Slow subscriptions and topic monitoring (Enterprise)

When a device is clearly online but slow to receive messages, EMQX's Slow Subscriptions can measure the latency from the moment a message reaches EMQX to the moment it finishes being sent. Once you enable it under Diagnose → Slow Subscriptions, you can set the statistics threshold (Stats Threshold, 100ms minimum), the record limit (1000 records at most), how long a record is kept before it is dropped (300 seconds by default), and the calculation method (whole/internal/response).

The list is sorted from the longest latency down, with columns for Client ID, Topic, Duration, Node and Updated; click a Client ID to open that client's details and dig deeper.

Topic Metrics measures one named topic instead: add a monitor under Diagnose → Topic Metrics (or with Create Monitor on the Topics page) and give it a topic name. Note that this feature does not take wildcards — neither + nor # is supported today; only a full topic name works.

Both are EMQX Enterprise only. On Open Source 5.8.9 they are simply not in the Diagnose group of your sidebar.

Troubleshooting

• A device is missing from Clients: fuzzy-search by client ID or username first, and confirm it really did connect. If it is offline already, its session may still be there, which makes it look online.
• The same client is back right after a Kick Out: a client on a persistent session reconnects to that same session within the session expiry interval. To keep it out, use Authentication/ACL or the Blacklist rather than kicking it by hand every time.
• Subscribed to a topic, but nothing arrives: on the Subscriptions page, check whether that subscription's QoS or No Local is set wrong. Then subscribe to the same topic once more with the subscription tool in Diagnose → WebSocket Client, to confirm the broker is publishing at all.
• Slow Subscriptions or Topic Metrics is nowhere to be found: both are Enterprise features. On Open Source 5.8.9, use the statistics columns in Clients and Subscriptions for a rough read instead.

FAQ

Official sources

• EMQX 5.8 Clients list and details (pinned docs branch)
• EMQX 5.8 Subscription Management (pinned docs branch)
• EMQX 5.8 Slow Subscriptions statistics (pinned docs branch)
• Woow EMQX add-on README (pinned commit)