Skip to content

General purpose Prometheus exporter for MQTT

License

Notifications You must be signed in to change notification settings

fhemberger/mqtt_exporter

 
 

Repository files navigation

Prometheus exporter for MQTT

Configurable general purpose Prometheus exporter for MQTT.

Subscribes to one or more MQTT topics, and lets you configure prometheus metrics based on pattern matching.

Test with pytestCodeQLDocker Pulls

Features

  • Supported Metrics:
    • standard metrics
      • Gauge, Counter, Histogram, Summary
    • additional
      • Counter (Absolute):
        • Same as Counter, but working with absolute numbers received from MQTT. Which is far more common, than sending the diff in each publish.
        • e.g. a network counter or a rain sensor
      • Enum:
        • is a metric type not so common, details can be found in the OpenMetrics docs and Python client code.
        • Allows to track as state by a know set of strings describing the state, e.g. on/off or high/medium/low
        • Common sources would be a light switch oder a door lock.
  • Comprehensive rewriting for topic, value/payload and labels
    • similar to prometheus label rewrites
    • regex allows almost every conversion
    • e.g. to
      • remove units or other strings from payload
      • convert topic hierarchy into labels
      • normalize labels
    • check example configs ./exampleconf and the configs in ./test/test_data/

Usage

  • Create a folder to hold the config (default: conf/)
  • Add metric config(s) in YAML format to the folder. Files are combined and read as a single config. (See exampleconf/metric_example.yaml for details)
  • Install dependencies with pip3 install -r requirements-frozen.txt
  • Run ./mqtt_exporter.py

Docker

For your convenience, there is also a Docker image available:

docker run -d \
  -v "$(pwd)/myconfig:/usr/src/app/conf:ro" \
  -p "9344:9344" \
  ghcr.io/fhemberger/mqtt_exporter

If you want to mount your configuration to a different directory, add the -c flag:

docker run -d \
  -v "$(pwd)/myconfig:/myconfig:ro" \
  -p "9344:9344" \
  ghcr.io/fhemberger/mqtt_exporter -c /myconfig

Python dependencies

  • paho-mqtt
  • prometheus-client
  • PyYAML
  • yamlreader

Contribution

  • Contribution is welcome. Fork and then PR.
  • Discussions in Issues.
  • Functional tests are written in pytest (see tests/readme.md)
  • Code formatting uses autopep8 with default settings. If you submit a PR to this repo, please make sure it follows its formatting guidelines.

TODO

  • Add persistence of metrics on restart
  • forget/age out metrics receiving no updates anymore

About

General purpose Prometheus exporter for MQTT

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Languages

  • Python 98.0%
  • Dockerfile 2.0%