Munin contributed plugins

#!/usr/bin/env python3

"""

=head1 NAME

feinstaubsensor - Plugin to monitor one or more environmental sensors

=head1 APPLICABLE SYSTEMS

The "Feinstaubsensor" was developed by the OK Lab Stuttgart and is part of the

Citizen Science Project "luftdaten.info" (http://luftdaten.info).

Data is retrieved via HTTP requests from the sensors itself.

=head1 CONFIGURATION

Place a configuration entry somewhere below /etc/munin/plugin-conf.d/:

      [feinstaubsensor]

      env.sensor_hosts foo=192.168.1.4 [fe80::1:2:3:4%eth0] bar=sensor2.lan

The <sensor_hosts> environment variable is a space separated list of <token>.

Each <token> can be either a <host> or a combination of label and <host> (separated by the

character "=").

A <host> may be an IPv4 address, an IPv6 address (enclosed in square brackets) or a name to be

resolved via DNS.

Examples for <token>:

=over 4

=item 192.168.1.4

=item foo=192.168.1.4

=item [fe80::1a:2b:3c:cafe]

=item bar=[fe80::1a:2b:3c:cafe]

=item feinstaubsensor-12345.local

=item baz=feinstaubsensor-12345.local

=back

=head1 AUTHOR

Lars Kruse <devel@sumpfralle.de>

=head1 LICENSE

GNU General Public License v3.0 or later

SPDX-License-Identifier: GPL-3.0-or-later

=head1 MAGIC MARKERS

  #%# family=manual

=cut

"""

import collections

import functools

import json

import os

import re

import sys

import urllib.request

graphs = [

    {

        "name": "wireless_signal",

        "graph_title": "Feinstaub Wifi Signal",

        "graph_vlabel": "%",

        "graph_args": "-l 0",

        "graph_info": "Wifi signal strength",

        "fields": [

            {"api_key": "signal"},

        ],

        "value_type": "GAUGE",

    }, {

        "name": "feinstaub_samples",

        "graph_title": "Feinstaub Sample Count",

        "graph_vlabel": "#",

        "graph_info": "Number of samples since bootup",

        "fields": [

            {"api_key": "samples"},

        ],

        "value_type": "DERIVE",

    }, {

        "name": "feinstaub_humidity",

        "graph_title": "Feinstaub Humidity",

        "graph_vlabel": "% humidity",

        "graph_info": "Weather information: air humidity",

        "fields": [

            {"api_key": "humidity"},

            {"api_key": "BME280_humidity", "info": "BME280", "field_suffix": "bme280"},

        ],

        "value_type": "GAUGE",

    }, {

        "name": "feinstaub_temperature",

        "graph_title": "Feinstaub Temperature",

        "graph_vlabel": "°C",

        "graph_info": "Weather information: temperature",

        "fields": [

            {"api_key": "temperature"},

            {"api_key": "BME280_temperature", "info": "BME280", "field_suffix": "bme280"},

        ],

        "value_type": "GAUGE",

    }, {

        "name": "feinstaub_pressure",

        "graph_title": "Feinstaub Atmospheric Pressure",

        "graph_vlabel": "Pascal",

        "graph_info": "Weather information: atmospheric pressure",

        "fields": [

            {"api_key": "BME280_pressure"},

        ],

        "value_type": "GAUGE",

    }, {

        "name": "feinstaub_particles_pm10",

        "graph_title": "Feinstaub Particle Measurement P10",

        "graph_vlabel": "µg / m³",

        "graph_info": "Concentration of particles with a size between 2.5µm and 10µm",

        "fields": [

            {"api_key": "SDS_P1"},

        ],

        "value_type": "GAUGE",

    }, {

        "name": "feinstaub_particles_pm2_5",

        "graph_title": "Feinstaub Particle Measurement P2.5",

        "graph_vlabel": "µg / m³",

        "graph_info": "Concentration of particles with a size up to 2.5µm",

        "fields": [

            {"api_key": "SDS_P2"},

        ],

        "value_type": "GAUGE",

    }]

SensorHost = collections.namedtuple("SensorHost", ("host", "label", "fieldname"))

