Monitoring

System monitoring is an essential part of every production-software deployment. Monitoring your MQTT brokers is vital, especially in clustered environments. HiveMQ is designed to accommodate different kinds of monitoring easily. When you run HiveMQ in critical infrastructure, we strongly recommend use of an appropriate monitoring application.

The highly-performant metrics subsystem of HiveMQ lets you monitor relevant metrics with no reduction in system performance (even in low-latency high-throughput environments).

Some metrics are not available in the HiveMQ Community Edition.

JMX

HiveMQ exposes a large number of metrics with Java Management Extensions (JMX) and enables monitoring with JMX monitoring tools such as JConsole.

Configuration

If you run HiveMQ behind NAT (Network Address Translation), you need to set some additional options:

JAVA_OPTS="$JAVA_OPTS -Djava.rmi.server.hostname=<PUBLIC_IP>"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.rmi.port=9010"

This configuration allows you to connect with JConsole using PUBLIC_IP:9010.

MBeans

By default, the following MBeans (managed Java objects) are available for monitoring:

MBean Name Description

metrics

The HiveMQ metrics and statistics. A list of all available metrics is available here.

java.nio

Statistics and metrics about used native memory.

java.lang

All information about the Java Virtual Machine.

actions

Actions that can be started via JMX.

Maintenance

Some maintenance actions are resource intensive. In general, we recommend that you do not combine system maintence tasks with cluster topology changes. If you have recently added or removed HiveMQ instances, verify that the topology change is complete and that the cluster size is as expected before you start maintenance.

Maintenance action Description

subscription cleanup

Removes outdated subscriptions that were added during network splits.

Prometheus

Prometheus is a popular open-source solution for event monitoring and alerting. Prometheus provides a simple and powerful dimensional data model, flexible query language, efficient time-series database, and real-time metrics.

The HiveMQ Prometheus Monitoring Extension allows HiveMQ to expose metrics to a Prometheus application.

Install the HiveMQ Prometheus Monitoring Extension

  1. Download the HiveMQ Prometheus Monitoring Extension from the HiveMQ Marketplace (free of charge).

  2. Unpack the hivemq-prometheus-extension-<version>.zip file.

  3. Move the entire hivemq-prometheus-extension folder to the extensions folder of your HiveMQ installation.

  4. Adjust the prometheusConfiguration.properties file that is located in the hivemq-prometheus-extension folder to meet your individual needs. For more information, see Configuration Options.

  5. Start HiveMQ.

Configuration Options

The HiveMQ Prometheus Monitoring Extension is preconfigured with standard property settings. You can adapt properties of the prometheusConfiguration.properties file in the hivemq-prometheus-extension folder to fulfill for your specific use case.

Table 1. Prometheus extension configuration options
Configuration Default Description

port

9399

The port on which the servlet listens.

host

0.0.0.0

The bind-address which the servlet will listen to.

metric_path

/metrics

The path that Prometheus calls for the service. The path must start with a slash. For example, 127.0.0.1:9399/metrics

Example HiveMQ Prometheus Monitoring Extension configuration
# Prometheus Monitoring Extension Configuration
# -------------------------------------------------------------------------

# The ip where the servlet will be hosted
ip=0.0.0.0

# The port where the servlet will work on
port=9399

# The path for the servlet which gets called by prometheus
# <ip>:<port> and <metric_path>
# For example 127.0.0.1:9399/metrics
metric_path=/metrics
Be sure to verify that your Prometheus server can reach the IP address of the network interface.

Test Extension Configuration

To test the configuration of your HiveMQ Prometheus Monitoring Extension, use your browser to navigate to the <ip>:<port><metric_path> that is configured in your prometheusConfiguration.properties file. For example, if you use the default configuration values, navigate to http://localhost:9399/metrics.

Information similar to the following verifies that the extension is available:

# HELP com_hivemq_messages_incoming_publish_rate_total Generated from Dropwizard metric import
(metric=com.hivemq.messages.incoming.publish.rate, type=com.codahale.metrics.Meter)
# TYPE com_hivemq_messages_incoming_publish_rate_total counter
com_hivemq_messages_incoming_publish_rate_total 0.0
# HELP com_hivemq_messages_incoming_pubrec_rate_total Generated from Dropwizard metric import (metric=com.hivemq.messages.incoming.pubrec.rate, type=com.codahale.metrics.Meter)
# TYPE com_hivemq_messages_incoming_pubrec_rate_total counter
com_hivemq_messages_incoming_pubrec_rate_total 0.0
...

Install Prometheus

  1. Download Prometheus and install the Prometheus application on a machine of your choice.
    For best results, we recommend that you do not run Prometheus on the same machine as HiveMQ.
    A step by step Prometheus getting started guide and detailed configuration information are available in the Prometheus documentation.

  2. To enable Prometheus to gather metrics from HiveMQ, add a scrape configuration to your Prometheus configuration. Scrape from the <ip>:<port><metricPath> address that you entered in the prometheusConfiguration.properties file of your HiveMQ Prometheus Monitoring Extension.

  3. Open the web address of your Prometheus application and verify that HiveMQ metrics are visible.

Example minimal Prometheus configuration based on the HiveMQ Prometheus Extension configuration
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'hivemq'
scrape_interval: 5s
metrics_path: '/metrics'
static_configs:
#using port 9399 as configured in the HiveMQ Prometheus Extension
- targets: ['<node1-ip>:9399', '<node2-ip>:9399']
This example is for a 2 node cluster. If you want more nodes, add the additional nodes to the targets.

Display HiveMQ Metrics in Prometheus

Prometheus provides built-in functionality to display metrics on-the-fly that can be helpful when you want an in-depth look into specific metrics that you do not monitor constantly. Navigate to http://:9090/. When Prometheus and the HiveMQ Prometheus Monitoring Extension are configured correctly, you can access your HiveMQ metrics in the Expression field.

HiveMQ metrics in Prometheus

