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_sessions_overall_current

Counter

The current number of stored sessions. These sessions include all sessions, including online and offline clients.

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.

Api Access - new token - unique name
  • In the Access Type field select Custom.

  • From the Custom permissions options, select the Read and Otel metrics custom permissions.

  • To create the new API token, select Create API token.

  • On the API Access overview, select Copy Token. NOTE: 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, run the following command:

    curl -v https://${YOUR_REST_API_BASE_URL}/metrics -H "Authorization: Bearer ${TOKEN}"
  • In the command, replace YOUR_REST_API_BASE_URL with the REST API BASE URL 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.

Integrating HiveMQ Broker Metrics into Prometheus

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

  1. Edit your Prometheus configuration (prometheus.yml)

  2. 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.