HiveMQ Web UI

The HiveMQ Enterprise MQTT broker is able to handle millions of MQTT clients and millions of messages sent and received by those clients. Messaging applications with such a high amount of throughput are usually complicated to manage and monitor, because a lot happens in a very short amount of time. To address this, HiveMQ contains a specialized Web UI which simplifies the process of the day-to-day operation of small and large MQTT deployments by giving you all the tools needed to quickly and easily get the insights you really need.

With the HiveMQ Web UI for advanced analysis and administrative tasks, administrators are able to drill down on specific client information and can perform administrative actions like disconnecting a client. Advanced analytics functionality allows identifying clients with irregular behavior. It’s easy to identify message-dropping clients as HiveMQ shows detailed statistics of such misbehaving MQTT participants. Of course all Web UI features work at scale with more than a million connected MQTT clients.

This document is focused on the features of HiveMQ’s administrative Web UI. If you are looking for general documentation on HiveMQ and all its features, please refer to the HiveMQ User Guide instead.

If you are new to MQTT and want to learn about the specific protocol features and concepts, we recommend to read our MQTT Essentials.

The purpose of this document is to give a in-depth explanation of the features and sections of the administrative Web UI for HiveMQ. This documentation is structured in the same order as the menu items in the Web UI. A table of contents on the left shows all the topics covered by this guide and makes sure that every topic you are looking for is easy to find and quick to navigate to.

Although the Dashboard provides a wide range of information, it is not designed to replace a full monitoring solution. There are better fitting solutions for such purpose and we do recommend running a full-blown monitoring system in conjunction with HiveMQ. Ready-to-use plugins for popular monitoring solutions are available as Off-the-shelf plugins.

Installation

The Web UI is shipped with HiveMQ and enabled by default. No additional installation is needed.

There are multiple configuration options for HiveMQ’s Web UI, including port, TLS and Access Control. See the configuration chapter in the HiveMQ documentation for more information on all the available options.

If you are performing a rolling upgrade from a previous HiveMQ version, older than 3.3.0, the Web UI will be not be fully functional until all nodes in your cluster run HiveMQ version 3.3.0 or later. Information from cluster nodes older than 3.3.0 is not displayed in the Web UI.

HiveMQ cluster

The Web UI is embedded into the HiveMQ process. This means that every HiveMQ cluster node is running its own Web UI which can be accessed separately. Each Web UI will give you access to the information for the whole cluster, so you do not have to access multiple Web UIs to get the insights you need. All data is automatically collected from other nodes in the cluster when needed. The Web UI can be used without needing any knowledge about the underlying cluster setup.

Since a HiveMQ cluster is a distributed system, there are rare situations like network-splits, which can lead to Web UIs from different nodes in the same cluster not having access to the same data.

Accessing the Web UI

The Web UI is a web application which can be accessed from your browser. No dedicated software needs to be installed on a computer which uses the Web UI. The Web UI is already included in the standard HiveMQ distribution.

If you already have a HiveMQ runnning on your local machine, the Web UI will be enabled by default and you can reach it by pointing your browser to the URL http://localhost:8080/.

The default login is the username admin with password hivemq

Your Web UI URL might be different, depending on your specific HiveMQ setup. The Web UI can also be configured to be avaiable via HTTPS. For your specific connection details please consult with your HiveMQ administrator.

For security reasons the Web UI only listens on the local network interface per default. To access the Web UI from another computer the default configuration has to be modified.

All the available configuration options are explained in detail in the Web UI section of the HiveMQ User Guide.

Access Control

To protect the Web UI from unwanted access, the Web UI offers access control in the form of username/password based authentication.

The login site is automatically displayed when accessing the Web UI, if you are not already logged in.

login example
Figure 1. Login Screen
Please change the default password and username to prevent potential attackers from using the defaults. Since the Web UI can show sensitive information, we do not recommend making the Web UI accessible from an unsecured network

The default value for the user is admin and the default password is hivemq. The default values can be changed in the HiveMQ configuration.

The Web UI will automatically log you out after a configurable amount of time.

Once you are logged in, you can log out of the Web UI at any time by clicking on the Logout link in the top right corner of the Web UI.

After a successful login you will be directed to the Dashboard.

Overview over the general Structure

complete view
Figure 2. Dashboard

Every page of the Web UI follows the same makeup. On every site, the top shows the title of the current page. In the top right corner of the page, the username of the currently logged in user is displayed next to the Logout button.

On the left is the menu, clicking on a menu item will take you to one of the following pages:

Table 1. Overview on the tabs
Tab Description

Dashboard

Current status of HiveMQ and the whole cluster.

License

Detailed information on the installed HiveMQ licenses.

Clients

List available clients with drill-down on particular clients

Plugins

List installed plugins

Trace Recordings

List, create and manage trace recordings

Analytics - Dropped Messages

Detailed information on dropped messages

Help

Opens the Web UI User Guide

In the lower left corner the version of HiveMQ is displayed. Please keep the version information on hand when contacting our support.