Frequently, Prometheus is used as a data source for monitoring dashboards such as Grafana. For a complete tutorial on how to set up a Grafana dashboard and use Prometheus as a data source to monitor HiveMQ, see HiveMQ - Monitoring with Prometheus and Grafana.

InfluxDB

InfluxDB is a widely-used open-source time-series database that is written in Go and optimized for fast, high-availability storage and retrieval of time-series data. InfluxDB is a popular choice for gathering and visualizing application metrics, Internet of Things sensor data, and real-time analytics to gain deeper insights.

The HiveMQ InfluxDB Monitoring Extension allows HiveMQ to connect to an instance of InfluxDB for time-series monitoring.

Install the HiveMQ InfluxDB Monitoring Extension

  1. Download the HiveMQ InfluxDB Monitoring Extension from the HiveMQ Marketplace (free of charge).

  2. Unpack the hivemq-influxdb-extension-<version>.zip file.

  3. Move the entire hivemq-influxdb-extension folder to the extensions folder of your HiveMQ installation.

  4. Modify the influxdb.properties file that is located in the hivemq-influxdb-extension folder to meet your individual needs. The host and port properties are mandatory. For more information, see Configuration Options.

Configuration Options

The HiveMQ InfluxDB Monitoring Extension is preconfigured with standard property settings. You can adapt properties of the influxdb.properties file that is located in the hivemq-influxdb-extension folder to match your specific use case. The host and port properties are mandatory.

The InfluxDB extension cannot start if the influxdb.properties file is missing or if the required host and port properties are not set.
Table 2. InfluxDB extension configuration options
Configuration Default Environment Variable Description

mode

http

HIVEMQ_INFLUX_DB_PLUGIN_MODE

The mode that is configured for the InfluxDB sender. The following modes are possible: : http, tcp, udp.

host

localhost

HIVEMQ_INFLUX_DB_PLUGIN_HOST

The host name of the InfluxDB instance. The host prperty is required.

port

8086

HIVEMQ_INFLUX_DB_PLUGIN_PORT

The port number on which the InfluxDB instance listens. The port property is required.

protocol

http

HIVEMQ_INFLUX_DB_PLUGIN_PROTOCOL

The protocol the InfluxDB sender uses in HTTP mode.

auth

HIVEMQ_INFLUX_DB_PLUGIN_AUTH

The authorization string that is used to connect to InfluxDB. The format of the string is username:password.

prefix

HIVEMQ_INFLUX_DB_PLUGIN_PREFIX

The measurement prefix.

database

hivemq

HIVEMQ_INFLUX_DB_PLUGIN_DATABASE

The database name.

reportingInterval

1

HIVEMQ_INFLUX_DB_PLUGIN_REPORTING_INTERVAL

The reporting interval in seconds.

connectTimeout

5000

HIVEMQ_INFLUX_DB_PLUGIN_CONNECTION_TIMEOUT

The connect and read timeout in seconds.

tags

HIVEMQ_INFLUX_DB_PLUGIN_TAGS

The tags for each metric. Listed as a semicolon ( ; ) separated list.

Example HiveMQ InfluxDB Monitoring Extension configuration
mode:http
host:localhost
port:8086
protocol:http
auth:

prefix:
database:hivemq

reportingInterval:1
connectTimeout:5000

tags:host=hivemq1
To ensure that you can easily match metrics to the right node in your HiveMQ cluster, define a unique host tag for each HiveMQ node. For example, in a two-node cluster, assign one node tag:host=hivemq1 and the other node tag:host=hivemq2.

Quick Start for InfluxDB on Docker

If you do not have an InfluxDB instance set up, use the following procedure to start a not configured InfluxDB instance with Docker.

  1. Download and install Docker for your platform.

  2. Start an InfluxDB docker container with the command: docker run -p 8086:8086 -v $PWD:/var/lib/influxdb influxdb.
    A local instance of InfluxDB starts with the port for the database set to 8086.
    For more information about using InfluxDB with Docker, see the official Docker repository for InfluxDB.

  3. Create a database that matches the name that is set in the database property in influxdb.properties file.
    To use the default database value enter the command: curl -G http://localhost:8086/query –data-urlencode “q=CREATE DATABASE hivemq”.

Usage

After you install the HiveMQ InfluxDB Monitoring Extension and set up an InfluxDB instance, start HiveMQ. If a configuration file exists and contains the required properties, the extension has successfully started.

For a complete tutorial on how to set up a Grafana dashboard and use InfluxDB as a data source to monitor HiveMQ, see HiveMQ - Monitoring with InfluxDB and Grafana.

Available Metrics

HiveMQ exposes five different types of metrics:

Table 3. Metric Types
Metric Type Description

Gauge

A gauge returns a simple value at the point of time the metric was requested.

Counter

A counter is a simple incrementing and decrementing number.

Histogram

A histogram measures the distribution of values in a stream of data. They allow to measure min, mean, max, standard deviation of values and quantiles.

Meter

A meter measures the rate at which a set of events occur. Meters measure mean, 1-, 5-, and 15-minute moving averages of events.

Timer

A timer is basically a histogram of the duration of a type of event and a meter of the rate of its occurrence. It captures rate and duration information.

Standard HiveMQ Metrics

The following HiveMQ metrics are available for all single node and clustered HiveMQ server instances:

Table 4. Standard HiveMQ Metrics
Metric Type Description

com.hivemq.cache.payload-persistence.averageLoadPenalty

Gauge

Cache statistic capturing the average load penalty of the payload persistence cache

com.hivemq.cache.payload-persistence.evictionCount

Gauge

Cache statistic capturing the eviction count of the payload persistence cache

com.hivemq.cache.payload-persistence.hitCount

Gauge

Cache statistic capturing the hit count of the payload persistence cache

com.hivemq.cache.payload-persistence.hitRate

Gauge

Cache statistic capturing the hit rate of the payload persistence cache

com.hivemq.cache.payload-persistence.loadCount

