Overview
mqtt-spy is probably one of the most advanced open source utilities for publishing and monitoring activity on MQTT topics. It is suitable for basic day-to-day usage and power users who need an advanced utility for their MQTT-based systems.
For a brief overview of the functionality take a look at the mqtt-spy blog post (part of the MQTT Toolbox series).
Recently, mqtt-spy featured in:
- Eclipse IoT virtual meet-up (57min): https://www.youtube.com/watch?v=vLrx62MT5_Q
- ThingMonk IoT conference (24min): https://www.youtube.com/watch?v=OTbpUbTO5_I
Don't forget to check out the getting started wiki page.
This brief section lists some of the unique features of mqtt-spy and what makes it different from other tools:
- support for multiple concurrent connections (a tab of each MQTT broker connection)
- high availability (multiple server URIs & automatic reconnection)
- support for all MQTT message/connection properties (e.g. QoS, Retained, LWT, User Authentication, SSL/TLS)
- advanced security with SSL/TLS (support for most common types of handshake and key store types)
- publications
- manual, parametrised and scripted - using JavaScript
- remembering and restoring recently published messages
- subscriptions
- multiple concurrent subscriptions (a tab for each subscription)
- summary of all topics received - with search and filtering
- handling over 1000 messages per second (tried on a standard laptop)
- browsing, searching and filtering for received messages
- message content formatting and conversions (e.g. Hex or Base64 decoding)
- automated testing (using test cases written in JavaScript)
- charts (statistics and message payload-based) and processing statistics
- diagnostic logging, including published and received messages (for more details see Logging)
- message audit log
- UI customisation
- perspectives & customisable pane visibility
- checking for updates at start-up
The mqtt-spy's control panel gives you a quick overview of the following items:
- configuration - when no configuration present click to open the configuration wizard
- list of configured connections and their status - click on the relevant button to perform the action
- update status - checks if there are any new versions of mqtt-spy available
- processing statistics & link to the UNICEF fundraising page
From the main menu you can perform the following actions:
- reload a configuration file (Configuration -> Open file)
- run the configuration creator / restore defaults (Configuration -> Restore defaults)
- create a new connection (Connections -> New connection)
- manage connections - create, edit, copy, delete (Connections -> Manage connections)
- open message log (Logger -> Open message log for off-line analysis)
- change perspective - hides/shows panes or detailed view (Window -> Perspectives)
- open a Base64 converter (Window -> Converter)
- open the wiki pages (Help -> Wiki)
- open the UNICEF fundraising page (Help -> Donate to UNICEF)
- open the project's page (Help -> About)
For information about all the various configuration parameters see the Configuration wiki.
Each connection tab divided into multiple panes:
- Publish message
- Scripted publications
- Define new subscription
- Subscriptions and received messages
To connect, disconnect or close the tab, use the connection tab's context menu. You can also toggle the visibility of all the panes.
Additionally, the connection tab's context menu contains a shortcut to broker's statistics. This is compatible with brokers supporting the $SYS topics - e.g. Mosquitto, HiveMQ or RSMB.
Apart from publishing individual messages, you can also automate message publications by using scripted publications. For more details see the Scripting wiki.
After typing in or selecting the subscription topic, click on the Subscribe button or press Enter.
Once you've created a new subscription, a tab will be created. If you right-click on the tab, the subscription's context menu will appear.
Subscriptions and received messages are the main focus for mqtt-spy. There are a number of ways to find and browse wanted messages: subscribe to the relevant topics or if you don't know which topics to subscribe, just try with "#" or "/#". mqtt-spy will create a list of all the topics it receives messages on.
In the 'Received messages summary' pane, each row in the table represents a single topic, together with the payload of the last message, its time and total message count.
When dealing with hundreds of messages per second, and hundreds or thousands of topics, it might be difficult to find the messages you need. To help with that, you can search for topics containing the given text.
For all actions see the table's context menu.
When hovering over the message index field, the mouse scroll can be used for increasing or decreasing the currently viewed message number.
Once the focus has been given to the message index field, the following actions can be triggered:
- Toggle "Show latest on new" by pressing the Space key
- Show the latest (first) message by pressing the Home key
- Show the oldest (last) message by pressing the End key
- Increasing the message index by 1 by pressing the Up Arrow key
- Increasing the message index by 5 by pressing the Page Up key
- Decreasing the message index by 1 by pressing the Down Arrow key
- Decreasing the message index by 5 by pressing the Page down key
When the focus is on the publication topic field, the following actions can be triggered:
- Publish message by pressing the Enter key
- Restore the X most recent message (ALT + X, where X is 1, 2, 3, 4, 5, 6, 7, 8, 9 and 0; 1 is for the most recent message; 2 for the second most recent; 0 for the 10th most recent)
When you want to find a message with specific content, use the message search functionality. Clicking on the 'Search' button will open a new search window for that subscription tab. Note that any topic filtering will be maintained.
To help you with analysing MQTT traffic, mqtt-spy keeps an in-memory history of received messages. These messages are stored in a list, in which new messages are always added at beginning of the list (that is with index of 1). When a new message is added, all previously received messages are moved by one towards the end of the list.
In order to stop this list growing out of control, there is a limit on how many messages that list can contain. When this limit is reached, the oldest messages from the end of the list will be removed. As this is done once a second, you might see the message count going up (over the configured limit), and then down to the configured value. This significantly improves performance when receiving 100s or 1000s messages per second.
This limit ('Max messages stored') can be defined individually for each connection ('Other' tab of your connection settings).
If however, there are topics with lots of repetitive publications, they might force other useful messages out of the list by pushing them towards the end and as a result, getting them removed. To avoid this, there is another configuration parameter called 'Min messages per topic', which says how many messages to keep for each topic, before any message on that topics gets removed.
This means that in environments with 100s or 1000s messages per second, you can still catch and analyse occasional publications on some less used topics.
For details on creating, replaying or browsing the message log see the Message Audit wiki.
There are a number of ways to export data collected by mqtt-spy:
- Automatically export messages as Message Audit Log
- Export individual topics or message payload - right click the subscription tab or message summary table rows
- Export browsed messages or topics - use the 'Tools' menu button on the 'Subscriptions and received messages' pane; then select 'Export'