HiveMQ Prometheus Plugin

Note	HiveMQ 4 uses a new extension system. This HiveMQ 3 plugin is not compatible with HiveMQ 4. The new version can be found here.

This plugin allows you to gather HiveMQ metrics with Prometheus and expose them via an HTTP interface.

First steps

1. Move the jar file to your plugins folder of HiveMQ.

2. Move the sample prometheusConfiguration.properties file to the conf folder of HiveMQ.

3. Configure the prometheusConfiguration.properties to your needs (The meaning of the fields is explained below).

4. Start HiveMQ.

5. You can test your configuration by navigating to <ip>:<port>/servlet<metric_path> (as configured in prometheusConfiguration.properties) in your browser. (Do not forget to insert "/servlet"). For example the address would be http://localhost:9399/servlet/metrics with default values. You should see data provided by the plugin:

#HELP com_hivemq_RESTService_percent_4xx_15m Generated from Dropwizard metric import (metric=com.hivemq.RESTService.percent-4xx-15m, type=com.codahale.metrics.jetty9.InstrumentedHandler$3)
# TYPE com_hivemq_RESTService_percent_4xx_15m gauge
com_hivemq_RESTService_percent_4xx_15m 1.0
...

6. Load and install Prometheus

7. Configure Prometheus to scrape from <ip>:<port>/servlet<metricPath> as configured in the prometheusConfiguration.properties. (IMPORTANT: Do not forget to insert "/servlet", or prometheus will not be able to scrape the metrics from HiveMQ)

8. Look at the website provided by your Prometheus application. You should be able to find the HiveMQ metrics.

Configuration of the Prometheus Plugin

The plugin can be configured with the prometheusConfiguration.properties file, which needs to be placed in HiveMQ’s conf folder.

Table 1. Configuration Options

Name	Default	Description
port	9399	The port which the servlet will listen to
host	0.0.0.0	The bind-address which the servlet will listen to
metric_path	/metrics	The path for the servlet which gets called by Prometheus. It must start with a slash. (IMPORTANT: /servlet will be inserted between <ip>:<port> and <metric_path>. For example 127.0.0.1:9399/servlet/metrics)

Configuration of Prometheus

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 plugin:

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'hivemq'
    scrape_interval: 5s
    metrics_path: '/servlet/metrics'
    static_configs:
      - targets: ['localhost:9399']

= Contributing

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

= License

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