Throughout the pages of the Web UI a click on the ? icon opens a popup with additional information about the current page. The popup can be closed by clicking on the X in the top right corner of the window or by pressing the ESC key.

Dashboard

The Dashboard shows a quick overview over the current state of HiveMQ and the whole cluster. It gives you a quick insight on the most pressing issues and allows you to check the state of every available cluster node.

Overview over the Dasboard Site
Figure 3. Overview over the Dasboard Site

On the top simple key metrics show the current usage and throughput in the cluster. These key metrics can be displayed in more detail in the Detail View left below of it.

On the bottom of the page detailed information on the license if given on the left and details on the statistics of the cluster nodes are preseneted on the right.

Cluster metrics

This section is designed to give a quick and compact view over important metrics of HiveMQ. The following metrics are displayed on the Dashboard:

cluster total numbers overview
Figure 4. cluster metrics
Table 2. Metrics
Aspect Description

Connections

Current amount of active connections on all nodes

MQTT Messages Incoming

Current amount of incoming MQTT Messages per second over all cluster nodes

MQTT Messages Outgoing

Current amount of outgoing MQTT Messages per second over all cluster nodes

Subscriptions

Current amount of Subscriptions stored in the cluster

Retained Messages

Current amount of Retained Messages stored in the cluster

Queued Messages

Current amount of Queued Messages stored in the cluster

Cluster Nodes

Current amount of Cluster Nodes

Connections

The current amount of active TCP connections between MQTT clients and all HiveMQ nodes.

MQTT Messages Incoming/Outgoing

Current amount of all MQTT messages incoming or outgoing. This metric is calculated by considering the total amount of incoming/outgoing MQTT messages processed by HiveMQ over the last 10 seconds. Incoming messages are messages sent from the client to the broker. Outgoing messages are messages sent from the broker to the client.

Subscriptions

The current amount of topic subscriptions stored on all HiveMQ nodes.

This metric also contains the amount of replicas which are distributed over multiple nodes by HiveMQ’s clustering to prevent data-loss in case of a node failure.

Retained Messages

The current amount of retained messages stored on all HiveMQ nodes.

This metric also contains the amount of replicas which are distributed over multiple nodes by HiveMQ’s clustering to prevent data-loss in case of a node failure.

Queued Messages

The current amount of stored offline queued messages for all clients on all HiveMQ nodes.

Cluster Nodes

The current amount of cluster nodes which form this HiveMQ cluster.

Fore more information on clustering, please visit out clustering benefits blog post.

Detailed Metric View

Below this overview on the total metrics is a more detailed diagram. You can choose the information displayed here by clicking on the headlines in the top section:

Connections is selected
Figure 5. Connections is selected

It is possible to choose any metric of the top section like MQTT Messages incoming:

incoming_messages
Figure 6. Incoming Messages is selected

The chosen metric is underlined in the top section.

Furthermore you can hide and show the information for individual nodes by clicking on them in the legend. The color of the unselected nodes will turn grey in the legend.

Both nodes selected:

Both Nodes are displayed
Figure 7. information on both nodes is displayed

One node deselected:

Only one Node is displayed
Figure 8. Only information on one node is displayed
If you compare both diagrams you will notice that the scale changes automatically.

Another feature is that you can select time intervals to zoom in by clicking in the diagram and dragging until the desired interval is marked:

choosing the time between 10:10 and 10:15
Figure 9. choosing the time between 10:10 and 10:15
zoomed view on the time between 10:10 and 10:15
Figure 10. zoomed view on the time between 10:10 and 10:15

After zooming into the interval (here 10:10 - 10:15), it is possible to zoom in even further:

choosing the time between 10:11 and 10:12
Figure 11. choosing the interval from 10:10 to 10:15
The minimal zoom is 30 seconds:
minimal zoom
Figure 12. minimal zoom

You can reset the zoom by clicking on Reset Zoom in the right upper corner.

While the graph is zoomed in on a time interval the detailed graph will not be updated with new information. After resetting the zoom the graph is updated again.

Attention Log

The Attention Log displays important alerts. For example if there are dropped messages for clients. An alert does not necessarily mean that something is wrong, but it might be an indication that there is some unwanted behaviour has occurred.

The appearance when the number of the connections reaches the maximum by the license allowed number:

maximal connections reached
Figure 13. maximal connections reached

The appearance when messages are dropped:

notification dropping messages
Figure 14. notification dropping messages

The appearance when there are no alerts:

no important notification
Figure 15. no important notification

When no client is connected. Useful links are displayed instead:

no_client_connected
Figure 16. no client is connected

License Information

At the bottom of the page you can find a panel for information on the active license.

If you have not acquired a license, HiveMQ will automatically use a evaluation license limited to 25 concurrently connected clients.
license_information
Figure 17. license information
Table 3. license explanation
Aspect Description

Connections

The number of used connections in relation to maximal number of connections

License type

The validation status and the type of the license (e.g. commercial)

Maximum connections

The maximum number of clients you can connect concurrently using the current license

Cluster license

