Available Control Center Information
The pages of the HiveMQ Control Center have a consistent look and feel. The top of each page provides the title of the page, the user name of the person who is currently logged in, and a Log out option.
The version number of the HiveMQ version that you are currently running appears below the side navigation. Please keep the version information on hand when you contact our support.
To view more information about an item in the control center, click the question mark (?) next to the desired item.
By default, the control center contains the following pages:
| Page | Description |
|---|---|
Shows the current status of HiveMQ and each node in the HiveMQ cluster (including notifications, license information, and key metrics) |
|
Overview of all available clients with links to further client details |
|
Overview of all available shared subscriptions with links to further shared subscription details |
|
Overview of all available retained messages with links to further retained message details |
|
Provides detailed information on the active and inactive HiveMQ licenses that are associated with the HiveMQ installation |
|
Overview of all current trace recordings, with links to create and manage trace recordings |
|
Detailed information on dropped messages |
|
Help |
Opens the HiveMQ Control Center User Guide (this page) |
|
HiveMQ Enterprise Extensions add additional pages and features to your control center. For more information, see HiveMQ Enterprise Extensions.
|
Dashboard
The dashboard of the control center provides a clear overview of the current state of HiveMQ and your entire cluster. This information gives you immediate insights on key issues and allows you to quickly check the state of each available cluster node.
At the top of the dashboard, an overview bar shows you key metrics such as the current usage and throughput of the cluster at a glance. For more information on a specific metric, click the metric in the overview bar to open a detail view.
Notifications
The Notifications area of your dashboard displays useful information and alerts. For example, information if a client drops a message. An alert does not necessarily mean that something is wrong. However, an alert can indicate that an unwanted behaviour has occurred.
Notification area with connection-limit alert:
Notification area with connected clients and no alerts:
Notification area with no connected clients that displays useful links:
Active License Information
This area of the control center dashboard shows information about the HiveMQ license that is currenly in use.
| Item | Description |
|---|---|
Cores Used |
The number of CPU cores that are currently in use and the maximum number of cores that the selected license allows |
License Type |
The validity status and the type of license (for example, valid commercial license) |
Maximum Cores |
The maximum number of CPU cores the current license allows |
Edition |
The variant for which the license is valid. HiveMQ is available in three different editions:
|
Filename |
The filename of the license that is currently in use |
License Expiration Date |
Expiration date of the license that is currently in use |
Based on the maximum number CPU cores the active licence allows, the cores status bar shows the current CPU capacity of the selected node:
A green bar indicates that less than 75% of the CPU cores that the active license allows are in use.
A yellow bar indicates that more than 75% of the CPU cores that the active license allows are in use.
A red bar indicates that more than 90% of the CPU cores that the active license allows are in use.
| If no valid license is availalble in the licence folder of your HiveMQ installation, an evaluation license is used automatically. Evaluation licenses are limited to 25 concurrent connections. For more information, see Evaluation license. |
Cluster Node Statistics
The statistics area of your control center dashboard shows information for each individual node in your cluster. Nodes are identified with a randomly-generated cluster node ID. An asterik (*) after the cluster node ID indicates the node that is used for the HiveMQ control-center connection.
To view statistics for a node, click the node ID.
The following metrics are avaialble for each node in the cluster:
| Metric | Description |
|---|---|
|
The amount of the JVM-memory heap space that is in use and the total amount that is avaialable |
|
The amount of disk space where the HiveMQ data folder is located that is in use and the total amount that is available |
|
The startup time of the selected node |
|
The total number of inbound publish messages |
|
The total number of outbound publish messages |
|
The HiveMQ version the selected node runs |
|
The network hostname of the selected node |
|
The total volume of inbound MQTT messages in bytes |
|
The total volume of outbound MQTT messages in bytes |
|
The amount of inbound MQTT messages per second |
|
The amount of outbound MQTT messages per second |
Clients
With millions of connected clients, keeping track of specific clients can become a challenge. The HiveMQ Control Center provides tools to list, view, and manage all the MQTT clients known to HiveMQ. Information about subscriptions, connection status, TLS, and more offer detailed insights into every client.
Clients Overview
HiveMQ uses cluster-wide snapshots to display all available MQTT sessions. To view information for the MQTT sessions that are currently available, you must create a fresh snapshot. The HiveMQ snapshot gives you a consolidated view from all of the nodes in your cluster at a particular point in time. This unified snapshot provides an efficient way to sort, filter, and navigate through all of the available MQTT sessions.
To create a snapshot, select Refresh Snapshot. Based on the number of MQTT sessions on your cluster, the refresh process can take a few moments. When the process finishes, an overview table of the current clients displays.
To change the order in which clients are sorted on the overview, click the column header.
To filter clients by client ID, username, or IP address, select the desired option from the drop-down menus in the Clean Session and Connected columns.
The sorting options and filters that you apply to the Clients overview table are stored until you log out.
If you leave the Clients overview and return later, the filters and sorting options that you applied to the overview table remain active.
| Snapshots do not update automatically. To manually refresh the data that is shown in the Clients overview, select Refresh Snapshot. |
| Column | Description |
|---|---|
Client ID |
The unique identifier of the client. |
Connected |
Shows whether a client is currently connected.
|
Queue Size |
The current and maximum number of messages in the message queue of the client.
|
Username |
The username of the client. When blank, no username was set. |
IP Address |
The IP address of the client. |
To open the Client Detail page of a client and access additional client actions, select the identifier of the client on the overview.
Client Details
This page displays when you select a client identifier in the Clients overview.
The client identifier and the connection status of the client for which details are shown appears at the top of the page.
The Prev and Next options on your client detail pages allow you to easily navigate through the clients on your Clients overview.
Prev displays information for the client one row before the currently selected entry in the overview table.
Next displays information for the client one row after the currently selected entry in the overview table.
If you change the sorting order or filters of your Clients overview table, the changes that you make are immediately reflected in the Prev and Next information.
To view more information about each items that is shown on the details page, click the question mark next to the desired column.
For example, more information on sessions:
Session
When a client connects to an MQTT broker, the client subscribes to each topic for which it wants to receive messages from the broker. If the client connects to the MQTT broker with a non-persistent session, the broker does not save any subscription information when the client disconnects. In a non-persistent session, each time the client reconnects to the MQTT broker, the client must resubscribe to each topic of interest.
In a persistent session, the MQTT broker saves all relevant client information. The session is identified by the client ID that the client provides during connection establishment.
For more information, see MQTT Essentials: Persistent Session and Queuing Messages.
The following information is stored in the session:
| Item | Description |
|---|---|
Client ID |
Identifies the MQTT client within an MQTT broker or MQTT broker cluster. |
Clean Session |
If set to true, sessions are stateless. Information such as unfinished message flows and subscriptions is lost on disconnect. |
Connected/Disconnected Since |
Date and time when the client last established or lost connection with the broker. |
Offline Session TTL |
Shows the Time to live (TTL) limit that is set for the client. The TTL timer starts when the client disconnects. If the client does not reconnect within the predefined period, the session is invalidated and the broker deletes all client information (including subscriptions and queued messages). The TTL does not apply while the client is connected |
Offline Message Queue Size |
When a client with a persistent session is offline (session-expiry-interval > 0), this entry shows the current number of QoS 1 and 2 messages that are queued for the client. |
Connection
A central principle of MQTT is the decoupling of communication partners. Decoupling means that the clients that send and
receive the MQTT messages only connect to the MQTT broker. One MQTTclient never connects directly to another MQTT client.
To establish an MQTT connection, the client sends a CONNECT message to the HiveMQ broker and the HiveMQ broker
replies to the client with a CONNACK message.
The protocol the HiveMQ broker uses for the connection is TCP.
For more information, see HiveMQ Essentials: Client, Broker, and Connection Establishment and MQTT Essentials: Keep Alive and Client Take-Over.
The Client Detail page provides the following connection information for the client that is currently selected on the overview:
| Item | Description |
|---|---|
Client IP |
The network IP address of the client. The address can be IPv4 or IPv6. |
Username |
Username of the selected client. |
Password |
Password of the selected client. |
MQTT Version |
The version number of the MQTT protocol that is used for the connection. |
Keep-Alive |
Interval during which the client is required to send control packets. If the client fails to send a packet within the defined interval, the broker disconnects the client. |
Listener |
The type of listener and the address the client uses to connect to the broker. |
Connected Node |
The unique identifier of the cluster node to which the client is connected. |
TLS
Transport Layer Security (TLS) is a cryptographic protocol that allows secure and encrypted communication between a client application and a server
at the transport layer. 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 an X.509 certificate to authenticate the client.
Authentication with an X.509 certificate is an alternative to the username/password authentication.
The TLS column of the Client Details page shows the most important aspects of the TLS that the selected client uses.
For more information, see Transport Layer Security (TLS).
| Item | Description |
|---|---|
TLS Version |
The version of the TLS protocol that is used. |
Cipher Suite |
The cipher suite that is used for the encryption of the connection. The cipher suite is a combination of authentication, encryption, message authentication code (MAC), and key exchange algorithms. |
X.509 client certificate |
The X.509 certificate of the client. |
Information from the X.509 certificate of the client is grouped into two sections:
General
| Item | Description |
|---|---|
Common Name |
Common name of the owner of the certificate |
Organization |
Organization of the subject |
Organizational Unit |
Organizational unit of the subject |
Serial |
Serial number of the certificate |
x.509 Version |
Version of the certificate |
Valid From |
Timestamp from which the certificate is valid |
Valid Until |
Timestamp until which the certificate is valid |
Country |
Country of the subject |
State |
State of the subject |
Last Will
Last will is a feature that is used when a client disconnects ungracefully. The last will of a client publishes a last-will message to a specific topic with a specified Quality of Service upon an ungraceful disconnection.
For more information, see MQTT Essentials: Last Will and Testament.
When a client connects to the broker, the client can specify a last will message. The will message is a normal MQTT message with a topic, QoS, retained flag, and payload.
| Item | Description |
|---|---|
Will Topic |
The topic on which the last will payload is published. |
Will QoS |
The Quality of Service level with which the last will message is published. |
Will Retained |
Indicates whether the last will message is a retained message. |
Will Payload |
The payload that is published when the last will is triggered. |
To view or download the payload of the last-will message, click show payload next to the Will Payload size of the desired payload. This opens a new window:
In the LWT Payload window, you can select how the payload is presented. It is possible to show the payload as a UTF-8 string, hexadecimal value, or binary value. The Content area of the window shows a preview of the payload in the selected format. If desired, you can copy the payload content to your clipboard or download the content as a .dat file.
Restrictions
To ensure a trouble-free communication process, some restrictions have to be observed.
| Item | Description |
|---|---|
Maximum Bytes per Second Inbound |
The maximum bytes per second this client can receive from the broker. |
Maximum Bytes per Second Outbound |
The maximum bytes per second this client can send to the broker. |
Maximum Message Size |
The maximum payload size in bytes that MQTT PUBLISH messages sent by this client. |
Maximum Message Queue Size |
The maximum number of messages that the client can store in its message queue on the broker. |
Drop Strategy for Queued Messages |
Defines how the broker manages messages when the message queue limit is reached.
|
Proxy Protocol
HiveMQ supports the PROXY protocol for all listener types. The PROXY protocol is a TCP-based protocol that provides a convenient way to transport client details such as the IP address and port over multiple proxies. If you run your HiveMQ brokers behind a load balancer that proxies the TCP connection, PROXY protocol is helpful. Otherwise, useful client information such as the IP address, port, and SSL information is lost since the broker only recognizes the TCP connection of the load balancer (not of the original client).
For more information, see PROXY protocol.
| Item | Description |
|---|---|
Source IP/Port |
The source (origin) IP address and port of the proxy. |
Destination IP/Port |
The destination IP address and port of the proxy. |
Additional TLVs |
The type-length values (TLVs) are key-value pairs that provide optional information such as the SSL X.509 client certificate common names or the TLS version the client used to connect to the proxy. |
Subscriptions
The Client Detail page provides information on the subscriptions and shared subscriptions of each client. On the detail page, you can add and remove subscription and shared subscription topics for the selected client.
The Subscriptions area shows all topics to which the selected client subscribes. Each subscription consists of a topic and the Quality of Service (QoS) level for the subscription. There are three QoS levels:
-
0 - At Most Once: Messages are delivered one time or not at all.
-
1 - At Least Once: Messages are delivered at least once and can be delivered multiple times.
-
2 - Exactly Once: Message delivery is guaranteed with no duplicates.
Shared Subscriptions
The ability to use shared subscriptions with all versions of MQTT is a unique feature of HiveMQ. Shared subscriptions allow MQTT clients to share a subscription to the same topic on the broker.
In a "standard" MQTT subscription, each client receives a copy of the message. Shared subscriptions distribute the message load of the subscribed topic equally among each client in the shared group.
HiveMQ delivers the message to only one subscriber in the group that share the subscription.
This mechanism is sometimes called client load balancing.
The shared subscription area shows the topic, shared group name, and QoS level of all shared subscriptions of the selected client.
-
To view the shared subscriptions details of a specific shared subscription, select the subscription topic.
-
To unsubscribe the client from a shared subscription, select the x symbol next to the subscription you wish to end.
-
To add new shared subscriptions to the client, enter the topic, shared group, and quality of service level for the desired subscription.
Session Attributes
Session attributes are a convenient way to add additional key-value data to the session of an MQTT client. The Session Attributes area of the Client Detail lists all available session attributes for the selected client. Use the concise control center view to easily review and verify the session attributes of your clients.
Each session attribute contains a key and a value. The Sessions Attributes area can display a maximum of 100 entries.
| Item | Description |
|---|---|
key |
The key of the session attribute. To view, download, or copy the information stored in the key, select show key. In the information dialog that opens you can select how the information is shown. |
value |
The value of the session attribute. If the value contains only ASCII characters, an ASCII string displays. If the value contains non-ASCII characters, the size of the value in bytes is shown. To view, download, or copy the information stored in the value, select show value. In the information dialog that opens you can select how the information is shown. |
When you select show key or show value for the key or value of a session attribute, you can select how the data is presented. It is possible to show the data as a UTF-8 string, hexadecimal value, or binary value. The Content area of the information dialog shows a preview of the payload in the selected format. If desired, you can copy the session attribute content to your clipboard or download the content as a .dat file.
Event History
HiveMQ deployments are built to handle millions of clients and massive amounts of data. The Event History area gives you access to all previous events associated with the selected client. The historical view of client events makes it easier to monitor and analyze the behavior of a specific client over time and diagnose problems.
| You can use the event history integration in the HiveMQ enterprise extension SDK to trigger actions that are based on the event history of a client or to export historical data for further analysis in a third party tool. |
| Item | Description |
|---|---|
Timestamp |
The UTC timestamp when the event occurred. |
Event |
Shows the type of event that was captured. The following options are available:
|
Details |
Shows additional information for the event:
|
Events can be sorted and filtered by the time interval, event type, and event details.
To change the order in which events are sorted, click the column header.
To filter events by type or details, enter your filter criteria in the Event and Details columns. To filter for events in a specific timeframe, use the calendar option in the Timestamp column to define your desired time period.
| The Event History area can display a maximum of 100,000 entries. If the number of events exceeds the display limit, reduce the selected time interval. |
Shared Subscriptions
Shared subscriptions are an effective way to distribute messages across different MQTT subscribers with standard MQTT mechanisms. This type of subscription lets you add MQTT-client load balancing without any proprietary additions to your MQTT clients. For more information, see Shared Subscriptions.
The HiveMQ Control Center gives you all the information you need to efficiently manage all your shared subscriptions.
| Shared subscriptions can dramatically alleviate cluster traffic and latency for high-scalability deployments. The load balancing abilities of shared-subscriptions are especially useful for backend systems or high-traffic topics that can quickly overwhelm a single MQTT client. Shared subscriptions are the recommended way to connect horizontally scaling backend systems with HiveMQ. For more information see, MQTT Client Load Balancing with Shared Subscriptions. |
Shared Subscription Overview
The shared-subscription overview provides basic information for each shared subscription on your HiveMQ cluster.
HiveMQ uses cluster-wide snapshots to display all available shared subscriptions. To view information for the shared subscriptions that are currently available, you must create a fresh snapshot. The HiveMQ snapshot gives you a consolidated view from all of the nodes in your cluster at a particular point in time. This unified snapshot provides an efficient way to sort, filter, and navigate through all of the available MQTT sessions.
To create a snapshot, select Refresh Snapshot. Based on the number of shared subscriptions on your cluster, the refresh process can take a few moments. When the process finishes, an overview table of your current shared subscriptions displays.
To change the order in which the data is sorted on the overview, click the column header. To filter for a specific shared subscription, enter the desired topic in the Topic field.
The sorting options and filters that you apply to the overview table are stored until you log out. If you leave the overview and return later, the filters and sorting options that you applied remain active.
| Snapshots do not update automatically. To manually refresh the data that is shown in the Shared Subscriptions overview, select Refresh Snapshot. |
| Column | Description |
|---|---|
Topic |
The complete topic of the shared subscription including the shared name. |
Queue Size |
The current number of messages that are queued for the shared subscription. |
Shared Subscriptions Details
This page displays when you select a Topic in the Shared Subscriptions overview.
The shared subscription topic for which details are shown appears at the top of the page.
To view more information about each items that is shown on the details page, click the question mark next to the desired column.
For example, more information about shared subscription client details:
The Prev and Next options on your detail pages allow you to easily navigate through entries and respect the filters and sorting options that you apply to the overview table.
Prev displays information for the subscription one row before the currently selected entry in the overview table.
Next displays information for the subscription one row after the currently selected entry in the overview table.
When you change the sorting order or filters of your Shared Subscription overview, your changes are immediately reflected in the Prev and Next information of your detailed view.
| Column | Description | ||
|---|---|---|---|
General |
Provides basic information on the selected shared subscription:
|
||
Queue |
The number of messages that are currently in the queue of the shared subscription. |
||
Restrictions |
Shows the limits that apply to the shared subscription:
|
||
Clients |
Lists information for each client that shares the subscription. The Clients area can display a maximum of 100 entries:
|
Retained Messages
Keeping track of the millions of retained messages that your HiveMQ cluster processes can be a challenge. The HiveMQ Control Center provides the tools you need to manage all the retained messages in your HiveMQ cluster.
Retained Messages Overview
HiveMQ uses cluster-wide snapshots to display all available retained messages. To view information for the retained messages that are currently available, you must create a fresh snapshot. The HiveMQ snapshot gives you a consolidated view from all of the nodes in your cluster at a particular point in time. This unified snapshot provides an efficient way to sort, filter, and navigate through all retained messages that are available on your cluster.
To create a snapshot, select Refresh Snapshot. Based on the number of retained messages that are available in your cluster, the refresh process can take a few moments. When the process finishes, an overview table of the retained messages displays.
To change the order in which the data is sorted on the overview, click the column header. To filter the messages that are displayed by topic, enter the desired topic in the input field of the Topic column.
The sorting options and filters that you apply to the retained messages overview table are stored until you log out. If you leave the retained messages overview and return later, the filters and sorting options that you applied to the overview table remain active.
| Snapshots do not update automatically. To manually refresh the data that is shown in the retained messages overview, select Refresh Snapshot. |
| Column | Description |
|---|---|
Topic |
The topic of the retained message. |
Payload Size |
The size of the payload of the retained message. |
Creation Date |
The date and time when the retained message was created. |
Retained Message Details
This page displays when you click the topic of a retained message in the Retained Messages overview. The topic of the retained message for which details are shown appears at the top of the page.
Prev and Next options on each detail page allow you to easily navigate through the retained messages that are listed on your retained messages overview table.
Prev displays detailed information for the message one row before the currently selected entry in the overview table.
Next displays detailed information for the message one row after the currently selected entry in the overview table.
If you change the sorting order or filters on the Retained Messages overview table, the changes are immediately reflected in the Prev and Next information.
The Retained Message Detail page provides message information and user property information for the retained message that is currently selected.
To view more information about each items that is shown on the details page, click the question mark next to the desired column.
General
Shows basic information about the retained message that is currently selected.
| Item | Description |
|---|---|
Topic |
The topic of the retained message. |
QoS |
The Quality of Service (QoS) level of the retained message. There are three QoS levels:
|
Payload Size |
The amount of data that the payload of retained message contains in bytes. NOTE: The payload size does not reflect other data such as user properties or correlation data that the retained message can transmit. |
Expiry
Shows when the retained message was created and how long the message is valid.
| Item | Description |
|---|---|
Creation Date |
The date and time the retained message was published. |
Message Expiry |
The message-expiry interval that is set for the retained message. The expiry timer starts at the moment that the retained message is published. |
Remaining Time |
The time in seconds until the message expires and is deleted from HiveMQ. The time is calculated in seconds at the moment the detail page loads. To recalculate the time until message expiration, select Refresh Snapshot. |
Message Metadata
Shows information that is used in a request/response pattern for the retained message. This information is only available for MQTT 5.
| Item | Description |
|---|---|
Response Topic (optional) |
The identifier used to implement a request/response pattern between clients. |
Correlation Data (optional) |
The data used to match response requests to the correct response messages. |
Payload Metadata
Shows information about the type and format of the data in the payload of the retained message. This information is only available in MQTT 5.
| Item | Description |
|---|---|
Content Type (optional) |
The UTF-8 encoded strings that describe the content of the retained message payload. For example, text/plain. |
Payload Format Indicator (optional) |
A value that shows whether the message payload contains UTF-8 encoded character data or unspecified bytes. |
| To view more information on the payload of the retained message, click Show Payload. |
User Properties
The User Properties area of the details page shows the name and value of all user properties for the retained message.
User properties are defined as part of the sender implementation. The meaning of the user properties is not defined by MQTT.
User properties are only available for MQTT 5.
| The User Properties area shows a maximum of 500 properties. |
Licenses
Your HiveMQ instance can contain more than one license. The license page provides an overview of all HiveMQ license information that is currently avaialble.
Active License
This area shows information about the HiveMQ license that is currenly in use. Only one license can be active at a time. Information for this license is also shown in the Active License Information area of the control center dashboard.
Evaluation license
If no license is installed in the licence folder of your HiveMQ installation, HiveMQ automatically uses a free evaluation license. Evaluation licenses are limited to 25 concurrent connections:
| Only licenses that are installed on the currently selected node are shown. |
The license table provides the following useful information on the current license:
| Item | Description |
|---|---|
Maximum Connections |
The maximum number of concurrent client connections the license allows. |
Cluster License |
Indicates whether the license enables the use of HiveMQ clusters. |
Filename |
The filename of the current license. |
Start Date |
The date on which the license is activated. |
License Expiration Date |
Expiration date of the license. |
Support Expiration Date |
The expiration date of your support subscription. |
License Owner |
The owner of this license. |
Contact |
Contact information for the owner of the license. |
Email address of the owner of the license. |
| A warning notification displays at the top of the Active License area when your license is about to expire. The default setting is 30 days before the license expiration date. This time period can be adjusted individually for each license. |
If your license expires, an evaluation license is used automatically. Information on the expired license appears in the Inactive licenses area.
