Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gaelreyrol/mqtt-exporter
[WIP] Export MQTT messages to Prometheus
https://github.com/gaelreyrol/mqtt-exporter
mqtt prometheus-exporter
Last synced: 26 days ago
JSON representation
[WIP] Export MQTT messages to Prometheus
- Host: GitHub
- URL: https://github.com/gaelreyrol/mqtt-exporter
- Owner: gaelreyrol
- License: mit
- Created: 2023-07-13T17:42:25.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-09-15T00:09:04.000Z (about 2 months ago)
- Last Synced: 2024-09-15T07:03:29.783Z (about 2 months ago)
- Topics: mqtt, prometheus-exporter
- Language: Go
- Homepage:
- Size: 6.72 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: ReadMe.md
- License: LICENSE
Awesome Lists containing this project
README
# mqtt-exporter
[](https://github.com/gaelreyrol/mqtt-exporter/actions/workflows/ci.yml)
[](http://unmaintained.tech/)
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:
```bash
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:
```txt
# 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](https://toml.io/en/) format.
Here is a configuration example:
```toml
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`:
```json
{
"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](https://mosquitto.org/)
- Go ^1.20
Or install Nix and run `nix develop`.
## ToDo
- [ ] Unit tests basic features
- [ ] Real world tests with NixOS test VM
- [x] Split listening and exporting via topic channels
- [ ] Forget messages between intervals