Indicates whether the current license enables to use HiveMQ clusters

filename

The filename of the current license

License valid until

Expiration date of the current license

License supported until

Expiration date of your support subscription

The color of the connection bar will change depending on the relation:

A green bar indicates that there is still much capacity left before the connection number reaches the maximum number:

green bar
Figure 18. green bar

A yellow bar indicates that most ob the maximum number of connections are used

yellow bar
Figure 19. the maximal number is almost reached

A red bar warns for a forthcoming reaching of the maximum number

red bar
Figure 20. the maximal number is almost reached

If no license is present, a evaluation license is automatically used:

evaluation_license information
Figure 21. evaluation_license information

The evaluation license is limited to 25 connections.

Cluster Node Stats

Right to the license information statistics of each individual node is displayed. The node name is build by random letters to provide a cluster wide unique id, with which the cluster node is identified. The node that hosts this Dashboard is marked with "*" after the node name.

You can choose the node by clicking on the name:

cluster_node_stats_first
Figure 22. stats of the first node (DAVj5)
cluster_node_stats_second
Figure 23. stats of the second node (Ky4lj)
Table 4. cluster node stats explanation
Aspect Description

JVM Memory

This bar graph illustrates currently used memory in proportion to the total available Memory

Disk Space

This bar graph illustrates the currently used disk space of the node in proportion to the total available disc space

Running Since

Timestamp when the node was started

MQTT messages incoming total

The total number of incoming MQTT messages

MQTT messages outgoing total

The total number of outgoing MQTT messages

HiveMQ Version

the current HiveMQ version of this node

Hostname

The Hostname of this node

Network incoming total

The total amount of incoming network traffic

Network outgoing total

The total amount of outgoing network traffic

Network incoming

The current rate of the incoming traffic

Network Network outgoing

The current rate of the outgoing traffic

The color of the bars changes like at the License Information based on the percentage.

Clients

With millions of connected clients, keeping track of specific clients can become a challenge. HiveMQ’s Web UI gives you the tools to list, view and manage all the MQTT clients known to HiveMQ. Insights into subscriptions, connection status, TLS and more provide you with detailed information about every client.

Clients Overview

HiveMQ uses snapshots to display all available MQTT sessions. As a result you need to create a snapshot before information based on that snapshot can be displayed. This provides a better user experience when sorting, filtering or navigating through the available MQTT sessions. Click the “refresh snapshot” button in order to refresh the snapshot with the current state in the cluster. Depending on the number of MQTT sessions of your cluster, refreshing a snapshot may take a few moments. A table with current clients will be displayed. This table can be ordered by clicking on headlines of the table. Furthermore you can filter the displayed clients by inserting the wished clientID, Username or IP Address or by chosing options from the dropdown menues positioned next to the headers of the "Clean Session" and "Connected" column.

This site will not refresh the snapshots on its own. You need to refresh it manually with the "refresh snapshot" button in the right top corner of the table.
clients_overview
Figure 24. clients_overview
Table 5. clients_overview_explanation
Aspect Description

ClientID

The Id of the Client

Clean Session

Indicates whether a client uses a clean session

Connected

Indicates whether a cleint is currently connected

Username

The username of the client. A blanket field indicates that no username was set

Ip Address

The ip address of the client

The current connection status is illustrated by the color. The legend is on the bottom of the site. By clicking on a client a new tab will be opened, showing additional information about the client and enabling actions like disconnecting, subscribing or unsubscribing.

Client Detail View

This site is displayed after a click on a clientID in the overview at the Clients tab.

On the left upper corner information on the ClientID, connection status and session status is displayed:

client_details_header
Figure 25. client_details_header

More information about the Client can be found underneath:

session_information
Figure 26. overview

It is also possible to show more information by clicking on the questionmark. This opens a new window:

help_session
Figure 27. help_session

Session

When a client connects to a MQTT broker, it needs to create subscriptions for all topics that it is interested in in order to receive messages from the broker. On a reconnect these topics are lost and the client needs to subscribe again. This is the normal behavior with no persistent session.
In contrast a persistent session saves all information relevant for the client on the broker. The session is identified by the clientId provided by the client on connection establishment.

For more details on persistent sessions please visit the Persistent Session and Queuing Messages chapter in our MQTT Essentials.

The following information is stored in the session:

session_information
Figure 28. session_information
Table 6. session_information_explanation
Aspect Description

Client Identifier

The unique identifier for this particular client

clean-session

If set to true, sessions will be stateless and information like unfinished message flow and subscriptions will be lost on disconnect

Connected since

Exact time stamp when this client connected

Offline Session TTL

When the client is disconnected for this amount of seconds, stored session information will be deleted

Offline message queue size

The maximum number of messages that will be stored for this client, when he is offline.

Connection

Connections are always between HiveMQ and the Client application never between clients directly. A connection is established by sending a CONNECT message to HiveMQ and HiveMQ replying with a CONNACK message. The protocol used for the connection is tcp and the connection is open until the client disconnects.

