mqtt-exporter

Export MQTT messages to Prometheus

Info This exporter allows you to simplify your IoT monitoring stack if you don't want to store messages on the long run. While InfluxDB or other timeseries database are well suited for IoT messages, I built this exporter because I don't need those databases, I just need a temporary storage (at least a few months). Also Prometheus is a piece of software that is already deployed in my stack along with Grafana, so I wanted to keep it simple and stupid. I do not recommend any one to use this project unless your motivations are the same.

This project is still a work in progress.

Usage

With Go:

go install github.com/gaelreyrol/mqtt-exporter

You can change the following options from the command line:

the listening address server with -listen-addr, defaults to :8181.
the telemetry path with -telemetry-path, defaults to /metrics.
the config file path with -config-path, defaults to /etc/mqtt-exporter.toml.

Here is an example of the output generated by the exporter:

# HELP mqtt_topic_field
# TYPE mqtt_topic_field gauge
mqtt_topic_field{name="outside_temperature",topic="zigbee2mqtt/my_thermostat"} 12.6
mqtt_topic_field{name="inside_temperature",topic="zigbee2mqtt/my_thermostat"} 19
# HELP mqtt_topic_messages_total
# TYPE mqtt_topic_messages_total counter
mqtt_topic_messages_total{topic="zigbee2mqtt/my_thermostat"} 14

Configuration

The configuration file follows the TOML format.

Here is a configuration example:

broker = "localhost:1883"

[[topics]]
name = "zigbee2mqtt/my_thermostat"
fields = [
    "outside_temperature",
    "inside_temperature",
]

`broker`

The MQTT broker TCP address, for example localhost:1883.

It does no yet support encryption nor authentication.

`topics`

Topics represents each topic messages to export to Prometheus.

The name field represents the topic name available in your broker. The fields field represents each key that should be exported to Prometheus from a message received in the topic.

For example if the following payload is received with two fields defined outside_temperature and inside_temperature:

{
    "outside_temperature": 12.6,
    "inside_temperature": 19,
    "garage_temperature": 14
}

The garage_temperature field will not be exported to Prometheus.

Warning Only JSON is supported with zero level of depth, every value must be at the root of the JSON object.

Warning Each value's field extracted from the payload must be float compatible. Strings or child object path values are not supported.

Development

Requirements

A MQTT broker such as Mosquitto
Go ^1.20

Or install Nix and run nix develop.

ToDo

Unit tests basic features
Real world tests with NixOS test VM
Split listening and exporting via topic channels
Forget messages between intervals