:hivemq-link: https://www.hivemq.com :hivemq-support: {hivemq-link}/support/

= HiveMQ Prometheus Extension

image:https://img.shields.io/badge/Extension_Type-Monitoring-orange?style=for-the-badge[Extension Type] image:https://img.shields.io/github/v/release/hivemq/hivemq-prometheus-extension?style=for-the-badge[GitHub release (latest by date),link=https://github.com/hivemq/hivemq-prometheus-extension/releases/latest] image:https://img.shields.io/github/license/hivemq/hivemq-prometheus-extension?style=for-the-badge&color=brightgreen[GitHub,link=LICENSE] image:https://img.shields.io/github/actions/workflow/status/hivemq/hivemq-prometheus-extension/check.yml?branch=master&style=for-the-badge[GitHub Workflow Status,link=https://github.com/hivemq/hivemq-prometheus-extension/actions/workflows/check.yml?query=branch%3Amaster]

== Purpose

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

== Installation

. Unzip the file: hivemq-prometheus-extension-<version>-distribution.zip to the directory: <HIVEMQ_HOME>/extensions . A configuration file prometheusConfiguration.properties can be found in the hivemq-prometheus-extension folder. The properties are preconfigured with standard settings and can be adapted to your needs (The meaning of the fields is explained below). . Start HiveMQ.

== Configuration

The extension can be configured with the prometheusConfiguration.properties file, which is part of the hivemq-prometheus-extension folder.

[cols="1m,1,2" options="header"] .Configuration Options |=== |Name |Default |Description

|port |9399 |The port which the servlet will listen to.

|ip |0.0.0.0 |The bind-address which the servlet will listen to.

|metric_path |/metrics |The path for the service which gets called by Prometheus. It must start with a slash.

|===

== First Steps

You can test your configuration by navigating to <ip>:<port><metric_path> (as configured in prometheusConfiguration.properties) in your browser. For example the address would be http://localhost:9399/metrics with default values.

You should see data provided by the extension:

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

== Final Steps

. Load and install Prometheus . Configure Prometheus to scrape from :<metricPath> as configured in the prometheusConfiguration.properties. . Look at the website provided by your Prometheus application. You should be able to find the HiveMQ metrics.

For detailed information please visit: https://prometheus.io/docs/operating/configuration/

To enable Prometheus to gather metrics from HiveMQ, you need to add a scrape configuration to your Prometheus configuration. The following is a minimal example using the default values of the extension:

.prometheus.yml

global: scrape_interval: 15s scrape_configs:

• job_name: 'hivemq' scrape_interval: 5s metrics_path: '/metrics' static_configs:
  • targets: ['localhost:9399']

== Need Help?

If you encounter any problems, we are happy to help. The best place to get in contact is our {hivemq-support}[support].

== Contributing

If you want to contribute to HiveMQ Prometheus Extension, see the link:CONTRIBUTING.md[contribution guidelines].

== License

HiveMQ Prometheus Extension is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found link:LICENSE[here].