Message and topic management
EMQX message and topic management: publishing messages, managing retained messages, the topic tree, Topic Metrics and Delayed Publish.
Why this matters
MQTT messages work on a publish/subscribe model: the broker does not file them away and keep them forever unless you set the retained flag. So the questions "was that message actually kept, which topic is it on, did it go out the way I expected" get their answers on the handful of message management pages in the Dashboard.
This chapter walks you through the Dashboard features that deal with messages and topics: the WebSocket Client you publish and test with, managing and configuring retained messages, the way into the topic overview, and (on Enterprise) Topic Metrics and Delayed Publish. By the end you will be able to answer "where is that message now".
Core concepts
Retained Message: when a client publishes a message with the RETAIN flag, EMQX stores it in the system. From then on, any client that newly subscribes to that topic receives the retained message immediately. By default it never expires, unless you delete it by hand.
The Dashboard's Monitoring → Retained Messages page lists every retained message there is right now (topic, QoS, publisher, publish time). Press Show Payload to read the content, or Delete to remove one.
Delayed Publish is an EMQX Enterprise extension: a message published to `$delayed/{DelayInterval}/{Topic}` goes out after the number of seconds you specify. It and retained are two different tools — this one delays the publish, it does not hold on to the latest message.
Know where the line is: Delayed Publish and Topic Metrics are both EMQX Enterprise features, and the Open Source 5.8.9 Dashboard does not show them.
Terms at a glance
| Term | Plain English | What it means |
|---|---|---|
| Publish | send a message | A client writes one message into a topic |
| Subscribe | ask to receive | A client's declared interest in receiving messages on a topic |
| Payload | the message body | The data a message carries (a string, JSON, binary) |
| Retained Message | the message the broker keeps | A message the broker remembers and delivers immediately to a new subscriber |
| Retainer | retained message settings | The settings tab that manages the retained message feature |
| Delayed Publish | send it later | An MQTT extension that delays delivery, based on the $delayed/ prefix |
Hands-on
Open the Retained Messages page
In the sidebar, choose Monitoring → Retained Messages to see the list of every retained message in the system right now.
Read one message's payload
In that row's Actions column, press Show Payload; the content opens below. You can pick a format such as JSON or Hex, and Copy at the bottom right copies it.
Delete one retained message
Press Delete on the row to remove it, or use Clear All to clear the retained messages across the whole cluster.
Try publishing with the WebSocket Client
In the sidebar, choose Diagnose → WebSocket Client, add a connection, and use subscribe/publish to check a topic and its retained behavior quickly.
Managing retained messages and their settings
At the top left of the list are Show Payload and Delete; at the top right, Refresh reloads the list. Settings takes you to the Management → MQTT Settings → Retainer tab, where you can enable or disable the retained message feature and set several parameters.
| Setting | Default | What it means |
|---|---|---|
| Storage Type | Built-in Database | The storage backend |
| Storage Method | ram | ram: memory only; disc: memory plus disk |
| Max Retained Messages | 0 | 0 = no limit; past the limit, new messages replace old ones |
| Max Payload Size | 1MB | Anything larger is treated as an ordinary message and not retained |
| Message Expire Interval | Never | 0 = never expires; you can have it deleted automatically after a number of hours |
By default EMQX keeps three retained messages on $SYS system topics (the node description, the version and the cluster node list, for example). To clear the retained message on a topic, the usual way is to publish an empty message to that topic.
Topic overview and Topic Metrics
The Dashboard's Monitoring → Subscriptions → Topics tab takes every topic currently subscribed on any node, removes the duplicates, and lists what is left. You can find a topic with a fuzzy search, and press Create Monitor in the Actions column to go to the Topic Metrics page.
Topic Metrics is a diagnostic tool in EMQX Enterprise, at Diagnose → Topic Metrics. Its job is to count message volume for one specific topic and nothing else.
When you add one, you have to type a complete topic name; topic filters that carry a wildcard (`+`, `#`) are not supported at present. Something written as a/+ cannot be turned into a metric.
In the list's Actions column, View opens the details (broken down by QoS), Reset starts the count over, and Delete removes the entry.
Delayed Publish (Enterprise)
Delayed Publish is EMQX's MQTT extension: when the topic a client publishes to starts with $delayed/, EMQX holds the message back for a while before it goes out on the real topic.
The format is:
$delayed/{DelayInterval}/{TopicName}$delayed/15/x/y: published tox/y15 seconds later.$delayed/60/a/b: published toa/bone minute later.$delayed/3600/$SYS/topic: delivered to$SYS/topicone hour later.
{DelayInterval} can go up to 4294967 seconds; if it cannot be parsed as an integer, EMQX drops the message.
To manage the feature, open Management → Delayed Publish in the sidebar, where you can enable or disable it and cap the number of delayed messages.
Troubleshooting
- You subscribed to a topic but no retained message arrived: check that the retained message is still there (it shows on the Retained Messages page). Once it is deleted, it is not sent again.
- You want to delete a topic's retained message but cannot reach Delete: the more common approach is to publish an empty message to that topic with RETAIN, which also overwrites the old one.
- You cannot find the Delayed Publish or Topic Metrics page: both belong to EMQX Enterprise. The Open Source 5.8.9 Dashboard does not show them, and nothing is broken.
- Topic Metrics rejects what you type when you add one: the feature only supports a single topic at present, not the
+/#wildcards. Create it again with a complete topic name.
FAQ
Does a retained message expire on its own?
Not by default. It stays until you delete it, overwrite it with an empty message, or give it an expiry time in the Retainer settings (Message Expire Interval). You can also carry a different expiry in seconds on the PUBLISH packet, and the value on the PUBLISH wins.
Why do subscribers get the old value after I publish the retained message again?
Usually because that retained message has already been cleared, or because the new publish went out without the RETAIN flag. Publish a new message to the same topic with RETAIN and the retained message overwrites the old value in the same fields on the same topic.
Are Delayed Publish and retained the same thing?
No. Retained means "remember the last message so every new subscriber gets it immediately"; Delayed Publish means "send it later" (the `$delayed/` prefix). You can use both together, but they play different parts, and Delayed Publish is an Enterprise feature.
Why can't Topic Metrics use a/+?
The official documentation spells it out: Topic Metrics supports a single topic name only, which means the `+` / `#` wildcards are not supported at present. To monitor a topic, use one definite topic name.