HiveMQ Cloud Metrics

The metrics HiveMQ exposes for your HiveMQ Cloud cluster vary based on your HiveMQ Cloud plan.

Metrics Overview

Each HiveMQ Cloud plan provides a different level of monitoring:

Starter: Access to essential metrics for basic monitoring and troubleshooting.
Enterprise: Comprehensive metrics including all Starter metrics plus advanced monitoring capabilities

HiveMQ Cloud Starter Metrics

Clusters on the HiveMQ Cloud Starter plan provide the following metrics:

Table 1. HiveMQ Cloud Starter Metrics
Metric	Type	Description
`hivemq_cloud_keep_alive_disconnect_count`	`Counter`	Counts every closed connection that was closed because the client missed sending a PINGREQ message during the keep-alive interval
`hivemq_cloud_messages_client_queued_count`	`Gauge`	The current number of queued messages for client sessions
`hivemq_cloud_messages_client_pending_qos_0_count`	`Gauge`	The current number of pending QoS 0 messages for client sessions
`hivemq_cloud_messages_client_pending_total_count`	`Gauge`	The total number of pending messages for client sessions
`hivemq_cloud_messages_dropped_consumer_queue_full_count`	`Counter`	The number of PUBLISH messages that dropped because the message queue for a consumer topic was full
`hivemq_cloud_messages_dropped_count`	`Counter`	The total number of dropped messages on the broker
`hivemq_cloud_messages_dropped_extension_prevented_count`	`Counter`	The number of PUBLISH messages that dropped because a Publish Inbound Interceptor prevented onward delivery
`hivemq_cloud_messages_dropped_internal_error_count`	`Counter`	The number of PUBLISH messages that dropped because of an internal error
`hivemq_cloud_messages_dropped_message_too_large_count`	`Counter`	The number of PUBLISH messages that dropped because the message size was too large for the client
`hivemq_cloud_messages_dropped_mqtt_packet_too_large_count`	`Counter`	The number of MQTT messages (excluding PUBLISH packets) that dropped because the message size was too large for the client
`hivemq_cloud_messages_dropped_not_writable_count`	`Counter`	The number of PUBLISH messages that dropped because the socket for the client was not writable (QoS 0 only)
`hivemq_cloud_messages_dropped_qos_0_memory_exceeded_count`	`Counter`	The number of PUBLISH messages that dropped because the global memory limit for QoS 0 messages was exceeded
`hivemq_cloud_messages_dropped_queue_full_count`	`Counter`	The number of PUBLISH messages that dropped because the message queue for a disconnected persistent session client was full
`hivemq_cloud_messages_dropped_shared_queue_full_count`	`Counter`	The number of PUBLISH messages that are dropped because the message queue for a shared subscription is full
`hivemq_cloud_messages_expired_messages`	`Counter`	The total number of expired messages on the broker
`hivemq_cloud_messages_incoming_connect_count`	`Counter`	Counts every incoming MQTT CONNECT message
`hivemq_cloud_messages_incoming_publish_count`	`Counter`	Counts every incoming MQTT PUBLISH message
`hivemq_cloud_messages_outgoing_publish_count`	`Counter`	Counts every outgoing MQTT PUBLISH message
`hivemq_cloud_networking_connections_current`	`Gauge`	The current total number of active MQTT connections
`hivemq_cloud_normalized_messages_total`	`Counter`	Total number of normalized messages
`hivemq_cloud_publish_without_matching_subscribers`	`Counter`	Counts the amount of publish messages received, without any matching subscribers
`hivemq_cloud_sessions_persistent_active`	`Counter`	The current number of active persistent sessions (= Online MQTT clients which are connected with cleanSession=false)
`hivemq_cloud_subscriptions_overall_current`	`Counter`	The current number of subscriptions on the broker
`hivemq_cloud_data_hub_behavior_validation_clients_covered_count`	`Counter`	The number of connected clients to which at least one non-terminated behavior is currently applied
`hivemq_cloud_data_hub_behavior_validation_policies_failed_count`	`Counter`	The total number of failed terminations of behaviors
`hivemq_cloud_data_hub_behavior_validation_policies_successful_count`	`Counter`	The total number of successful terminations of behaviors
`hivemq_cloud_data_hub_behavior_validation_schema_deserializations_failed_count`	`Counter`	The total number of failed schema deserializations in behavior policies
`hivemq_cloud_data_hub_behavior_validation_schema_deserializations_successful_count`	`Counter`	The total number of successful schema deserializations in behavior policies
`hivemq_cloud_data_hub_behavior_validation_states_initialized_count`	`Counter`	The total number of behavior states initialized for all clients
`hivemq_cloud_data_hub_messages_dropped_policy_prevented_count`	`Counter`	The number of PUBLISH messages that are dropped because a policy prevented onward delivery
`hivemq_cloud_data_hub_data_validation_payload_validation_failed_count`	`Counter`	The total number of payloads that failed to validate successfully
`hivemq_cloud_data_hub_data_validation_payload_validation_successful_count`	`Counter`	The total number of payloads that validated successfully
`hivemq_cloud_data_hub_data_validation_policies_failed_count`	`Counter`	The total number of policies that had a failed outcome
`hivemq_cloud_data_hub_data_validation_policies_successful_count`	`Counter`	The total number of policies that had a successful outcome
`hivemq_cloud_data_hub_data_validation_schema_validations_failed_count`	`Counter`	The total number of failed schema validations
`hivemq_cloud_data_hub_data_validation_schema_validations_successful_count`	`Counter`	The total number of successful schema validations
`hivemq_cloud_data_hub_data_validation_validators_failed_count`	`Counter`	The total number of validators that had a failed outcome
`hivemq_cloud_data_hub_data_validation_validators_successful_count`	`Counter`	The total number of validators that had a successful outcome
`hivemq_cloud_data_hub_scripting_script_runtime_scripts_count`	`Gauge`	The current number of loaded scripts in the script engine
`hivemq_cloud_shared_subscriptions_overall_current`	`Counter`	The current number of shared subscriptions on the broker
`hivemq_cloud_kafka_extension_total_failed_count`	`Counter`	The total number of records the extension cannot produce to Kafka
`hivemq_cloud_kafka_extension_total_ignored_count`	`Counter`	The total number of records the extension ignored
`hivemq_cloud_kafka_extension_total_retry_count`	`Counter`	The total number of records that were retried to be produced to Kafka
`hivemq_cloud_kafka_extension_total_send_count`	`Counter`	The total number of records the extension attempted to send to Kafka
`hivemq_cloud_kafka_extension_total_success_count`	`Counter`	The total number of records the extension successfully produced to Kafka
`hivemq_cloud_mqtt_to_pubsub_total_dropped_count`	`Counter`	The total number of messages the extension drops from MQTT to Google Cloud Pub/Sub
`hivemq_cloud_mqtt_to_pubsub_total_failed_count`	`Counter`	The total number of MQTT to Google Cloud Pub/Sub messages the extension cannot successfully forward
`hivemq_cloud_mqtt_to_pubsub_total_ignored_count`	`Counter`	The total number of MQTT to Google Cloud Pub/Sub messages the extension ignores
`hivemq_cloud_mqtt_to_pubsub_total_resent_count`	`Counter`	The total number of MQTT to Google Cloud Pub/Sub messages the extension resends
`hivemq_cloud_mqtt_to_pubsub_total_sent_count`	`Counter`	The total number of MQTT to Google Cloud Pub/Sub messages the extension sends
`hivemq_cloud_mqtt_to_pubsub_total_success_count`	`Counter`	The total number of MQTT to Google Cloud Pub/Sub messages from all transformers and mappings that the extension successfully forwards

