InfluxDBLogger

InfluxDBLogger
Zweck / Funktion
	Protokolliert Ereignisse in einer Datenbank
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Unterstützende Dienste
Modulname	93_InfluxDBLogger.pm
Ersteller	timmib
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Todo: Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.

Genau wie mit dem Modul DbLog lassen sich mit InfluxDBLogger Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf die Beschreibung des Moduls DbLog verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels Grafana analysiert und visualisiert werden.

Konfiguration

Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf diesen Artikel verwiesen.

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InfluxDB 2.0 eingegangen.

Einrichtung einer Datenbank

Voraussetzungen:

Eine laufende Docker-Umgebung (inkl. Docker-Compose)
Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
Die FHEM Konfiguration im Unterordner ./fhem/conf
Das folgende file docker-compose.yml im Ausgangsordner

version: '2.4'
services:

  fhem2:
    container_name: fhem2
    build: ./fhem/build
    restart: always
    ports:
      - 8083:8083
    depends_on:
      - influxdb
    volumes:
      - ./fhem/conf:/opt/fhem
    environment: 
      - FHEM_UID=1000
      - FHEM_GID=1000
      - FHEM_PERM_DIR=0750
      - FHEM_PERM_FILE=0640

  influxdb:
    image: influxdb:latest
    restart: always
    ports:
      - 8086:8086
    volumes:
      # Mount for influxdb data directory and configuration
      - ./influxdb/data:/var/lib/influxdb2:rw
      - ./influxdb/config:/etc/influxdb2:rw
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=${INFLUXDB_USERNAME}
      - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
      - DOCKER_INFLUXDB_INIT_ORG=${INFLUXDB_ORG}
      - DOCKER_INFLUXDB_INIT_BUCKET=${INFLUXDB_BUCKET}
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}

An dieser Stelle sei empfohlen, die Zugangsinformationen in eine .env Datei auszulagern, die zugriffsbeschränkt im gleichen Verzeichnis liegt, wie die docker-compose.yml Datei.

INFLUXDB_USERNAME=myusername
INFLUXDB_PASSWORD=passwordpasswordpassword
INFLUXDB_ORG=myorg
INFLUXDB_BUCKET=mybucket
INFLUXDB_ADMIN_TOKEN=mytoken

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch beim ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist FHEM über <ip-des-docker-servers>:8083 erreichbar, das Webinterface von InfluxDB über <ip-des-docker-servers>:8086 erreichbar.

Die gesamte Konfiguration kann über

docker-compose up -d

gestartet, bzw. über

docker-compose down

gestoppt werden.

Konfiguration des Loggers als Device

Das InfluxDBLogger Device wird dann definiert mit

define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec>

wobei bei der Verwendung der InfluxDB Version 2

dbname dem vergebenen Bucket entspricht.
Das Attribut api=v2 die InfluxDV Version 2 festlegt.
Das Attribut org=myorg die vergebene Org festlegt.
Das Attribut security=token die Verwendung eines Tokens festlegt.

Der Token wird über set <Device-name> token <mytoken> festlegt.

Ein Beispiel für eine Konfiguration wäre:

define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token

Finetuning des Loggings

Todo: Todo

Einschränkung über den zentralen `define`-Eintrag

Todo: Todo

Einschränkung über die jeweiligen Devices

Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei DbLog und FileLog um Events zu unterdrücken:

event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. commandref/event-on-update-reading)

Datenbank

Unterstützte Datenbanksysteme :

influxDB 1.x
influxDB 2.x

Zusätzliches

Plot-Abrisse vermeiden

Mit der Verwendung einer vollkommen neuen Datenverarbeitung, wird auch die Problematik der Plot-Abrisse an Datumsübergängen wieder zum Thema. Da das Modul logProxy direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es hier nicht eingesetzt werden.

Das Modul InfluxDBLogger besitzt allerdings selbst die notwendige Funktionalität, um die aktuellen Werte der konfigurierten Readings der konfigurierten Geräte in die Datenbank zu schreiben (Verweis auf die Commandref von InfluxDBLogger für weitere Details).

Ein entsprechendes DOIF müsste dann so aussehen:

define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always

Probleme bei der Authentifizierung

Bei der Ersteinrichtung des Moduls scheint es Konfigurations-Zustände zu geben, in denen die Authentifizierung trotz richtiger Zugangsdaten zunächst fehlschlägt (aufgetreten bei der Verwendung von Api v2) (Forum). Dabei scheint es zu helfen, das Modul zu löschen und neu einzurichten.

Da dieses nur bei der Ersteinrichtung aufzutreten scheint, konnte die Ursache bislang noch nicht genauer identifiziert werden.