README

This is a Prometheus monitoring exporter for the YoctoPuce USB sensors.

The project includes:
 - yocto_exporter: the actual code
 - yotco_exporter.service: a systemd unit
 - scrape_to_munin: a munin sensor that scrapes yocto_exporter


requirements:
  - Python3 Prometheus client library (Debian: python3-prometheus-client)
  - YoctoPuce Python libraries: https://www.yoctopuce.com/EN/libraries.php
    expected to be installed at: /opt/yoctolib_python/Sources
    - easiest way:
      cd opt ; git clone http://github.com/yoctopuce/yoctolib_python

automatic startup (install & enable the usual way as required):
  - systemd unit: yocto_exporter.service
  - sysvinit init script: yocto_exporter.init

commandline arguments:

yocto_exporter --help
usage: yocto_exporter [-h] [--port PORT] [--bind_ip BIND_IP] [--dump_sensors]
                      [--debug]

optional arguments:
  -h, --help         show this help message and exit
  --port PORT        port to bind to (default 8000)
  --bind_ip BIND_IP  IP to bind to (default 0.0.0.0)
  --dump_sensors     dump sensor info and exit
  --debug            dump sensor info and continue
  --sensor_log       log sensor access

This exporter iterates:
  - over all USB connected YoctoPuce sensor modules it finds
    - over all sensors connected to the module
while ignoring sensor 0, as this is the datalogger which we don't care about.

Currently, the following sensor types are supported:
- module internal:
  - usb_current: USB module current consumption
  - luminosity: USB module beacon luminosity
- module sensors:
  - pressure: ambient air pressure
  - temperature: module temperature
  - humidity: ambient air humidity
  - light: light sensor
  - co2: CO2 sensor
- exporter internals
  - request_processing_seconds: time spent processing requests
  - sensor_read_time: time spent in the last sensor reading loop
  - sensor_read_passes: numbers of sensor reading loop iterations
  - yapi_exceptions: number of exception from YAPI during sensor read loop


Implementation details:

Typically, a Prometheus exporters aquires the data it exports when it is
asked for it (while being scraped).

Except .. this approach isn't very stable, as I found. When scraping at a
5s interval, there is a noticeable number of failed scrapes, either because
it takes too long to read all the sensors in realtime or because there are
transient errors from the YAPI.

So this exporter decouples scraping and data collection: After the http
server has been started, in an endless loop, every 4s the data collector
loop kicks off and updates the exported variables. Exceptions thrown by
the YAPI get noted, counted and then dealt with by restarting
(unregister, sleep a few sec, re-register) the YAPI interface.

If there are sensors missing, then this is due to me not having access
to those sensors/modules to test. Happy to extend the sensor/module
coverage ...