Create Trace Recordings for a shared subscription

Trace recordings offer a filtered view of what happened for a given set of clients and/or topics on the broker during a defined time period. Generating these recordings with a well chosen filter can make assessing behaviour vastly easier, as only the desired information is logged.

In this guide we will look at how to create a trace recording in the special case of a shared subscription.

Prerequisites

In our example we will be inspecting the topic our/topic to which we will subscribe two clients in a single, joint subscriber group (group00).

Using the MQTT CLI, this can be achieved by running the following commands in separate terminals

mqtt sub -t '$share/group00/our/topic' -h localhost -i client00

mqtt sub -t '$share/group00/our/topic' -h localhost -i client01

These sessions must remain active throughout our entire test.

Configuring the Trace Recording

Initiating, managing and downloading Trace Recordings is done in the HiveMQ Control Center.

Here we must Add New Trace Recording in order to reach the configuration mask.

First, choose a new, unique name. This need not match a topic name and only serves to help identify the recording we are about to create.

Next, we have to define a Topic Filter. Note that we must specify the actual topic here and not include the definition of our share group!

After clicking Add Topic Filter it should become visible as an existing filter:

From here we can select the types of messages we are interested in. As our subscribers are ready and waiting, we are only interested in PUBLISH messages.

Finally, after making sure that Start Date is set to a past time and the selected End Date is far enough into the future to cover our efforts, we are ready to Start Trace Recording.

Don’t worry about timing it just right or otherwise having to wait for your recording to end. Trace Recordings can be stopped at any time

Upon success, your new recording will show up in the overview with the name you specified:

Generate test data

In order to verify our recording works as expected, we will publish messages to the topic.

You can use the following loop to send 10 different messages

for i in `seq 0 9`; do mqtt pub -t 'our/topic' -h 127.0.0.1 -m "message0$i" -i publisher00; done

If your subscriber group is set up correctly, the messages should be split between them. No individual message should be visible to both subscribers in the group.

Inspecting the Trace Recording

Once our publishing run is complete, we may

stop the Trace Recording by clicking stop
have HiveMQ prepare the resulting output by clicking download
and click save to receive the resulting compressed trace recording

After unpacking the downloaded file, the resulting .trace file can be inspected with any text editor.

You should see a Sent and corresponding Received for each message, similar to the following:

Trace Recordings matching a shared subscriber group, as opposed to the topic itself, must escape the dollar symbol as to not be interpreted as a regular expression quantifier. Matching our example subscriber group: \$share/group00/our/topic

Since publishes don’t contain group names, only subscribes of a group can be traced in this way