InfluxDBLogger

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

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!

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

Alternativmodul

Um Missverständnisse zu vermeiden sei an dieser Stelle darauf hingewiesen, dass es bereits ein anderes Modul mit den Namen 93_InfluxDBLog für die Anbindung an eine InfluxDB gibt, das zu diesem Zeitpunkt (11/2021) allerdings scheint, nicht weiterentwickelt zu werden und um das es in diesem Artikel definitiv nicht geht. (Forum)

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

Unterschiede zur Definition von DBLog Um Fehlern bei der Umstellung von DBLog auf InfluxDBLogger zu vermeiden, anders als bei DBLog werden bei der Definition nur die Devices definiert und nicht zusätzlich auch die Readings (Forum)..

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 folgende Attributfestlegungen notwendig werden:

• Das Attribut api=v2, dass die InfluxDV Version 2 festlegt. Hiermit wird auch das Setzten der Org mit dem folgenden Attribut notwendig, wie auch die Verknüpfung des Buckets als dbname.
• Das Attribut org=myorg, dass die vergebene Org festlegt.
• Das Attribut security=token, dass die Verwendung eines Tokens festlegt. Hiermit ist ebenfalls das Definieren eines Users als Attribut und das Setzen eines Passwortes überflüssig. 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

Bei der Optimierung ist der Einschränkung an der Quelle (am jeweiligen Device) immer der Vorzug zu geben vor der der Einschränkung an zentraler Stelle um unnötig entstehende Daten zu vermeiden. Allerdings kann es Fälle geben, in denen eine Whitelist oder Blacklist bzgl. der Definition, welche der entstandenen Event geloggt werden sollen, sinnvoll sein kann.

Dieses kann exklusiv oder zusätzlich zu den im Folgenden genannten Einschränkungen über die jeweiligen Devices an zentraler Stelle geschehen.

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)
• event-aggregator

(Forum)

Einschränkung über den zentralen define-Eintrag

Verweis auf die commandref InfluxDBLogger bzgl. der Attribute readingInclude und readingInclude bzw. ein Link ins Forum zu einem Beispiel für dessen Verwendung (Forum).

Datenbank

Unterstützte Datenbanksysteme :

• influxDB 1.x
• influxDB 2.x

Zusätzliches

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.

Migration von Altdaten

Zwei Hinweise ins Forum bzgl.

• Ein Script, um filelogs zu migrieren (Forum).
• Ein Script, um Mysql Daten zu migrieren (Forum)

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

Device Alias mit Leerzeichen als tag

Über das Attribut tags lassen sich weitere Informationen den Daten hinzufügen wie z.B. die vergebenen Aliase der Devices. Haben diese allerdings Leerzeichen, schlägt das logging fehl. Eine Ersetzung der Leerzeichen in Aliasen und der Verwendung als tag kann über diese Attributdefinition realisiert werden (Forum):

attr influxDB tags device={my $str = AttrVal($device,"alias",$device);; $str =~ s/\s/_/g;; return $str;;}