From cdb02b9efedebafeac6b11cde593c3eb2c58273a Mon Sep 17 00:00:00 2001 From: Christoph Petrausch Date: Sat, 18 Jul 2020 20:13:23 +0200 Subject: [PATCH] Updated readme --- Readme.md | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/Readme.md b/Readme.md index 626c1dd..80a70bb 100644 --- a/Readme.md +++ b/Readme.md @@ -8,28 +8,27 @@ publish the received messages as prometheus metrics. I wrote this exporter to pu metrics from small embedded sensors based on the NodeMCU to prometheus. The used arduino scetch can be found in the [dht22tomqtt](https://github.com/hikhvar/dht22tomqtt) repository. ## Assumptions about Messages and Topics -This exporter makes some assumptions about the message format and MQTT topics. This exporter assumes that each -client publish the metrics into a dedicated topic. The last level topic becomes the `sensor` label in prometheus. -This exporter assume that the message are JSON objects with only float fields. The golang type for the messages is: - -```go -type MQTTPayload map[string]float64 -``` - -For example the message +This exporter makes some assumptions about the MQTT topics. This exporter assumes that each +client publish the metrics into a dedicated topic. The regular expression ìn the configuration field `mqtt.device_id_regex` +defines how to extract the device ID from the MQTT topic. This allow an arbitrary place of the device ID in the mqtt topic. +For example the [tasmota](https://github.com/arendst/Tasmota) firmware pushes the telemetry data to the topics `tele//SENSOR`. +Let us assume the default configuration from [#ConfigFile]. A sensor publishes the following message ```json -{"temperature":23.20,"humidity":51.60,"heat_index":22.92} +{"temperature":23.20,"humidity":51.60, "computed": {"heat_index":22.92} } ``` -published to the MQTT topic `devices/me/livingroom` becomes the following prometheus metrics: +to the MQTT topic `devices/me/livingroom`. This message becomes the following prometheus metrics: ```text -temperature{sensor="livingroom"} 23.2 -heat_index{sensor="livingroom"} 22.92 -humidity{sensor="livingroom"} 51.6 +temperature{sensor="livingroom",topic="devices/me/livingroom"} 23.2 +heat_index{sensor="livingroom",topic="devices/me/livingroom"} 22.92 +humidity{sensor="livingroom",topic="devices/me/livingroom"} 51.6 ``` +### Tasmota +An example configuration for the tasmota based Gosund SP111 device is given in [examples/gosund_sp111.yaml](examples/gosund_sp111.yaml). + ## Build To build the exporter run: @@ -85,18 +84,23 @@ The config file can look like this: mqtt: # The MQTT broker to connect to server: tcp://127.0.0.1:1883 - # The Topic path to subscripe to. Actually this will become `$topic_path/+` - topic_path: v1/devices/me + # The Topic path to subscripe to. Be aware that you have to specify the wildcard. + topic_path: v1/devices/me/+ + # Optional: Regular expression to extract the device ID from the topic path. The default regular expression, assumes + # that the last "element" of the topic_path is the device id. + # The regular expression must contain a named capture group with the name deviceid + # For example the expression for tasamota based sensors is "tele/(?P.*)/.*" + device_id_regex: "(.*/)?(?P.*)" # The MQTT QoS level qos: 0 cache: # Timeout. Each received metric will be presented for this time if no update is send via MQTT - timeout: 2min + timeout: 24h # This is a list of valid metrics. Only metrics listed here will be exported metrics: # The name of the metric in prometheus - prom_name: temperature_celsius - # The name of the metric in a MQTT JSON message + # The name of the metric in a MQTT JSON message. This can be an arbitrary gojsonq path. mqtt_name: temperature # The prometheus help text for this metric help: DHT22 temperature reading @@ -118,8 +122,8 @@ metrics: sensor_type: dht22 # The name of the metric in prometheus - prom_name: heat_index - # The name of the metric in a MQTT JSON message - mqtt_name: heat_index + # The name of the metric in a MQTT JSON message. Here a nested field. + mqtt_name: computed.heat_index # The prometheus help text for this metric help: DHT22 heatIndex calculation # The prometheus type for this metric. Valid values are: "gauge" and "counter"