HiveMQ Cloud Enterprise Metrics

In addition to all Starter metrics, HiveMQ Cloud Enterprise offers the following advanced monitoring metrics:

Additional HiveMQ Cloud Enterprise Metrics

Table 2. Additional HiveMQ Cloud Enterprise Metrics
Metric	Type	Description
`hivemq_cloud_messages_incoming_connect_mqtt3_count`	`Counter`	Counts every incoming MQTT 3 CONNECT message
`hivemq_cloud_messages_incoming_connect_mqtt5_count`	`Counter`	Counts every incoming MQTT 5 CONNECT message
`hivemq_cloud_messages_incoming_publish_qos_0_count`	`Counter`	Counts every incoming MQTT PUBLISH message that is sent with quality of service (QoS) level 0
`hivemq_cloud_messages_incoming_publish_qos_1_count`	`Counter`	Counts every incoming MQTT PUBLISH message that is sent with quality of service (QoS) level 1
`hivemq_cloud_messages_incoming_publish_qos_2_count`	`Counter`	Counts every incoming MQTT PUBLISH message that is sent with quality of service (QoS) level 2
`hivemq_cloud_messages_outgoing_publish_qos_0_count`	`Counter`	Counts every outgoing MQTT PUBLISH message that is sent with quality of service (QoS) level 0
`hivemq_cloud_messages_outgoing_publish_qos_1_count`	`Counter`	Counts every outgoing MQTT PUBLISH message that is sent with quality of service (QoS) level 1
`hivemq_cloud_messages_outgoing_publish_qos_2_count`	`Counter`	Counts every outgoing MQTT PUBLISH message that is sent with quality of service (QoS) level 2
`hivemq_cloud_messages_queued_count`	`Gauge`	The current number of queued messages
`hivemq_cloud_networking_bytes_read_current`	`Gauge`	The current (last 5 seconds) amount of read bytes
`hivemq_cloud_networking_bytes_write_current`	`Gauge`	The current (last 5 seconds) amount of written bytes

HiveMQ Cloud Enterprise Dead Messages Queue Metrics

