Skip to content
Switch branches/tags
This branch is even with master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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


  • 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/


  • 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 ./


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

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

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" \ -c /myconfig

Python dependencies

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


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


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