Skip to content

inuits/mqttgateway

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Julien Pivotto
Jun 11, 2020
511169b · Jun 11, 2020

History

21 Commits
Jun 11, 2020
May 1, 2018
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
May 1, 2018
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020
Jun 11, 2020

Repository files navigation

MQTTGateway for Prometheus

circleci go report card

A project that subscribes to MQTT queues and published prometheus metrics.

usage: mqttgateway [<flags>]

Flags:
  --help                        Show context-sensitive help (also try --help-long and --help-man).
  --web.listen-address=":9337"  Address on which to expose metrics and web interface.
  --web.telemetry-path="/metrics"
                                Path under which to expose metrics.
  --mqtt.broker-address="tcp://localhost:1883"
                                Address of the MQTT broker.
                                The default is taken from $MQTT_BROKER_ADDRESS if it is set.
  --mqtt.topic="prometheus/#"   MQTT topic to subscribe to.
                                The default is taken from $MQTT_TOPIC if it is set.
  --mqtt.prefix="prometheus"    MQTT topic prefix to remove when creating metrics.
                                The default is taken from $MQTT_PREFIX if it is set.
  --mqtt.username=""            MQTT username.
                                The default is taken from $MQTT_USERNAME if it is set.
  --mqtt.password=""            MQTT password.
                                The default is taken from $MQTT_PASSWORD if it is set.
  --mqtt.clientid=""            MQTT client ID.
                                The default is taken from $MQTT_CLIENT_ID if it is set.
  --log.level="info"            Only log messages with the given severity or above. Valid levels: [debug, info, warn, error, fatal]
  --log.format="logger:stderr"  Set the log target and format. Example: "logger:syslog?appname=bob&local=7" or "logger:stdout?json=true"

Installation from source

Requires go

go get -u github.com/inuits/mqttgateway

Installation from binaries

Pre-built binaries are available on the releases page.

Installation with Docker

dockeri.co

Use a MQTT broker which runs locally:

$ docker run --network="host" -p 9337:9337 mqttgateway/mqttgateway

Use a MQTT broker which runs elsewhere:

$ docker run -p 9337:9337 mqttgateway/mqttgateway --mqtt.broker-address="tcp://mosquitto.local:1883"

How does it work?

mqttgateway will connect to the MQTT broker at --mqtt.broker-address and listen to the topics specified by --mqtt.topic.

By default, it will listen to prometheus/#.

The format for the topics is as follow:

prefix/LABEL1/VALUE1/LABEL2/VALUE2/NAME

A topic prometheus/job/ESP8266/instance/livingroom/temperature_celsius would be converted to a metric temperature_celsius{job="ESP8266",instance="livingroom"}.

If labelnames differ for a same metric, then we invalidate existing metrics and only keep new ones. Then we issue a warning in the logs. You should avoid it.

Two other metrics are published, for each metric:

  • mqtt_NAME_last_pushed_timestamp, the last time NAME metric has been pushed (unix time, in seconds)
  • mqtt_NAME_push_total, the number of times a metric has been pushed

Security

This project does not support authentication yet but that is planned.

Example

$ mosquitto_pub -m 20.2 -t prometheus/job/ESP8266/instance/livingroom/temperature_celsius
$ curl -s http://127.0.0.1:9337/metrics|grep temperature_celsius|grep -v '#'
mqtt_temperature_celsius_last_pushed_timestamp{instance="livingroom",job="ESP8266"} 1.525185129171293e+09
mqtt_temperature_celsius_push_total{instance="livingroom",job="ESP8266"} 1
temperature_celsius{instance="livingroom",job="ESP8266"} 20.2

A note about the prometheus config

If you use job and instance labels, please refer to the pushgateway exporter documentation.

TL;DR: you should set honor_labels: true in the scrape config.