For more information on connetions, please visit the Client, Broker and Connection Establishment chapter of our MQTT Essentials.
For more information on keep alive, please visit the Keep Alive and Client Take-Over chapter of our MQTT Essentials.

The connection is described in more detail underneath.

connection_information
Figure 29. connection_information
Table 7. session_information_explanation
Aspect Description

Client-ip

he ip-address of this client

Username

Username of this client

Password

Password of this client

MQTTVersion

The MQTT Version this client uses

Keep-Alive

Interval during which the client is required to send control packets. Otherwise the broker will disconnect the client

Listener

The Listener this client has connected on

Connected Node

The Node this client has connected on

TLS

Transport Layer Security (TLS) is a cryptographic protocol which allows a secure and encrypted communication at transport layer between a client application and a server. If a TLS listener is enabled in HiveMQ, each client connection for that listener is encrypted and secured by TLS. It is also possible to use X.509 certificate client authentication. This is an alternative to the username/password authentication.
This section informs you about the most important aspects like the tls-version, the cipher suite and the certificate.

For more information on TLS please visit the TLS chapter in our documentation.
It is beneficial to also visit the X.509 Client Certificate Authentication chapter to receive further information on x.509 client certificates.

The following illustration shows the most important attributes of TLS:

tls information
Figure 30. tls information
Table 8. tls_information_explanation
Aspect Description

TLSVersion

The version of the procotol which is used.

Cipher Suite

The cipher suite which is used for the encryption of the connection. Cipher suite is a combination of authentication, encryption, message authentication code (MAC) and key exchange algorithms

X.509 client certificate

The certificate used by the client

Right of the cypher suite you have the possibility to display more information on the cipher suite used in the tls by clicking "show more":

cipher suite information
Figure 31. cipher suite information

It is also possible to show more information on the client certificate by clicking on "show certificate":

certificate information
Figure 32. certificate information

The information is divided in two groups, General and Extensions:

Table 9. general_information_explanation
Aspect Description

Common Name

the common name of the owner of the certificate

Organisation

The Organisation of the Subject

Organizational Unit

The organizational unit of the subject

Serial

The serial number of this certificate

x.509 Version

The version of X.509

Valid from

The timestamp from which on the certificate is valid

Valid until

The timestamo to which the certificate is valid

Country

The country of the subject

State

The State of the subject

Table 10. extensions_information_explanation
Aspect Description

Subject Key Identifier

Fingerprint of the key

Last Will

Last will is a feature that is used when a client disconnects ungracefully. The given payload will be published on the last will topic with the given last will Quality of Service.

For more information on the Last Will feature feel free to visit the Last Will and Testament chapter of MQTT Essentials

Each client can specify its last will message (a normal MQTT message with topic, QoS, retained flag and payload) when connecting to a broker.

last will section
Figure 33. last will section
Table 11. lastwill_information_explanation
Aspect Description

Will topic

The topic on which the last will payload will be published

Will QoS

The Quality of Service level the last will message will be published with

Will Retained

Indicates whether the last will message will be a retained message

Will Payload

The payload that will be published when last will is triggered

It is possible to show and download the Last Will payload by clicking "show payload" next to the size of the payload. This opens a new window:

last will payload
Figure 34. last will payload

In this window you can choose how the payload is presented by selecting the option in dropdown menu. It is possible to show the payload as a UTF-8 String, hexadecimal and Binary. Below this dropdown menu the payload is presented in the wished format. At the bottom there are buttons to copy the payload to the clipboard and to download it as a .dat file.

Restrictions

To ensure a trouble-free communication process, some restrictions have to be observed.

restrictions
Figure 35. restrictions
Table 12. restrictions_explanation
Aspect Description

maximum bytes incoming per second

The maximum bytes this client may receive from the broker

Maximum Bytes Outgoing Per Second

The maximum bytes this client may send to the broker

Maximum message size

The maximum payload size in bytes for MQTT PUBLISH messages sent by this client

Proxy Protocol

HiveMQ supports the PROXY protocol for all listener types. The PROXY protocol is a TCP based protocol that allows to transport client details like IP address and port over multiple proxies. This is very useful if you are running your HiveMQ brokers behind a load balancer that proxies the TCP connection. Useful client information like IP address, port and SSL information is lost since the broker only "sees" the TCP connection of the load balancer and not of the original client.

Information Proxy Protocol
Figure 36. Information Proxy Protocol
Table 13. proxy_protocol_explanation
Aspect Description

Source IP/Port

The IP Adress and port of the source

Destination IP/Port

The IP Adress and port of the destination

Additional TLVs

Additional data received through the proxy protocol

For more information on PROXY protocol please visit the PROXY protocol chapter in our documentation.

Subscriptions

This section offers you the possibility to manage the subscriptions of this client. It enables subscribing regularly and using the shared subscription feature of HiveMQ. You can view the topic and Quality of Service level for each subscription. Further you can unsubscribe by clicking on the x at the right side of each line. At the same time you are able to add subscriptions for this client. You need to specify the topic and the Quality of Service.

