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!

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.

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 nicht weiterentwickelt zu werden scheint und um das es in diesem Artikel definitiv nicht geht.

Siehe dazu auch hier:

• Freigabe zum Fork
• Wartungsstatus
• Start "InfluxDBLogger

Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf die (externe) Seite "FHEM und Grafana" verwiesen.

Allgemein

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

Einrichtung einer Datenbank als Docker Container

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}

Die Definition des oben genannten Containers "fhem2" ist für die Einrichtung der Datenbank nicht notwendig und ist an dieser Stelle nur der Vollständigkeit halber mit aufgeführt. FHEM kann auch separat installiert sein, es bietet sich aber in diesem Beispiel an, gleich in das Docker-Compose-File mit aufgenommen zu werden.

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.

Nach der Einrichtung der Datenbank wird empfohlen, die Ansprechbarkeit der Datenbank über das Webinterface unter Zuhilfenahme des vergebenen Usernamens und Passworts zu testen.

http://<ip-des-dockercontainers>:8086

Konfiguration des Loggers als Device in FHEM

Unterschiede zur Definition von DBLog Um Fehlern bei der Umstellung von DBLog auf InfluxDBLogger zu vermeiden, bitte beachten: 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, das die InfluxDB Version 2 festlegt. Hiermit wird auch das Setzen der Org mit dem folgenden Attribut notwendig, wie auch die Verknüpfung des Buckets als dbname.
• Das Attribut org=myorg, das die vergebene Org festlegt.
• Das Attribut security=token, das 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 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 Events 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.

Loggen von Zuständen

Wie eingangs erwähnt, ist die Datenbank designt, numerische Werte zu loggen. Nichtnumerische Werte lassen sich nur über den Umweg „tags“ in der Datenbank ablegen (siehe dazu auch Beitrag 1 und Beitrag 2 im Forum).

Sollen nun Zustände von z.B. Fenster- oder Türkontakten geloggt werden, kommt das Attribut conversion zum Einsatz. Mit ihm lassen sich Zustände entsprechend in Werte umwandeln.

Die jeweiligen Umwandelungen werden kommagetrennt aufgezählt. Mehrere Werte können durch ein pipe getrennt aufgezählt werden. Die Parameteraufzählung enthält dabei keine Leerzeichen. Conversions sind nicht case sensitive (Forum).

Ein entsprechendes Beispiel für die Anwendung findet sich in der commandref.

Mehrere Logging-Devices

Um eine weitere Detaillierung des Loggings umzusetzen, bei unterschiedlicher Kombination von devspec, readingInclude, readingExclude, sowie der entsprechenden Limitierung der Events, sei an dieser Stelle ebenfalls darauf verwiesen, mehrere Definitionen des Moduls kombinieren zu können, z.B. fünf separate Logger, einer für Raumsensoren, einer für die Heizung, einer für Energiezähler, einer für das Wetter und ein weiterer für alles weitere Allgemeine.

Weiteres Feinetuning

Ohne weitere Definition von Attributen werden die numerischen Daten mit Site_name und value in die Datenbank geschrieben. Dieses ist historisch bedingt, siehe entsprechende Hinweise im Forum zum "alten" InfluxDBLog und im "neuen" InfluxDBLogger.

Als nützlich Kombination hat sich beispielsweise die Definition folgender Attribute herausgestellt:

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

Dieses führt dazu, dass

• das durch Unterstriche verbundene Alias als "_Device",
• der Devicename als "_Measurement",
• der Readingsname als "_Field"

verwendet wird.

Für alternative Verwendung der entsprechenden Attribute sei ebenfalls auf die ComandRef verwiesen.

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.

• Scripte, um filelogs zu migrieren:
  • Beitrag von gvzdus
  • Beitrag von fervor
• Scripte, um Mysql Daten zu migrieren:
  • addlog (import.py)
  • Skripte von kadettilac89
  • Hinweis zur Anwendung der Skripte von kadettilac89
  • weitere Hinweis von kadettilac89

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;;}

Links

• https://www.influxdata.com/