HiveMQ Cloud Metrics

Metrics Index

Table 1. HiveMQ Cloud 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_policy_prevented_count`	`Counter`	The number of PUBLISH messages that dropped because a policy prevented onward delivery
`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`	`Counter`	The current total number of active MQTT connections
`hivemq_cloud_publish_without_matching_subscribers`	`Counter`	Counts the amount of publish messages received, without any matching subscribers
`hivemq_cloud_sessions_overall_current`	`Counter`	The current number of stored sessions. These sessions include all sessions, including online and offline clients
`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_shared_subscriptions_overall_current`	`Counter`	The current number of shared subscriptions on the broker
`hivemq_cloud_cloud_normalized_messages_total`	`Counter`	Total number of normalized messages
`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 attempts 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_extensions_$extensionname_normalized_messages_incoming_total`	`Counter`	Incoming messages per extension
`hivemq_cloud_extensions_$extensionname_normalized_messages_outgoing_total`	`Counter`	Outgoing messages per extension
`hivemq_cloud_data_hub_behavior_validation_clients_covered_count`	`Counter`	The number of connected clients to which at least one non-terminated behavior currently applies
`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_custom_counters_*`		Customer metrics that support IncrementBy semantics

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 API token.
On the Create API Token page, enter a unique name for the new token in the Token name field and select Custom in the Access Type field.

In the Access Type field select Custom.
From the Custom permissions options, select the Read and Otel metrics custom permissions.

Api Access - new token - metrics - 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
Retrieve your broker metrics in your own environment by running the following command:
```
curl -v https://${YOUR_REST_API_BASE_URL}/metrics -H "Authorization: Bearer ${TOKEN}"
```
YOUR_REST_API_BASE_URL: From the API Access tab.
TOKEN: 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:

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

scrape_configs:
  - job_name: 'hivemq'
    metrics_path: /metrics
    scheme: https
    static_configs:
      - targets:
        - "https://${YOUR_REST_API_BASE_URL}/metrics"
    authorization:
      credentials: "Bearer ${TOKEN}"

Replace ${YOUR_REST_API_BASE_URL} and ${TOKEN} with your actual values.

Conclusion

With the above procedure, you can effectively access and monitor HiveMQ Cloud metrics via API calls or integrate your metrics into Prometheus for continuous observability.