Table 3. HiveMQ Cloud Enterprise Dead Messages Queue Metrics
Metric	Type	Description
`hivemq_cloud_messages_dead_count`	`Counter`	The total number of dead messages the broker detects
`hivemq_cloud_messages_dead_topic_enqueued_count`	`Counter`	The number of dead messages that are queued to a dead topic
`hivemq_cloud_messages_dead_topic_dead_count`	`Counter`	The number of dead messages that are dead more than once
`hivemq_cloud_messages_dead_topic_dropped_count`	`Counter`	The number of dead messages that are dropped
`hivemq_cloud_messages_dead_topic_expired_count`	`Counter`	The number of dead messages that are expired

HiveMQ Cloud Enterprise Dropped Messages Topic Metrics

Table 4. Enterprise Dropped Message Topic Metrics
Metric	Type	Description
`hivemq_cloud_messages_dropped_topic_dead_count`	`Counter`	The number of messages that are dead
`hivemq_cloud_messages_dropped_topic_dropped_count`	`Counter`	The number of messages that dropped due to queue limits
`hivemq_cloud_messages_dropped_topic_message_created_client_count`	`Counter`	The number of messages that originate from clients
`hivemq_cloud_messages_dropped_topic_message_created_shared_count`	`Counter`	The number of messages that originate from shared subscriptions
`hivemq_cloud_messages_dropped_topic_message_created_consumer_count`	`Counter`	The number messages that originate from consumers
`hivemq_cloud_messages_dropped_topic_enqueued_count`	`Counter`	The number of messages that are enqueued for a topic

HiveMQ Cloud Enterprise Expired Messages Topic Metrics

Table 5. HiveMQ Cloud Enterprise Expired Messages Topic Metrics
Metric	Type	Description
`hivemq_cloud_messages_expired_topic_dead_count`	`Counter`	The number of expired messages that are dead
`hivemq_cloud_messages_expired_topic_dropped_count`	`Counter`	The number of expired messages that are dropped due to queue limits
`hivemq_cloud_messages_expired_topic_expired_count`	`Counter`	The number of expired messages that expire more than once
`hivemq_cloud_messages_expired_topic_enqueued_count`	`Counter`	The number of expired messages that are enqueued for an expired topic

HiveMQ Cloud Enterprise Data Hub Metrics

Table 6. HiveMQ Cloud Enterprise Data Hub Metrics
Metric	Type	Description
`hivemq_cloud_data_hub_behavior_policy_persistence_size_total`	`Gauge`	The current number of policy entries in the behavior policy persistence
`hivemq_cloud_data_hub_behavior_validation_transitions_performed_count`	`Gauge`	The total number of state transitions behaviors perform
`hivemq_cloud_data_hub_data_policy_persistence_size_total`	`Gauge`	The current number of data policy entries in the persistence
`hivemq_cloud_data_hub_schema_persistence_size_total`	`Gauge`	The current amount of schema entries in the persistence
`hivemq_cloud_data_hub_script_persistence_size_total`	`Gauge`	The current number of script entries in the persistence

HiveMQ Cloud OpenAPI Reference

For a detailed API reference, see: OpenAPI

Access HiveMQ Broker Metrics From a Remote Service

To retrieve raw metrics from a service, follow these steps:

Generate an API Token

Log into the HiveMQ Cloud web console, navigate to API Access in the top navigation of your HiveMQ Cloud cluster, and select Create new token.
On the Create API Token page, enter a unique name for the new token in the Token name field.
In the Access Type field select Custom.
From the Custom permissions options, select the Read and Otel metrics custom permissions.
To generate the new API token, select Create API token.
On the API Access overview, select Copy Token.

Make sure to copy your token. Once you leave the API page, you will be unable to copy the token.

Make an API Call

To retrieve your broker metrics in your own environment, copy the following command:

curl -v https://${YOUR_REST_API_BASE_URL}/metrics -H "Authorization: Bearer ${TOKEN}"

Then, paste the command in your editor and modify the command with the following substitutions:
- Replace https://${YOUR_REST_API_BASE_URL} with the REST API BASE URL value provided on the API Access tab of your cluster.
- Replace ${TOKEN} in the command with the API token you generated and copied in the previous steps.
Now, run the command. This command returns the current metrics from the broker.

Integrating HiveMQ Broker Metrics into Prometheus

To collect and monitor HiveMQ Cloud metrics in Prometheus, follow these steps:

Edit your Prometheus configuration (prometheus.yml)
Add the following scrape job:

scrape_configs:
  - job_name: 'hivemq'
    metrics_path: '${PATH_TO_METRICS_ENDPOINT}/metrics'
    scheme: https
    static_configs:
      - targets:
        - '${YOUR_REST_API_URL}'
    bearer_token: '${TOKEN}'

Here is an example configuration:

scrape_configs:
  - job_name: 'hivemq'
    metrics_path: '/api/v2/orgs/rngipm/clusters/551f55b3-3026-420c-8908-95e958905055/metrics'
    scheme: https
    static_configs:
      - targets:
          - 'api.a01.euc1.aws.hivemq.cloud'
    bearer_token: 'eyJ...'

${PATH_TO_METRICS_ENDPOINT} is part of the REST API BASE URL provided on the API Access tab of your cluster.

${YOUR_REST_API_URL} is also provided on the API Access tab of your cluster.