Gauge

Cache statistic capturing the load count of the payload persistence cache

com.hivemq.cache.payload-persistence.loadExceptionCount

Gauge

Cache statistic capturing the load exception count of the payload persistence cache

com.hivemq.cache.payload-persistence.loadExceptionRate

Gauge

Cache statistic capturing the load exception rate of the payload persistence cache

com.hivemq.cache.payload-persistence.loadSuccessCount

Gauge

Cache statistic capturing the load success count of the payload persistence cache

com.hivemq.cache.payload-persistence.missCount

Gauge

Cache statistic capturing the miss count of the payload persistence cache

com.hivemq.cache.payload-persistence.missRate

Gauge

Cache statistic capturing the miss rate of the payload persistence cache

com.hivemq.cache.payload-persistence.requestCount

Gauge

Cache statistic capturing the request count of the payload persistence cache

com.hivemq.cache.payload-persistence.totalLoadTime

Gauge

Cache statistic capturing the total load time of the payload persistence cache

com.hivemq.cache.shared-subscription.averageLoadPenalty

Gauge

Cache statistic capturing the average load penalty of the shared subscription cache

com.hivemq.cache.shared-subscription.evictionCount

Gauge

Cache statistic capturing the eviction count of the shared subscription cache

com.hivemq.cache.shared-subscription.hitCount

Gauge

Cache statistic capturing the hit count of the shared subscription cache

com.hivemq.cache.shared-subscription.hitRate

Gauge

Cache statistic capturing the hit rate of the shared subscription cache

com.hivemq.cache.shared-subscription.loadCount

Gauge

Cache statistic capturing the load count of the shared subscription cache

com.hivemq.cache.shared-subscription.loadExceptionCount

Gauge

Cache statistic capturing the load exception count of the shared subscription cache

com.hivemq.cache.shared-subscription.loadExceptionRate

Gauge

Cache statistic capturing the load exception rate of the shared subscription cache

com.hivemq.cache.shared-subscription.loadSuccessCount

Gauge

Cache statistic capturing the load success count of the shared subscription cache

com.hivemq.cache.shared-subscription.missCount

Gauge

Cache statistic capturing the miss count of the shared subscription cache

com.hivemq.cache.shared-subscription.missRate

Gauge

Cache statistic capturing the miss rate of the shared subscription cache

com.hivemq.cache.shared-subscription.requestCount

Gauge

Cache statistic capturing the request count of the shared subscription cache

com.hivemq.cache.shared-subscription.totalLoadTime

Gauge

Cache statistic capturing the total load time of the shared subscription cache

com.hivemq.client-events.stored.total

Counter

The total number of client events stored including all replicas.

com.hivemq.cluster.name-request.retry.count

Counter

Counts the amount of retry until a name for a node via it‘s address is resolved

com.hivemq.cluster.topology-change.time

Timer

Measures the time spent waiting for cluster topology changes

com.hivemq.exceptions.total

Meter

Measures the rate of inconsequential exceptions thrown during the socket life cycle

com.hivemq.keep-alive.disconnect.count

Counter

Counts every closed connection that was closed because the client missed sending PINGREQ message during the keep-alive interval

com.hivemq.logging.all

Meter

Measures the rate of logging statements of all levels

com.hivemq.logging.debug

Meter

Measures the rate of logging statements in DEBUG level

com.hivemq.logging.error

Meter

Measures the rate of logging statements in ERROR level

com.hivemq.logging.info

Meter

Measures the rate of logging statements in INFO level

com.hivemq.logging.trace

Meter

Measures the rate of logging statements in TRACE level

com.hivemq.logging.warn

Meter

Measures the rate of logging statements in WARN level

com.hivemq.messages.dropped.count

Counter

Counts every dropped message.

com.hivemq.messages.dropped.rate

Meter

Measures the current rate of dropped messages.

com.hivemq.messages.dropped.queue-full.count

Counter

Counts PUBLISH messages that have been dropped, because the message queue for a disconnected persistent session client was full.

com.hivemq.messages.dropped.shared-queue-full.count

Counter

Counts PUBLISH messages that are dropped because the message queue for a shared subscription is full.

com.hivemq.messages.dropped.consumer-queue-full.count

Counter

Counts PUBLISH messages that have been dropped, because the message queue for a consumer topic was full.

com.hivemq.messages.dropped.publish-inbound-intercepted.count

Counter

Counts PUBLISH messages that have been dropped, because a Publish Inbound Interceptor prevented onward delivery.

com.hivemq.messages.dropped.mqtt-packet-too-large.count

Counter

Counts MQTT messages (except PUBLISH) that have been dropped, because the message size was too large for the client.

com.hivemq.messages.dropped.not-writable.count

Counter

Counts PUBLISH messages that have been dropped, because the socket for the client was not writable (only QoS 0).

com.hivemq.messages.dropped.qos-0-memory-exceeded.count

Counter

Counts PUBLISH messages that have been dropped, because the global memory limit for QoS 0 messages has been exceeded.

com.hivemq.messages.dropped.internal-error.count

Counter

Counts PUBLISH messages that have been dropped, because of an internal error.

com.hivemq.messages.dropped.count

Counter

Counts every dropped message

com.hivemq.messages.dropped.rate

Meter

Measures the current rate of dropped messages

com.hivemq.messages.dropped.queue-full.count

Counter

Counts PUBLISH messages that have been dropped, because the message queue for a disconnected persistent session client was full

com.hivemq.messages.dropped.message-too-large.count

Counter

Counts PUBLISH messages that have been dropped, because the message size was too large for the client

com.hivemq.messages.dropped.publish-inbound-intercepted.count

Counter

Counts PUBLISH messages that have been dropped, because a Publish Inbound Interceptor prevented onward delivery

com.hivemq.messages.dropped.mqtt-packet-too-large.count

Counter

Counts MQTT messages (except PUBLISH) that have been dropped, because the message size was too large for the client