connection_information
Figure 37. subscriptions
The name of the topic must follow this rules.

In general you are totally free in naming your topics, but there is one exception. Each topic, which starts with a $-symbol will be treated specially and is for example not part of the subscription when subscribing to #. These topics are reserved for internal statistics of the MQTT broker.
Best practices:

Table 14. best_practices
Best Practice Description

Don’t use a leading forward slash

It is allowed to use a leading forward slash in MQTT. But that introduces a unnecessary topic level with a zero character at the front

Don’t use spaces in a topic

A space often make it much harder to read and debug topics

Keep the topic short and concise

Each topic will be included in every message it is used in, so you should think about making them short and concise

Use only ASCII characters, avoid non printable characters

Using non-ASCII UTF-8 character makes it really hard to find typos or issues related to the character set, because often they can not be displayed correctly

Embed a unique identifier or the ClientId into the topic

This helps identifying, who send the message. Another advantage is the enforcement of authorization, so that only a client with the same ClientId as contained in the topic is allowed to publish to that topic

Don’t subscribe to #

Sometimes it is necessary to subscribe to all messages, which are transferred over the broker. This should not be done by using a MQTT client and subscribing to the multi level wildcard. The reason is that often the subscribing client is not able to process the load of messages that is coming its way

Shared Subscriptions

Shared Subscriptions are a unique feature of HiveMQ which allows MQTT clients to share the same subscription on the broker. When using "standard" MQTT subscriptions, each client receives a copy of the message. If shared subscriptions are used, all clients which share the same subscription will receive messages in an alternating fashion. This mechanism is sometimes called "client load balancing".
At the bottom of the site a similar section for shared subscriptions is positioned:

connection_information
Figure 38. shared subscriptions

The table will show any shared subscription this client has with information on the topic, the shared group name and the Quality of Service. You can also unsubscribe it by clicking on the x at the right side of each line. Additionally you are able to add new shared subscriptions to this client by inserting the topic, the shared group and the Quality of Service.

For more information on the Shared Subscription feature feel free to visit our MQTT Client Load Balancing with Shared Subscriptions blog post.

Disconnect a Client

To disconnect a client , click on the Disconnect Client button in the right upper corner

disconnect client with disconnect button
Figure 39. disconnect client with disconnect button

A confirmation shows which allows you to choose, if you want to publish the last will and testament message for the client. If the client did not set a last will and testament message upon connect, the option is disabled.

disconnect client
Figure 40. disconnect client

License

This site is designed to give a detailed view over the aspects of the current license. Further it informs about important events regarding the license like expiration.

It is possible to install new licenses on the fly by putting the license-file in the license-folder of HiveMQ. You will not have to restart HiveMQ, what would be critical in many use-cases.

Further it is possible to have more than one license installed. HiveMQ will recognize multiple license files and will automatically use the license file with the highest concurrent connections or the license which is valid the longest.

To purchase a licenses please contact sales@hivemq.com. More information about the license and installing licenses can be found at the installing a hivemq license chapter of your HiveMQ documentation.

Installed license

The perspective of this site depends on the status of the license. If more than one license is installed all licenses are displayed.

Only the licenses installed on the current node are displayed.
Complete view on the license site
Figure 41. Complete view on the license site
If no license is installed, a evaluation license will automatically be used. This license is limited to 25 concurrent connections. in Evaluation license the appearance without a installed license is explained.

The table provides following useful information on the current license:

license_table
Figure 42. license_table
Table 15. license_table_explanation
Aspect Description

License Warning

Indication of your license expiring

Connections

Number of concurrent clients this license allows

Cluster license

Indicates whether the current license enables the use of HiveMQ cluster

Filename

The filename of the current license

Start Date

The date of the start of this license

End Date

Expiration date of the license

Supported until

The expiration date of your support subscription

Issued to

The Owner of this license

Contact

Contact information

Email

Email-Adress of the named contact

Furthermore a warning will be displayed if your license is to expire the next time.

forthcoming expiration warning
Figure 43. forthcoming expiration warning

If your license expired, a evaluation license will be used automatically and the old license will be displayed too.

license expiration
Figure 44. license expiration

Evaluation license

If no license is provided, HiveMQ uses a free evaluation license automatically:

Evalution license appearance
Figure 45. Evalution license appearance

Plugins

In Enterprise environments, MQTT Brokers are rarely deployed without deep integration to existing systems. HiveMQ was built to be ultra-flexible and can be integrated with virtually every existing application for message processing, security, monitoring or complex business logic. The free and open source plugin system allows to develop custom integration in minutes. Besides free off-the-shelf plugins for download, complex enterprise integrations are available as well.

Installed plugins

This site gives you information on the installed plugins of HiveMQ on the node which hosts this site. It lists the name, the author and the version of the plugin:

plugins_table
Figure 46. plugins_table

Available Plugins

For list of already available plugins check out our Off-the-shelf plugins.

HiveMQ’s Open-Source plugin SDK enables you to build your own plugin with custom logic. Please see the Plugin Developer Guide for more information.

