HiveMQ Extension
Sparkplug and InfluxDB
The HiveMQ Sparkplug Extension can be leveraged to gather MQTT Sparkplug metrics from HiveMQ and persist them into a InfluxDB database.
Category: Monitoring
License: Apache 2.0
Provider: HiveMQ
Verified: Yes
Purpose
The HiveMQ Sparkplug Extension can be leveraged to gather MQTT Sparkplug metrics from HiveMQ and persist them into a InfluxDB database. This database can be used as the data source for a monitoring dashboard to monitor directly the data from the devices and gateways of a Sparkplug Infrastructure.
This extension is not yet ready for production use.
If you want to use this in production, please contact HiveMQ contact@hivemq.com
Flow
Installation
Installing the extension for HiveMQ is very easy:
Unzip the downloaded zip file
In the folder
hivemq-sparkplug-extension, modify thesparkplug.propertiesfile to fit your needs. Check that the mandatory properties from influxDB (host, port) are set.Copy the folder
hivemq-sparkplug-extensionto your[HIVEMQ_HOME]/extensionsfolderDone
Configuration
The Sparkplug Monitoring extension uses its own configuration file sparkplug.properties. The extension won’t start if this file is missing or the required properties are not set.
Dashboards
2 InfluxDB example dashboards are provided in the deploy subfolder of this extension.
| InfluxDB dashboard | Description |
|---|---|
| HiveMQInfluxDB-Dashboard.json | HiveMQ dashboard with the most useful HiveMQ metrics |
| SparkplugInfluxDB-Dashboard.json | Sparkplug example dashboard, that vizualizes data of 2 edge nodes and their related devices. |
General Configuration
| Config name | Required | Description | Default |
|---|---|---|---|
| influxdb.mode | no | The mode configured for the InfluxDB sender. Possibilities are: http, tcp, udp, cloud | http |
| influxdb.host | yes | The host name of the InfluxDB instance. | |
| influxdb.port | yes | The port number the InfluxDB instance is listening. | 8086 |
| influxdb.protocol | no | The protocol the InfluxDB sender uses in http mode. | http |
| influxdb.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 | |
| influxdb.prefix | no | The measurement prefix. | |
| influxdb.database | no | The database name. | hivemq |
| influxdb.reportingInterval | no | The reporting interval in seconds. | 1 |
| influxdb.connectTimeout | no | The connect and read timeout in seconds. | 5000 |
| influxdb.tags | no | The tags for each metric. Listed as a semicolon ( ; ) separated list. | |
| influxdb.organization | only for mode: “cloud” | The organization to push data to | |
| influxdb.bucket | only for mode: “cloud” | The bucket to push data to | |
| sparkplug.version | no | The sparkplug version to be used | spBv1.0 |
Example Configuration to connect to a local Influxdb 2.0
influxdb.mode:cloud
influxdb.host:localhost
influxdb.port:8086
influxdb.protocol:http
influxdb.auth:<your token>
influxdb.bucket:hivemq
influxdb.organization:<your company>
influxdb.reportingInterval:1
influxdb.connectTimeout:5000
influxdb.tags:host=localhost First Steps
Quick Start Sparkplug
InfluxDB setup
If you don’t already have an InfluxDB 2.0 instance set up, here is an instruction how to start and configure an InfluxDB instance with Docker.
Download and install Docker for your platform
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 InfluxDBA local instance of InfluxDB should be running with the port for the database set to 8086
The initial setup process for InfluxDB walks through creating a default organization, user, bucket, and Admin authentication token. The setup process is available in both the InfluxDB user interface (UI) and in the influx command line interface (CLI).
UI Setup - With InfluxDB running, visit localhost:8086.
Click Get Started
Set up your initial user
Enter a Username for your initial user
Enter a Password and Confirm Password for your user
Enter your initial Organization Name
Enter your initial Bucket Name
Click Continue
Done
Sparkplug setup
The Extensions actual supports the Sparkplug B specification for a payload. The sparkplug schema is defined with protobuf.
Usage
After the extension is installed and an InfluxDB instance exists.
Start HiveMQ
Extension successfully started if configuration file exists and contains required properties
Example deployment
For testing purposes a simple HiveMQ docker file with the sparkplug extension, and a compose file for influxDB setup is available in the deploy/docker subfolder. Further a Kubernetes script for deploying hivemq with sparkplug extension setup in Kuberntes is available in the deploy/k8s
Influx Dashboard
An influx dashboard example SparkplugInfluxDB-Dashboard.json is available in the deploy subfolder. The dashboard contains diagrams to monitor the Sparkplug online status of edge nodes and devices. It also gathered the sparkplug data values from the example devices.
Contributing
If you want to contribute to HiveMQ Sparkplug Extension, see the Contribution Guidelines.
License
HiveMQ Sparkplug Extension is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.
Need Help?
We're always happy to answer any questions you may have during installation. The best place to get in contact is our community forum.
Get started with HiveMQ today
Choose between a fully-managed cloud or self-managed MQTT platform. Our MQTT experts can help you with your solution and demonstrate HiveMQ in action.