com.hivemq.messages.dropped.not-writable.count

Counter

Counts PUBLISH messages that have been dropped, because the socket for the client was not writable (only QoS 0)

com.hivemq.messages.dropped.qos-0-memory-exceeded.count

Counter

Counts PUBLISH messages that have been dropped, because the global memory limit for QoS 0 messages has been exceeded

com.hivemq.messages.dropped.internal-error.count

Counter

Counts PUBLISH messages that have been dropped, because of an internal error

com.hivemq.messages.dropped.topic.dropped.count

Count

The number of $dropped messages that are dropped due to queue limits

com.hivemq.messages.dropped.topic.message-created.client.count

Counter

The number of $dropped messages that originate from clients

com.hivemq.messages.dropped.topic.message-created.shared.count

Counter

The number of $dropped messages that originate from shared subscriptions

com.hivemq.messages.dropped.topic.message-created.consumer.count

Counter

The number $dropped messages that originate from consumers

com.hivemq.messages.dropped.topic.enqueued.count

Counter

The number of dropped messages that are enqueued for a $dropped topic

com.hivemq.messages.expired.cache-size

Gauge

The current size of the expired messages cache

com.hivemq.messages.expired.cache-full-misses.count

Counter

The number of times an expired message is not added to the expired message cache due to a full cache

com.hivemq.messages.expired.topic.dropped.count

Counter

The number of $expired messages that are dropped due to queue limits

com.hivemq.messages.expired.topic.expired.count

Counter

The number of $expired messages that expire more than once

com.hivemq.messages.expired.topic.enqueued.count

Counter

The number of expired messages that are enqueued for an $expired topic

com.hivemq.messages.incoming.connect.count

Counter

Counts every incoming MQTT CONNECT message

com.hivemq.messages.incoming.connect.mqtt3.count

Counter

Counts every incoming MQTT 3 CONNECT message

com.hivemq.messages.incoming.connect.mqtt5.count

Counter

Counts every incoming MQTT 5 CONNECT message

com.hivemq.messages.incoming.connect.rate

Meter

Measures the current rate of incoming MQTT CONNECT messages

com.hivemq.messages.incoming.pingreq.count

Counter

Counts every incoming MQTT PINGREQ message

com.hivemq.messages.incoming.pingreq.rate

Meter

Measures the current rate of incoming MQTT PINGREQ messages

com.hivemq.messages.incoming.puback.count

Counter

Counts every incoming MQTT PUBACK message

com.hivemq.messages.incoming.puback.rate

Meter

Measures the current rate of incoming MQTT PUBACK messages

com.hivemq.messages.incoming.pubcomp.count

Counter

Counts every incoming MQTT PUBCOMP message

com.hivemq.messages.incoming.pubcomp.rate

Meter

Measures the current rate of incoming MQTT PUBCOMP messages

com.hivemq.messages.incoming.publish.bytes

Histogram

Measures the distribution of incoming MQTT message size (including MQTT packet headers)

com.hivemq.messages.incoming.publish.count

Counter

Counts every incoming MQTT PUBLISH message

com.hivemq.messages.incoming.publish.rate

Meter

Measures the current rate of incoming MQTT PUBLISH messages

com.hivemq.messages.incoming.pubrec.count

Counter

Counts every incoming MQTT PUBREC message

com.hivemq.messages.incoming.pubrec.rate

Meter

Measures the current rate of incoming MQTT PUBREC messages

com.hivemq.messages.incoming.pubrel.count

Counter

Counts every incoming MQTT PUBREL message

com.hivemq.messages.incoming.pubrel.rate

Meter

Measures the current rate of incoming MQTT PUBREL messages

com.hivemq.messages.incoming.subscribe.count

Counter

Counts every incoming MQTT SUBSCRIBE message

com.hivemq.messages.incoming.subscribe.rate

Meter

Measures the current rate of incoming MQTT SUBSCRIBE messages

com.hivemq.messages.incoming.total.bytes

Histogram

Measures the size distribution of incoming MQTT messages (including MQTT packet headers)

com.hivemq.messages.incoming.total.count

Counter

Counts every incoming MQTT message

com.hivemq.messages.incoming.total.rate

Meter

Measures the current rate of incoming MQTT messages

com.hivemq.messages.incoming.unsubscribe.count

Counter

Counts every incoming MQTT UNSUBSCRIBE message

com.hivemq.messages.incoming.unsubscribe.rate

Meter

Measures the current rate of incoming MQTT UNSUBSCRIBE messages

com.hivemq.messages.incoming.disconnect.count

Counter

Counts every incoming MQTT DISCONNECT message

com.hivemq.messages.incoming.disconnect.rate

Meter

Measures the current rate of incoming MQTT DISCONNECT messages

com.hivemq.messages.incoming.auth.count

Counter

Counts every incoming MQTT AUTH message

com.hivemq.messages.incoming.auth.rate

Meter

Measures the current rate of incoming MQTT AUTH messages

com.hivemq.messages.outgoing.connack.count

Counter

Counts every outgoing MQTT CONNACK message

com.hivemq.messages.outgoing.connack.rate

Meter

Measures the current rate of outgoing MQTT CONNACK messages

com.hivemq.messages.outgoing.pingresp.count

Counter

Counts every outgoing MQTT PINGRESP message

com.hivemq.messages.outgoing.pingresp.rate

Meter

Measures the current rate of outgoing MQTT PINGRESP messages

com.hivemq.messages.outgoing.puback.count

Counter

Counts every outgoing MQTT PUBACK message

com.hivemq.messages.outgoing.puback.rate

Meter

Measures the current rate of outgoing MQTT PUBACK messages

com.hivemq.messages.outgoing.pubcomp.count

Counter

Counts every outgoing MQTT PUBCOMP message

com.hivemq.messages.outgoing.pubcomp.rate

Meter

Measures the current rate of outgoing MQTT PUBCOMP messages

com.hivemq.messages.outgoing.publish.bytes