def clean_fieldname(text):

    if text == "root":

        # "root" is a magic (forbidden) word

        return "_root"

    else:

        return re.sub(r"(^[^A-Za-z_]|[^A-Za-z0-9_])", "_", text)

def parse_sensor_hosts_from_description(hosts_description):

    """ parse sensor list from the environment variable 'sensor_hosts' and retrieve their data """

    sensors = []

    for token in hosts_description.split():

        if "=" in token:

            label, host = token.strip().split("=", 1)

        else:

            host = token.strip()

            label = host

        fieldname = clean_fieldname("value_" + host)

        sensors.append(SensorHost(host, label, fieldname))

    sensors.sort(key=lambda item: item.fieldname)

    return sensors

@functools.lru_cache()

def get_sensor_data(host):

    """ request the data from a sensor and return a dict (value_type -> value)

    The result is cached - thus we do not need to take care for efficiency.

    Example dataset returned by the sensor:

        {"software_version": "NRZ-2017-099", "age":"88", "sensordatavalues":[

        {"value_type":"SDS_P1","value":"27.37"},{"value_type":"SDS_P2","value":"13.53"},

        {"value_type":"temperature","value":"23.70"},{"value_type":"humidity","value":"69.20"},

        {"value_type":"BME280_temperature","value":"9.76"},

        {"value_type":"BME280_humidity","value":"79.29"},

        {"value_type":"BME280_pressure","value":"100781.03"},

        {"value_type":"samples","value":"626964"},{"value_type":"min_micro","value":"225"},

        {"value_type":"max_micro","value":"887641"},{"value_type":"signal","value":"-47"}]}

    """

    try:

        with urllib.request.urlopen("http://{}/data.json".format(host)) as request:

            body = request.read()

    except IOError as exc:

        print("Failed to retrieve data from '{}': {}".format(host, exc), file=sys.stderr)

        return None

    try:

        data = json.loads(body.decode("utf-8"))

    except ValueError as exc:

        print("Failed to parse data from '{}': {}".format(host, exc), file=sys.stderr)

        return None

    return {item["value_type"]: item["value"] for item in data["sensordatavalues"]}

def print_graph_section(graph_description, hosts, include_config, include_values):

    # retrieve the data and omit ony output, if the relevant key is missing

    results = []

    for host_info in hosts:

        data = get_sensor_data(host_info.host)

        if data:

            for data_field in graph_description["fields"]:

                for dataset in data["sensordatavalues"]:

                    if dataset["value_type"] == data_field["api_key"]:

                        results.append((host_info, data_field, dataset["value"]))

                        break

                else:

                    # We cannot distinguish between fields that are not supported by the sensor

                    # (most are optional) and missing data. Thus we cannot handle online/offline

                    # sensor data fields, too.

                    pass

    # skip this multigraph, if no host contained this data field

    if results:

        print("multigraph {}".format(graph_description["name"]))

        if include_config:

            # graph configuration

            print("graph_category sensors")

            for key in ("graph_title", "graph_vlabel", "graph_args", "graph_info"):

                if key in graph_description:

                    print("{} {}".format(key, graph_description[key]))

            for host_info, data_field, value in results:

                try:

                    label = "{} ({})".format(host_info.label, data_field["info"])

                except KeyError:

                    label = host_info.label

                print("{}.label {}".format(host_info.fieldname, label))

                print("{}.type {}".format(host_info.fieldname, graph_description["value_type"]))

        if include_values:

            for host_info, data_field, value in results:

                print("{}.value {}".format(host_info.fieldname, value))

        print()

action = sys.argv[1] if (len(sys.argv) > 1) else ""

sensor_hosts = parse_sensor_hosts_from_description(os.getenv("sensor_hosts", ""))

if not sensor_hosts:

    print("ERROR: undefined or empty environment variable 'sensor_hosts'.", file=sys.stderr)

    sys.exit(1)

if action == "config":

    is_dirty_config = (os.getenv("MUNIN_CAP_DIRTYCONFIG") == "1")

    for graph in graphs:

        print_graph_section(graph, sensor_hosts, True, is_dirty_config)

elif action == "":

    for graph in graphs:

        print_graph_section(graph, sensor_hosts, False, True)

else:

    print("ERROR: unsupported action requested ('{}')".format(action), file=sys.stderr)

    sys.exit(2)