Trace Recordings

Usually a MQTT broker sends and receives millions of MQTT messages during a small period of time. To find out what is really happening with a client or on a topic by analysing all information from the broker is very time-consuming. For an easier approach in doing this, HiveMQ provides the ability to write log files for clients and topics.

A Trace Recording is a combination of filters which allows you to select messages of specific clients or topics, which are logged to a file in a human readable format. Each trace recording creates a .trace file in your HiveMQ log/recordings folder. Trace recordings are created cluster-wide and every HiveMQ cluster node writes its own trace files in its own log folder.

You can log any MQTT message sent or received by the broker with a filter you apply. A Filter can either be a client identifier or a topic. Many filter combinations are possible. All filters are regular expressions.

To add a trace recording click the Add New button in the right upper corner. More information on adding a trace is given at the Add new Trace Recording part.

The trace recording log file is stored as trace-recording-name.trace in hivemq/log/recordings.
Trace Site View
Figure 47. Trace Recordings Site

There are four attributes, which define a trace recording explained in the table below.

Table 16. information_active_traces
Attribute Description

State

Running Running, Waiting Waiting, Stopped Stopped or Aborted Aborted

Name

The Name of the trace recording log file

Start

The start date, when HiveMQ begins to record messages for a trace recording

End

The end date, when HiveMQ stops to record messages for a trace recording

Active Trace Recordings

Active trace recordings are all trace recordings in the state 'Running' Running or 'Waiting' Waiting

Active trace recordings can be viewed, stopped and deleted.

View a trace recording by clicking on its name. For more detail, have a look here: Trace Recording Details
Stop a trace recording by clicking ⇒ Stop

A stopped trace recording is still available in your HiveMQ log/recordings folder and in the Finished Trace Recordings table, but cannot be started again.

Delete a trace recording by clicking ⇒ Delete

A deleted trace recording is not visible anymore. All its log files are deleted from disk.
Active Trace Recordings
Figure 48. Active trace recordings table

Finished Trace Recordings

Finished trace recordings are all trace recordings in the state 'Stopped' Stopped or 'Aborted' Aborted

Finished trace recordings can be viewed and deleted.

View a trace recording by clicking on its name. For more detail, have a look here: Trace Recording Details

Delete a trace recording by clicking ⇒ Delete

A deleted trace recording is not visible anymore. All its log files are deleted from disk.
Finished traces table
Figure 49. Finshed traces table

Trace Recording Details

If you clicked on the name of a trace recording, you will be redirected to 'Trace Recording Details', where you can see the sections 'Basic Settings', 'Filters' and 'Trace Recording Contents'. All information is read only. For more detail about the sections see Add new Trace Recording

As well as in the tables you can stop a trace recording by clicking ⇒ Stop

A stopped trace recording is still available in your HiveMQ log/recordings folder and in the Finished Trace Recordings table, but cannot be started again.
Trace Recording Details
Figure 50. Trace Recording Details

Add new Trace Recording

To add a new trace recording to your HiveMQ click the Add New button in the right upper corner of the Trace Recordings page.

There are three sections with required information: Basic Settings, Filters and Trace Recording Contents

At the top right corner is either a Start Trace button or a Schedule Trace button.
When the start date is in the future, the trace recording will be scheduled. When the start date is now or in the past, the trace recording is started instantly.

Site for adding a new Trace
Figure 51. Site for adding a new Trace

Basic Settings

All fields in 'Basic Settings' are required. If any field failed to validate, you get a red warning message below the corresponding input field.

Choosing the basic settings
Figure 52. Choosing the basic settings

Name
The name defines the filename of the .trace log file in your HiveMQ log/recordings folder. It must be unique, contain at least three characters and only combinations of numbers, letters, dashes and underscores are allowed. E.g. 'publishing-clients', 'subscribe_my_topic_1' etc.

Start
When the start date is now or in the past, HiveMQ will start recording log messages immediately after successfully creation of the trace recording. When the start date is in the future, HiveMQ will schedule the trace recording. The default value is now.

It must be before the end date and must have this format: yyyy-MM-dd HH:mm:ss
E.g. 2017-10-18 19:42:00

If the start date is after the end date, you can either change the end date or the start date to make the date fields valid.

You can type date and time into the input field or click on the calender icon to choose date and time per mouse. See below.

date time chooser

End
The end date determines when HiveMQ stops the trace recording. The default value is now plus one hour.

The end date must be in the future and after start date. It must have this format: yyyy-MM-dd HH:mm:ss
E.g. 2017-10-18 20:42:00

If the end date is before start date, you can either change the end date or the start date to make the date fields valid.

You can type date and time into the input field or click on the calender icon to choose date and time per mouse. See below.

date time chooser

Filters

At the filters section, you can add Client Identifier and Topic filters to the trace recording. At least one filter (ClientID or Topic) must be set. Filters are based on regular expressions.

For more information about regular expressions please look here.
Choosing the filters
Figure 53. Choosing the filters