Histogram

Measures the size distribution of outgoing MQTT messages (including MQTT packet headers)

com.hivemq.messages.outgoing.publish.count

Counter

Counts every outgoing MQTT PUBLISH message

com.hivemq.messages.outgoing.publish.rate

Meter

Measures the current rate of outgoing MQTT PUBLISH messages

com.hivemq.messages.outgoing.pubrec.count

Counter

Counts every outgoing MQTT PUBREC message

com.hivemq.messages.outgoing.pubrec.rate

Meter

Measures the current rate of outgoing MQTT PUBREC messages

com.hivemq.messages.outgoing.pubrel.count

Counter

Counts every outgoing MQTT PUBREL message

com.hivemq.messages.outgoing.pubrel.rate

Meter

Measures the current rate of outgoing MQTT PUBREL messages

com.hivemq.messages.outgoing.suback.count

Counter

Counts every outgoing MQTT SUBACK message

com.hivemq.messages.outgoing.suback.rate

Meter

Measures the current rate of outgoing MQTT SUBACK messages

com.hivemq.messages.outgoing.total.bytes

Histogram

Measures the size distribution of outgoing MQTT messages (including MQTT packet headers)

com.hivemq.messages.outgoing.total.count

Counter

Counts every outgoing MQTT message

com.hivemq.messages.outgoing.total.rate

Meter

Measures the current rate of outgoing MQTT messages

com.hivemq.messages.outgoing.unsuback.count

Counter

Counts every outgoing MQTT UNSUBACK message

com.hivemq.messages.outgoing.unsuback.rate

Meter

Measures the current rate of outgoing MQTT UNSUBACK messages

com.hivemq.messages.outgoing.disconnect.count

Counter

Counts every outgoing MQTT DISCONNECT message

com.hivemq.messages.outgoing.disconnect.rate

Meter

Measures the current rate of outgoing MQTT DISCONNECT messages

com.hivemq.messages.outgoing.auth.count

Counter

Counts every outgoing MQTT AUTH message

com.hivemq.messages.outgoing.auth.rate

Meter

Measures the current rate of outgoing MQTT AUTH messages

com.hivemq.messages.queued.count

Gauge

The current number of queued messages

com.hivemq.messages.pending.qos-0.count

Gauge

The current number of pending qos 0 messages

com.hivemq.messages.pending.total.count

Gauge

The current number of pending messages total

com.hivemq.messages.retained.queued.count

Gauge

The current number of queued retained messages

com.hivemq.messages.retained.pending.total.count

Gauge

The current number of pending retained messages total

com.hivemq.messages.publish-resent

Meter

Measures the current rate of resent PUBLISH messages (QoS > 0)

com.hivemq.messages.pubrel-resent

Meter

Measures the current rate of resent PUBREL messages (OoS = 2)

com.hivemq.messages.retained.current

Gauge

The current amount of retained messages

com.hivemq.messages.retained.mean

Histogram

Metrics about the mean payload-size of retained messages in bytes

com.hivemq.messages.retained.rate

Meter

The current rate of newly retained messages

com.hivemq.messages.expired-messages

Counter

Counts every expired message

com.hivemq.messages.client.queued.count

Gauge

The current number of queued messages for client sessions

com.hivemq.messages.client.pending.qos-0.count

Gauge

The current number of pending QoS 0 messages for client sessions

com.hivemq.messages.client.pending.total.count

Gauge

The total number of pending messages for client sessions

com.hivemq.messages.shared.queued.count

Gauge

The current number of queued messages for shared subscriptions

com.hivemq.messages.shared.pending.qos-0.count

Gauge

The current number of pending QoS 0 messages for shared subscriptions

com.hivemq.messages.shared.pending.total.count

Gauge

The total number of pending messages for shared subscriptions

com.hivemq.networking.bytes.read.current

Gauge

The current (last 5 seconds) amount of read bytes

com.hivemq.networking.bytes.read.total

Gauge

The total amount of read bytes

com.hivemq.networking.bytes.write.current

Gauge

The current (last 5 seconds) amount of written bytes

com.hivemq.networking.bytes.write.total

Gauge

Total amount of written bytes

com.hivemq.networking.connections.current

Gauge

The current total number of active MQTT connections

com.hivemq.networking.connections.mean

Histogram

The mean total number of active MQTT connections

com.hivemq.networking.connections-closed.graceful.count

Counter

Counts clients which disconnected after sending a DISCONNECT Message

com.hivemq.networking.connections-closed.ungraceful.count

Counter

Counts clients which disconnected without sending a DISCONNECT Message

com.hivemq.networking.connections-closed.total.count

Counter

Counts all clients which disconnected from HiveMQ (= graceful + ungraceful)

com.hivemq.payload-persistence.cleanup-executor.completed

Meter

Measure the rate of completed tasks submitted to the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.duration

Timer

Captures metrics about the job durations for jobs submitted to the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.running

Counter

Counts tasks that are currently running in the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.scheduled.once

Meter

Measures about the tasks that have been scheduled to run only once in the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.scheduled.overrun

Counter

Counts the periodic tasks which ran longer then their time frame allowed in the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.scheduled.percent-of-period

Histogram

Metrics about how much percent of their allowed time frame periodic tasks used while running the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.scheduled.repetitively

Meter

Measures about the tasks that have been scheduled to run repetitively in the scheduler in charge of the cleanup of the persistence payload

com.hivemq.payload-persistence.cleanup-executor.submitted

Meter

Measures about the tasks that have been submitted to the scheduler in charge of the cleanup of the persistence payload

com.hivemq.persistence-executor.completed

Meter

Measure the rate of completed tasks submitted to the persistence executor

com.hivemq.persistence-executor.duration

Timer

Captures metrics about the job durations for jobs submitted to the persistence executor

com.hivemq.persistence-executor.running

Counter

Counts tasks that are currently running in the persistence executor

com.hivemq.persistence-executor.submitted

Meter

