Skip to content

HiveMQ extension for transferring monitoring data to the time series database InfluxDB

License

Notifications You must be signed in to change notification settings

hivemq/hivemq-influxdb-extension

Repository files navigation

HiveMQ InfluxDB Monitoring Extension

Extension Type GitHub release (latest by date) GitHub GitHub Workflow Status

Purpose

The HiveMQ InfluxDB Extension can be leveraged to gather metrics from HiveMQ and persist them into a time series database. This database can be used as the data source for a monitoring dashboard (like Grafana) that drills down into the inner workings of HiveMQ and provides valuable insights to your operations team.

Installation

Installing the extension for HiveMQ is very easy:

  1. Download the extension from the HiveMQ website and unzip the downloaded zip file.

  2. In the folder hivemq-influxdb-extension, modify the influxdb.properties file to fit your needs. Check that the mandatory properties (host, port) are set

  3. Copy the folder hivemq-influxdb-extension to your <HIVEMQ_HOME>/extensions folder

  4. Done

Configuration

The InfluxDB Monitoring extension uses its own configuration file influxdb.properties. The extension won’t start if this file is missing or the required properties are not set.

General Configuration

Config name Required Description Default

mode

no

The mode configured for the InfluxDB sender. Possibilities are: http, tcp, udp, cloud

http

host

yes

The host name of the InfluxDB instance.

-

port

yes

The port number the InfluxDB instance is listening.

8086

protocol

no

The protocol the InfluxDB sender uses in http mode.

http (or https for cloud mode)

auth

no

The authorization string to be used to connect to InfluxDB, of format username:password. If mode "cloud" is used, the token must be passed here

-

prefix

no

The measurement prefix.

-

database

no

The database name.

hivemq

reportingInterval

no

The reporting interval in seconds.

1

connectTimeout

no

The connect and read timeout in seconds.

5000

tags

no

The tags for each metric. Listed as a semicolon ( ; ) separated list.

-

organization

only for mode: "cloud"

The organization to push data to

-

bucket

only for mode: "cloud"

The bucket to push data to

-

Note
When using InfluxDB 2 the Cloud mode should be configured.
Example Configuration
mode:http
host:localhost
port:8086
protocol:http
auth:

prefix:
database:hivemq

reportingInterval:1
connectTimeout:5000

tags:host=hivemq1

First Steps

Quick Start InfluxDB

If you don’t already have an InfluxDB instance set up, here is an instruction how to start a not configured InfluxDB instance with Docker.

  1. Download and install Docker for your platform

  2. Start an InfluxDB docker container with the command docker run -p 8086:8086 -v $PWD:/var/lib/influxdb influxdb. For more information about using InfluxDB with Docker visit the official Docker repository for InfluxDB

  3. A local instance of InfluxDB should be running with the port for the database set to 8086

  4. Create a database that matches the name set in the property database in influxdb.properties. For the default database value use the command curl -G http://localhost:8086/query --data-urlencode "q=CREATE DATABASE hivemq"

  5. Done

Usage

After the extension is installed and an InfluxDB instance exists.

  1. Start HiveMQ

  2. Extension successfully started if configuration file exists and contains required properties

Need Help?

If you encounter any problems, we are happy to help. The best place to get in contact is our support.

Contributing

If you want to contribute to HiveMQ InfluxDB Extension, see the contribution guidelines.

License

HiveMQ InfluxDB Extension is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.