{{tag>software logiciel mqtt prometheus exporter todo}}


====== mqtt2prometheus : Prometheus exporter ======

**mqtt2prometheus** est un "exporter" pour Prometheus. Il souscrit au Broker MQTT, s'abonne aux topics et les rends disponibles pour le scapring de Prometheus.


===== Connexion au Broker MQTT =====

Le fichier de configuration ''/config.yml'' permet de définir les paramètres de connexion au Broker MQTT.

<code yaml>
mqtt:
  # The MQTT broker to connect to
  server: tcp://broker:1883
  # Optional: Username and Password for authenticating with the MQTT Server
  # user: bob
  # password: happylittleclouds
  # Optional: for TLS client certificates
  # ca_cert: certs/AmazonRootCA1.pem
  # client_cert: certs/xxxxx-certificate.pem.crt
  # client_key: certs/xxxxx-private.pem.key
  # Optional: Used to specify ClientID. The default is <hostname>-<pid>
  client_id: mqtt_exporter
  # The Topic path to subscribe to. Be aware that you have to specify the wildcard.
  topic_path: '#'
  # 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<deviceid>.*)/.*"
  # device_id_regex: "(.*/)?(?P<deviceid>.*)"
  # The MQTT QoS level
  qos: 0
</code>

L'exporteur mqtt2prometheus souscrit au broker. Les journaux du broker permettent de tracer la souscription:

<code bash>
docker-compose logs mosquitto 
Attaching to synopush_mqtt_broker
synopush_mqtt_broker | 1671561436: mosquitto version 2.0.14 starting
synopush_mqtt_broker | 1671561436: Config loaded from /mosquitto/config/mosquitto.conf.
synopush_mqtt_broker | 1671561436: Opening ipv4 listen socket on port 1883.
synopush_mqtt_broker | 1671561436: Opening ipv6 listen socket on port 1883.
synopush_mqtt_broker | 1671561436: mosquitto version 2.0.14 running
synopush_mqtt_broker | 1671561437: New connection from 172.19.0.5:49754 on port 1883.
synopush_mqtt_broker | 1671561437: New client connected from 172.19.0.5:49754 as mqtt_exporter (p2, c1, k30).
. . .
</code>

Les logs indiquent bien qu'un client nommé "mqtt_exporter" s'est connecté.

===== Exposition des métriques =====

Les métriques ne seront plus présentées à Prometheus si les valeurs ne sont pas rafraîchies par la réception de message MQTT en deçà de la valeur de **timeout**.
<code yaml>
cache:
  # Timeout. Each received metric will be presented for this time if no update is send via MQTT.
  # Set the timeout to -1 to disable the deletion of metrics from the cache. The exporter presents the ingest timestamp
  # to prometheus.
  timeout: 24h
</code>



Le fichier de configuration permet de définir/sélectionner les métriques à présenter à Prometheus

<code yaml>
# Liste des métriques valides. Seules les métriques listées ci-dessous seront exportées.
metrics:
    # Nom de la métrique exposée pour Prometheus
  - prom_name: temperature_celsius
    # Correspondance avec la valeur du message JSON MQTT
    mqtt_name: t
    # Description de la métrique
    help: temperature ambiante (°C)
    # Type de la métrique Prometheus. Valeurs possibles: "gauge" ou "counter"
    type: gauge
    # Nom de la métrique exposée pour Prometheus
  - prom_name: humidity_ratio
    # Correspondance avec la valeur du message JSON MQTT
    mqtt_name: u
    # Description de la métrique
    help: Humidité relative (%)
    # Type de la métrique Prometheus. Valeurs possibles: "gauge" ou "counter"
    type: gauge
</code>

===== Scraping par Prometheus =====

Par défaut mqtt2prometheus écoute sur le port **9641**. Vérifier que depuis le conteneur Prometheus, on peut atteindre l'exporteur:

<code bash>
# ouvre un shell interactif dans le conteneur prometheus
docker-compose exec -u root prometheus /bin/sh

# Récupère et affiche les métriques exposés par mqtt2prometheus dans la console
wget -O - "http://mqtt2prometheus:9641/metrics"
</code>

===== logs =====

S'appuie sur Uber Zap pour la génération des logs. Les niveaux de logs disponibles sont ceux proposés par bibliothèque.


^ debug     | Journaux verbeux le plus souvent désactivé en production.                           |
^ info      | Priorité de journalisation par défaut.                                              |
^ warn      | Priorité plus haute que info mais ne nécessitant pas une intervention particulière. |
^ error     | Événements de haute priorité nécessitant une correction. Une application s’exécutant normalement ne doit pas générer d'erreur.                                                         |
^ dpanic    | Erreurs importantes provoquant l'arrêt du logger.                                   |
^ panic     | Journalisation de l'erreur et panic                                                 |
^ fatal     | Journalisation de l'événement et appel de os.Exit(1)                                |

===== Références =====

  * https://github.com/hikhvar/mqtt2prometheus
  * https://medium.com/codex/level-based-logging-in-go-with-uber-zap-a8a90aa40672
  * https://frederic-hemberger.de/notes/prometheus/monitoring-temperature-and-humidity-with-mqtt/