Measures about the tasks that have been submitted to the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.completed

Meter

Measure the rate of completed tasks submitted to the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.duration

Timer

Captures metrics about the job durations for jobs submitted to the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.running

Counter

Counts tasks that are currently running in the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.scheduled.once

Meter

Measures about the tasks that have been scheduled to run once in the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.scheduled.overrun

Counter

Counts the periodic tasks which ran longer then their time frame allowed in the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.scheduled.percent-of-period

Histogram

Metrics about how much percent of their allowed time frame periodic tasks used in the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.scheduled.repetitively

Meter

Measures about the tasks that have been scheduled to run repetitively in the scheduler responsible for persistence

com.hivemq.persistence-scheduled-executor.submitted

Meter

Measures about the tasks that have been submitted to the scheduler responsible for persistence

com.hivemq.persistence.executor.client-session.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the client session persistence

com.hivemq.persistence.executor.client-session.time

Timer

Measures the mean execution time (in nanoseconds) of client session disk I/O tasks

com.hivemq.persistence.executor.client-events.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the client events persistence

com.hivemq.persistence.executor.client-events.time

Timer

Measures the mean execution time (in nanoseconds) of client events tasks

com.hivemq.persistence.executor.noempty-queues

Gauge

Current amount of single writer task queues that are not empty

com.hivemq.persistence.executor.outgoing-message-flow.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the outgoing message flow persistence

com.hivemq.persistence.executor.outgoing-message-flow.time

Timer

Measures the mean execution time (in nanoseconds) of outgoing message flow disk I/O tasks

com.hivemq.persistence.executor.queue-misses

Counter

Current count of loops that all single writer threads have done without executing a task

com.hivemq.persistence.executor.queued-messages.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the queued messages persistence

com.hivemq.persistence.executor.queued-messages.time

Timer

Measures the mean execution time (in nanoseconds) of queued messages disk I/O tasks

com.hivemq.persistence.executor.request-event-bus.tasks

Gauge

Current amount of tasks that are enqueued by the request event bus

com.hivemq.persistence.executor.request-event-bus.time

Timer

Measures the mean execution time (in nanoseconds) of request event bus tasks

com.hivemq.persistence.executor.retained-messages.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the retained message persistence

com.hivemq.persistence.executor.retained-messages.time

Timer

Measures the mean execution time (in nanoseconds) of retained message disk I/O tasks

com.hivemq.persistence.executor.running.threads

Gauge

Current amount of threads that are executing disk I/O tasks

com.hivemq.persistence.executor.subscription.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by the subscription persistence

com.hivemq.persistence.executor.subscription.time

Timer

Measures the mean execution time (in nanoseconds) of subscription disk I/O tasks

com.hivemq.persistence.executor.total.tasks

Gauge

Current amount of disk I/O tasks that are enqueued by all persistence executors

com.hivemq.persistence.payload-entries.count

Gauge

Holds the current amount of payloads stored in the payload persistence

com.hivemq.persistence.removable-entries.count

Gauge

Holds the current amount of payloads stored in the payload persistence, that can be removed by the cleanup

com.hivemq.sessions.overall.current

Gauge

Measures the current count of stored sessions. These sessions include all sessions, including online and offline clients

com.hivemq.sessions.persistent.active

Counter

Measures the current count of active persistent sessions (= Online MQTT clients which are connected with cleanSession=false).

com.hivemq.single-writer-executor.completed

Meter

Measure the rate of completed tasks submitted to the single-writer executor

com.hivemq.single-writer-executor.duration

Timer

Measure the rate of completed tasks submitted to the scheduler responsible for single-writer

com.hivemq.single-writer-executor.running

Counter

Counts tasks that are currently running in the scheduler responsible for single-writer

com.hivemq.single-writer-executor.submitted

Meter

Measures about the tasks that have been submitted to the scheduler responsible for single-writer

com.hivemq.subscriptions.overall.current

Counter

Measures the current count of subscriptions on the broker

com.hivemq.extension.managed-executor.submitted

Meter

Measures the current rate of submitted jobs to the ManagedExtensionExecutor

com.hivemq.extension.managed-executor.running

Counter

Measures the current count of running jobs in the ManagedExtensionExecutor

com.hivemq.extension.managed-executor.completed

Meter

Measures the current rate of completed jobs in the ManagedExtensionExecutor

com.hivemq.extension.managed-executor.duration

Timer

Measures the duration of time spent on submitted jobs to the ManagedExtensionExecutor

com.hivemq.extension.managed-executor.scheduled.once

Meter

Measures the current rate of scheduled jobs in the ManagedExtensionExecutor that run once

com.hivemq.extension.managed-executor.scheduled.repetitively

Meter

Measures the current rate of scheduled jobs in the ManagedExtensionExecutor that run repetitively

com.hivemq.extension.managed-executor.scheduled.overrun

Counter

Measures the current count of jobs in the ManagedExtensionExecutor that are overrun

com.hivemq.extension.managed-executor.scheduled.percent-of-period

Histogram

Measures how many percent of the scheduled period the ManagedExtensionExecutorService jobs lasted

com.hivemq.extension.services.rate-limit-exceeded.count

Counter

Counts the amount of times that the extension service rate limit was exceeded.

com.hivemq.extension.services.publish-service-publishes

Counter

Counts the amount of publish messages sent by the publish service.

com.hivemq.extension.services.publish-service-publishes-to-client

Counter

Counts the amount of publish messages sent by the publish service to a specific client.

com.hivemq.qos-0-memory.used

Gauge

Holds the current amount of bytes QoS 0 messages use in memory

com.hivemq.qos-0-memory.max

Gauge

Holds the maximum amount of bytes QoS 0 messages may use in memory

com.hivemq.qos-0-memory.exceeded.per-client

Gauge

Holds the current amount of clients that exceeded their QoS 0 message memory

com.hivemq.cpu-cores.used

Gauge

Holds the current amount of cpu cores used

