# Prometheus exporter for Victron MQTT devices

A purposely build Prometheus exporter for Victron Energy Cerbo GX MQTT devices.

(C) 2022 M. Konstapel https://meezenest.nl/mees

Based on the General purpose Prometheus exporter for MQTT from Frederic Hemberger.
(https://github.com/fhemberger/mqtt_exporter)

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

## Features

- Converts JSON string from Victron MQTT device topics to value readable by Prometheus.
- Sends keepalive signal to Victron Energy Cerbo GX MQTT device (every 30 seconds).
- 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](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset) and [Python client code](https://github.com/prometheus/client_python/blob/9a24236695c9ad47f9dc537a922a6d1333d8d093/prometheus_client/metrics.py#L640-L698).
      - 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 `./victron_mqtt_exporter.py`


## Python dependencies

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


## TODO

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