You can set and combine as many ClientID and Topic filters as you want. Contents are recorded, if at least one filter of each category matches. For example, if you set two ClientID filters 'client1' and 'client2' and one Topic filter 'my/topic' all chosen contents will be recorded for 'client1' and 'my/topic' as well as for 'client2' and 'my/topic'.

example filters
Figure 54. Three filters example
Table 17. Possible_filters
Filter Instructions

Client Identifier:

To add a Client Identifier filter, just type a regular expression into the field below and then press Enter or click the Add ClientID Filter Button

Topic:

To add a Topic filter, just type a regular expression into the field below and then press Enter or click the Add Topic Filter Button

To remove a filter click on "x" of the filter you want to remove.

Trace Recording Contents

In this section you can choose what kind of MQTT messages should be traced. MQTT Messages are messages sent or received by MQTT clients and MQTT brokers You can select the following MQTT Message types to be logged. At least one message type must be selected:

Client filters can be used to filter any kind of MQTT message, while topic filters apply only for MQTT messages which contain a topic. These are PUBLISH, SUBSCRIBE and UNSUBSCRIBE.
Choosing the trace recording contents
Figure 55. Choosing the trace recording contents
Table 18. Possible MQTT Messages
Content Description

CONNECT

A CONNECT message is sent to the broker, when a client connects to a broker

CONNACK

A CONNACK message is sent to the client, when a broker acknowledges the connection of a client

SUBSCRIBE

A SUBSCRIBE message is sent to the broker, when a client subscribes to a topic

SUBACK

A SUBACK message is sent to the client, when a broker acknowledges the subscription of a clien

PUBLISH

A PUBLISH Message is sent to the broker, when a client publishes to a topic

PUBACK

A PUBACK message is sent to the client, when a broker receives a PUBLISH with QoS 1

PUBREC

If a broker gets a QoS 2 PUBLISH it will process the publish message accordingly and acknowledge it to the sender with a PUBREC message

PUBREL

If the client receives the PUBREC it can safely discard the initial publish, because it knows that the counter part has successfully received the message. It will store the PUBREC and respond with a PUBREL Message

PUBCOMP

If the broker gets the PUBREL it can discard every stored state and answer with a PUBCOMP. The same is true when the sender receives the PUBCOMP.

UNSUBSCRIBE

An UNSUBSCRIBE message is sent to the broker, when a client wants to remove a subscription from a topic

UNSUBACK

A broker will acknowledge the request to unsubscribe with the UNSUBACK message.

PINGREQ

A PINGREQ is sent by the client and indicates to the broker that the client is still alive.

PINGRESP

When receiving a PINGREQ the broker must reply with a PINGRESP packet to indicate its availability to the client.

DISCONNECT

A DISCONNECT message is sent to the broker, when a client disconnects from a broker

To learn more about the MQTT Message types, have a look at our MQTT Essentials

A sample configuration might look like:

Chosen trace recording contents
Figure 56. Chosen trace recording contents

Finish Trace Recording Creation

After you configured the trace recording you can press the "Start/Schedule Trace Recording" button in the top right corner. In case you configured something wrong, a notification with the invalid settings is displayed:

invalid trace settings
Figure 57. invalid trace recording settings

If everything is configured correctly, a confirmation with a duration will be displayed. You can stop the process by clicking "Cancel". To confirm the trace recording press "Start/Schedule" and the trace recording will be added to HiveMQ and you will be redirected to Trace Recordings.

The trace recording log file is located in HiveMQs log/recording folder.
confirm
Figure 58. Confirm to start the trace recording
Regular Expressions

Regular Expressions or short regex are search patterns to find any matching character sequences .

For example if you want to find all names with ik in it, the paatern would be simple ik.

If you want to find all words with a a followed by at least one n, the regex would be an+. The + works as quanitification. It defines that at least one n must follow the a. This regex would find sequences like an, ann , annn, but not a, n, na.

These quantifiers always refer to the expression before:

  1. a+: + refers to a

  2. [a-c]+: + refers to [a-c]

There are more quantifiers: .quantifiers

Quantifier

Description

Example

matches

matches not

?

one or zero times

ha?llo

hallo hllo

haallo

*

zero or more times

ha*llo

hllo, `hallo, haallo, …​.

hakallo

+

one or more times

ha+llo

hallo, haallo, haaallo

hllo

{number}

exactly number-times

hal{2}o

hallo

halo, hao, halllo`

{min, }

at least min times

hal{2,}o

hallo, halllo

halo

{min, max}

at least min and maximal max times

hal{1,2}

halo, hallo

hao, halllo

With the brackets [ ] a set of characters can be defined that matches a single character of this set. For example h[a, e]llo matches hallo and hello. It is possible to set ranges to: [c-f] would match c, d, e and f.

Further it is possible to use the wildcard-character: . to match any character. For example h.llo matches hallo, hbllo, h llo, and so on.

Combined with the quantification * any string can be matched with .* .

As many characters are used as metacharacters they need to be escaped with a leading \ to be used as character:

Table 19. metacharacters

Metacharacter

escaped

*

\*

+

\+

.

\.

[ and ]

\[ and \]

{ and }

\{ and \}

( and )

\( and \)

\

\\

|

\|

Analytics

Dropped Messages

This site enables you to analyse dropped messages. A dropped message is a message which is not published by the broker due to reasons explained below. The following aspects can be analysed:

Detailed information on the reasons for dropped messages is given at the end of this section.
complete view over the site
Figure 59. complete view over the site

Dropped messages by reason

The reasons why messages were dropped, are visualized on the top of the page.

The left diagram visualizes the count of dropped messages over the last hour grouped by the reason.

dropped messages grouped by reason (stacked)
Figure 60. Dropped messages grouped by reason (stacked)

You can select or deselect specific reasons by clicking on them in the legend of the diagram. The diagram is updated every 10 seconds.

The right pie chart visualizes the total count of dropped messages and the percentage of every reason.

Dropped message reasons
Figure 61. Dropped message reasons

You can select or deselect specific reasons by clicking on them in the legend of the chart.

Message are dropped because of the following reasons:

Table 20. Reasons for dropping messages
Reason Description

Internal error

Messages that were dropped because of internal errors.

Before publish send

Messages that were dropped because an exception was thrown inside a BeforePublishSend callback.

Client not connected

Messages that were dropped because a client using a clean session disconnected.

Message queue full

Messages that were dropped because the offline message queue for this client was full.

Inflight queue full

Messages that were dropped because the inflight queue was full.

QoS 0 queue not empty

Messages with Quality of Service 0 that were dropped because of a not empty queue for this client.

QoS 0 channel not writable

Messages with Quality of Serice 0 that were dropped because it was impossible to write to the client socket.

Clients with dropped messages

This table contains the first 100 Clients per Node that dropped messages in the last four days:

dropped messages grouped by reason (stacked)
Figure 62. clients dropping messages
Table 21. dropping_clients
Reason Descriptions

ClientID

The id of the Client that dropped messages

First Message Dropped

The timestamp of the first message the Client dropped

Last Message Dropped

The timestamp of the last message the Client dropped

Internal error

Messages that were dropped because of internal errors.

Before publish send

Messages that were dropped because an exception was thrown inside a BeforePublishSend callback.

Client not connected

Messages that were dropped because the client using a clean session disconnected.

Offline message queue full

Messages that were dropped because the offline message queue for this client was full

Inflight queue full

Messages that were dropped because the inflight queue was full.

QoS 0 queue not empty

Messages with Quality of Service 0 that were dropped because a not empty queue for this client

QoS 0 channel not writable

Messages with Quality of Service 0 that were dropped because it was impossible to write to the client socket

It is possible to filter against a given ClientID: Only clients with ClientIds starting with the given filter will be displayed. You can also sort the table by the value of each row ascending and descending by clicking on the corresponding header.

By clicking on a Client you can navigate to the Client Detail View. Furthermore you can clear all data stored with the "Clear Data" - button located on right side above the table. Additionally there is the possibility to refresh the data by pressing the ""Refresh Data" - button

Shared subscription groups with dropped messages

This table represents information about Shared Groups which dropped messages during the last four days. The maximum number of Shared Groups a node can store is 100.

Shared Subscription Groups dropping messages
Figure 63. Shared Subscription Groups dropping messages
Table 22. dropping_clients
Reason Descriptions

Shared Group

The id of the Client that dropped messages

First Message Dropped

The timestamp of the first message the Client dropped

Last Message Dropped

The timestamp of the last message the Client dropped

Internal error

Messages that were dropped because of internal errors.

Client not connected

Messages that were dropped because a client without a persistent session disconnected

Inflight queue full

Messages that were dropped because the inflight queue was full

Detailed explanation of the reasons

Internal Error

If an internal error occurs during handling a message, the message gets dropped. The reason for the internal error is not specified. For more information check the HiveMQ log.

Client not connected

If a message is published to a client which set the cleanSession option to true in its connection and the client disconnects during the publishing process, the message gets dropped.

Before publish send

Plugins can implement BeforePublishSend callbacks. These callbacks will be called before any publish is sent. If an exception is thrown in this callback, the publish process is stopped and the message gets dropped.

Offline Message Queue full

An offline client with a persistent session has a offline message queue, in which the messages which would be published to the client are stored until the client reconnects. When this queue is full, new incoming messages get dropped.

Inflight Message Queue full

If a client consumes messages at a lower rate than the messages are published to the client, messages with QoS 1 or 2 get queued in the inflight queue for the client. When this queue is full, new incoming messages get dropped.

QoS 0 Queue not empty

After a client with a persistent session reconnects, it receives the messages stored in its offline queue. This process may take soem time. When the offline queue is not empy yet and a message with QoS 0 would be published for the client, the message is dropped.

QoS 0 Channel Not Writable

Messages with QoS 0 that are dropped because the socket of the client could not be written on. This is caused by a client not being able to read fast enough to keep up with the incoming messages.