com.hivemq.cpu-cores.licensed

Gauge

Holds the maximum amount of cpu cores allowed by license

com.hivemq.publish.without-matching-subscribers

Counter

Counts the amount of publish messages received, without any matching subscribers

com.hivemq.topic-alias.memory.usage

Gauge

Holds the current amount of bytes topic aliases use in memory

com.hivemq.topic-alias.count.total

Gauge

Holds the current amount of topic aliases

com.hivemq.overload-protection.level

Gauge

Holds the current level of overload protection

com.hivemq.overload-protection.credits.per-tick

Gauge

Holds the current amount of credits a client receives per tick

com.hivemq.overload-protection.clients.average-credits

Gauge

Holds the average amount of available credits between all clients

com.hivemq.overload-protection.clients.using-credits

Gauge

Holds the current amount of clients having less than the full amount of credits

com.hivemq.overload-protection.clients.backpressure-active

Gauge

Holds the current amount of clients for which backpressure is applied by overload protection

Table 5. System and Operating System Metrics
Metric Type Description

com.hivemq.system.max-file-descriptor

Gauge

Maximum allowed amount of file descriptors as seen by the JVM

com.hivemq.system.open-file-descriptor

Gauge

Amount of open file descriptors as seen by the JVM

com.hivemq.system.physical-memory.free

Gauge

Current amount of free physical memory in bytes

com.hivemq.system.physical-memory.total

Gauge

Total amount of physical memory (bytes) available

com.hivemq.system.process-cpu.load

Gauge

Current CPU usage for the JVM process (0.0 idle – 1.0 full CPU usage)

com.hivemq.system.process-cpu.time

Gauge

Total amount of CPU time the JVM process has used to this point(in nanoseconds)

com.hivemq.system.swap-space.free

Gauge

Current amount of free swap space in bytes

com.hivemq.system.swap-space.total

Gauge

Total amount of swap space available in bytes

com.hivemq.system.system-cpu.load

Gauge

Current CPU usage for the whole system (0.0 idle – 1.0 full CPU usage)

com.hivemq.system.os.global.uptime

Gauge

OS Uptime in seconds

com.hivemq.system.os.global.memory.total

Gauge

The amount of actual physical memory, in bytes

com.hivemq.system.os.global.memory.available

Gauge

The amount of physical memory currently available, in bytes

com.hivemq.system.os.global.memory.swap.used

Gauge

The current memory committed to the paging/swap file(s), in bytes

com.hivemq.system.os.global.memory.swap.total

Gauge

The current size of the paging/swap file(s), in bytes

com.hivemq.system.os.file-descriptors.open

Gauge

Amount of currently open file descriptors

com.hivemq.system.os.file-descriptors.max

Gauge

Maximum allowed amount of file descriptors

com.hivemq.system.os.global.cpu.<cpu-name>.usage.idle

Gauge

Percentage of time that the CPU or CPUs were idle and the system did not have an outstanding disk I/O request

com.hivemq.system.os.global.cpu.<cpu-name>.usage.iowait

Gauge

Percentage of time that the CPU or CPUs were idle during which the system had an outstanding disk I/O request

com.hivemq.system.os.global.cpu.<cpu-name>.usage.irq

Gauge

Percentage of time that the CPU used to service hardware IRQs

com.hivemq.system.os.global.cpu.<cpu-name>.usage.nice

Gauge

Percentage of CPU utilization that occurred while executing at the user level with nice priority

com.hivemq.system.os.global.cpu.<cpu-name>.usage.softirq

Gauge

Percentage of time that the CPU used to service soft IRQs

com.hivemq.system.os.global.cpu.<cpu-name>.usage.steal

Gauge

Percentage of time which the hypervisor dedicated for other guests in the system.

com.hivemq.system.os.global.cpu.<cpu-name>.usage.sys

Gauge

Percentage of CPU utilization that occurred while executing at the system level (kernel)

com.hivemq.system.os.global.cpu.<cpu-name>.usage.user

Gauge

Percentage of CPU utilization that occurred while executing at the user level (application)

com.hivemq.system.os.global.cpu.<cpu-name>.total

Gauge

Percentage of total CPU utilization for convenience (not idle, calculated as sum of usage values)

com.hivemq.system.os.process.threads.count

Gauge

Number of threads of the HiveMQ process as seen by the OS

com.hivemq.system.os.process.time-spent.user

Gauge

Amount of milliseconds the HiveMQ process has executed in user mode as seen by the OS

com.hivemq.system.os.process.time-spent.kernel

Gauge

Amount of milliseconds the HiveMQ process has executed in kernel/system mode as seen by the OS

com.hivemq.system.os.process.memory.virtual

Gauge

Virtual Memory Size (VSZ) in bytes. It includes all memory that the HiveMQ process can access, including memory that is swapped out and memory that is from shared libraries

com.hivemq.system.os.process.memory.resident-set-size

Gauge

Resident Set Size (RSS) in bytes. It is used to show how much memory is allocated to the HiveMQ process and is in RAM. It does not include memory that is swapped out. It does include memory from shared libraries as long as the pages from those libraries are actually in memory. It does include all stack and heap memory

com.hivemq.system.os.process.disk.bytes-written

Gauge

Number of bytes the HiveMQ process has written to disk

com.hivemq.system.os.process.disk.bytes-read

Gauge

Number of bytes the HiveMQ process has read from disk

com.hivemq.system.os.network-interface.<if-name>.bytes-received

Gauge

Bytes received by the network interface <if-name>

com.hivemq.system.os.network-interface.<if-name>.bytes-sent

Gauge

Bytes sent by the network interface <if-name>

com.hivemq.system.os.network-interface.<if-name>.packets-sent

Gauge

Packets sent by the network interface <if-name>

com.hivemq.system.os.network-interface.<if-name>.packets-received

Gauge

Packets received by the network interface <if-name>

com.hivemq.system.os.network-interface.<if-name>.in-errors

Gauge

Input errors for the network interface <if-name>

com.hivemq.system.os.network-interface.<if-name>.out-errors

Gauge

Output errors for the network interface <if-name>

com.hivemq.system.os.disks.<disk-name>.size

Gauge

Total size of disk with name <disk-name> in bytes

com.hivemq.system.os.disks.<disk-name>.read.count

Gauge

Amount of read operations for disk with name <disk-name>

com.hivemq.system.os.disks.<disk-name>.write.count

Gauge

Amount of read operations for disk with name <disk-name>

com.hivemq.system.os.disks.<disk-name>.read.bytes

Gauge

Amount of bytes read from disk with name <disk-name>

com.hivemq.system.os.disks.<disk-name>.write.bytes

Gauge

Amount of bytes written from disk with name <disk-name>

The following table lists all metrics that are specific to the Java Virtual Machine.

Table 6. JVM-specific metrics
Metric Type Description

com.hivemq.jvm.buffer-pool.direct.capacity

Gauge

The JVMs capacity of direct buffers.

com.hivemq.jvm.buffer-pool.direct.count

Gauge

The count of direct buffers in the JVM.

com.hivemq.jvm.buffer-pool.direct.used

Gauge

The amount of used direct buffers in the JVM.

com.hivemq.jvm.buffer-pool.mapped.capacity

Gauge

The JVMs capacity of mapped buffers.

com.hivemq.jvm.buffer-pool.mapped.count

Gauge

The count of mapped buffers in the JVM.

com.hivemq.jvm.buffer-pool.mapped.used

Gauge

The amount of used mapped buffers in the JVM.

com.hivemq.jvm.class-loader.loaded

Gauge

The total number of classes that have been loaded since the JVM has started execution.

com.hivemq.jvm.class-loader.unloaded

Gauge

The total number of classes unloaded since the JVM has started execution.

com.hivemq.jvm.file-descriptor.ratio

Gauge

Amount of file descriptors as seen by the JVM

com.hivemq.jvm.garbage-collector.G1-Old-Generation.count

Gauge

The total amount of collections that occurred.

com.hivemq.jvm.garbage-collector.G1-Old-Generation.time

Gauge

The approximate accumulated collection elapsed time.

com.hivemq.jvm.garbage-collector.G1-Young-Generation.count

Gauge

The total amount of collections that occurred.

com.hivemq.jvm.garbage-collector.G1-Young-Generation.time

Gauge

The approximate accumulated collection elapsed time.

com.hivemq.jvm.memory.heap.committed

Gauge

The amount of memory in bytes that is committed for the JVM to use.

com.hivemq.jvm.memory.heap.init

Gauge

The amount of memory in bytes that the JVM initially requests from the operating system for memory management.

com.hivemq.jvm.memory.heap.max

Gauge

The maximum amount of memory in bytes that can be used for memory management.

com.hivemq.jvm.memory.heap.usage

Gauge

The ratio of used memory and unused memory.

com.hivemq.jvm.memory.heap.used

Gauge

The amount of used memory in bytes.

com.hivemq.jvm.memory.non-heap.committed

Gauge

The amount of memory in bytes that is committed for the Java virtual machine to use.

com.hivemq.jvm.memory.non-heap.init

Gauge

The amount of memory in bytes that the JVM initially requests from the operating system for memory management.

com.hivemq.jvm.memory.non-heap.max

Gauge

The maximum amount of memory in bytes that can be used for memory management.

com.hivemq.jvm.memory.non-heap.usage

Gauge

The ratio of used memory and unused memory.

com.hivemq.jvm.memory.non-heap.used

Gauge

The amount of used memory in bytes.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.committed

Gauge

The amount of memory in bytes that is committed for the JVM to use in this memory pool.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.init

Gauge

The amount of memory in bytes that the JVM initially requests from the operating system for memory pool.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.max

Gauge

The maximum amount of memory in bytes that can be used for this memory pool.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.usage

Gauge

An estimate of the memory usage of this memory pool.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.used

Gauge

The amount of used memory in this memory pool in bytes.

com.hivemq.jvm.memory.pools.<Memory-Pool-Name>.used-after-gc

Gauge

The amount of memory usage int this memory pool after the last garbage collection.

com.hivemq.jvm.memory.total.committed

Gauge

The amount of memory in bytes that is committed for the Java virtual machine to use.

com.hivemq.jvm.memory.total.init

Gauge

The amount of memory in bytes that the JVM initially requests from the operating system for memory management.

com.hivemq.jvm.memory.total.max

Gauge

The maximum amount of memory in bytes that can be used for memory management.

com.hivemq.jvm.memory.total.used

Gauge

The amount of used memory in bytes.

com.hivemq.jvm.threads.blocked.count

Gauge

The amount of blocked threads in this JVM.

com.hivemq.jvm.threads.count

Gauge

The total amount of threads in this JVM.

com.hivemq.jvm.threads.daemon.count

Gauge

The amount of deamon threads in this JVM.

com.hivemq.jvm.threads.deadlock.count

Gauge

The amount of detected deadlocks in this JVM.

com.hivemq.jvm.threads.deadlocks

Gauge

The amount of detected deadlocks in this JVM.

com.hivemq.jvm.threads.new.count

Gauge

The amount of new threads in this JVM.

com.hivemq.jvm.threads.runnable.count

Gauge

The amount of runnable threads in this JVM.

com.hivemq.jvm.threads.terminated.count

Gauge

The amount of terminated threads in this JVM.

com.hivemq.jvm.threads.timed_waiting.count

Gauge

The amount of timed-waiting threads in this JVM.

com.hivemq.jvm.threads.waiting.count

Gauge

The amount of waiting threads in this JVM.

The following HiveMQ metrics are only available for HiveMQ server instances that are part of a cluster:

Table 7. Additional cluster environment metrics
Metric Type Description

com.hivemq.cluster.sent.*

Meter

Provides measures for every class that made once a SEND request (every class get its own metric)