InfluxDBLogger: Unterschied zwischen den Versionen

Aus FHEMWiki
(Neue Seite für InfluxDBLogger)
 
K (Sichtung / Überarbeitung der letzten Änderungen)
 
(9 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 4: Zeile 4:
|ModForumArea=Unterstützende Dienste
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModTechName=93_InfluxDBLogger.pm
|ModOwner=timmib ({{Link2FU|41939|Forum}})
|ModOwner={{Link2FU|41939|timmib}}}}
}}
Genau wie mit dem Modul [[DbLog]] lassen sich mit [[InfluxDBLogger]] Daten in einer Datenbank speichern.


{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}
Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf die Beschreibung des Moduls ''DbLog'' verwiesen.
 
== Einleitung ==
Genauso, wie das Modul {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} lassen sich mit dem Modul {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} Daten in einer Datenbank speichern.
 
Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf den Artikel über das Modul [[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.
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 Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen.  
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.
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 ==
{{Randnotiz|RNTyp=y|RNText='''Alternativmodul'''
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InflixDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen.
Um Missverständnisse zu vermeiden, sei an dieser Stelle darauf hingewiesen, dass es bereits ein anderes Modul mit den Namen [[InfluxDBLog|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:
* {{Link2Forum|Topic=71551|Message=896556|LinkText=Freigabe zum Fork}}
* {{Link2Forum|Topic=71551|Message=1071675|LinkText=Wartungsstatus}}
* {{Link2Forum|Topic=71551|Message=1090783|LinkText=Start "InfluxDBLogger}}


Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InflixDB 2.0 eingegangen.
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf die (externe) Seite [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ "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 ===
== Einrichtung einer Datenbank als Docker Container ==
Voraussetzungen:
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
Zeile 31: Zeile 33:
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<pre>
<syntaxhighlight lang="YAML">
version: '2.4'
version: '2.4'
services:
services:
Zeile 62: Zeile 64:
     environment:
     environment:
       - DOCKER_INFLUXDB_INIT_MODE=setup
       - DOCKER_INFLUXDB_INIT_MODE=setup
       - DOCKER_INFLUXDB_INIT_USERNAME=myusername
       - DOCKER_INFLUXDB_INIT_USERNAME=${INFLUXDB_USERNAME}
       - DOCKER_INFLUXDB_INIT_PASSWORD=passwordpasswordpassword
       - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
       - DOCKER_INFLUXDB_INIT_ORG=myorg
       - DOCKER_INFLUXDB_INIT_ORG=${INFLUXDB_ORG}
       - DOCKER_INFLUXDB_INIT_BUCKET=mybucket
       - DOCKER_INFLUXDB_INIT_BUCKET=${INFLUXDB_BUCKET}
       - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=mytoken
       - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}
</pre>
</syntaxhighlight>


Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch bei ersten Starten erstellt.
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 <code>docker-compose.yml</code> Datei.
<syntaxhighlight lang="YAML">
INFLUXDB_USERNAME=myusername
INFLUXDB_PASSWORD=passwordpasswordpassword
INFLUXDB_ORG=myorg
INFLUXDB_BUCKET=mybucket
INFLUXDB_ADMIN_TOKEN=mytoken
</syntaxhighlight>
 
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.
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 <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.
Mit dieser Konfiguration ist FHEM über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.


Die gesamte Konfiguration kann über
Die gesamte Konfiguration kann über
 
:<code>docker-compose up -d </code>
<code>
docker-compose up -d
</code>
gestartet, bzw. über
gestartet, bzw. über
:<code>docker-compose down </code>
gestoppt werden.


<code>
Nach der Einrichtung der Datenbank wird empfohlen, die Ansprechbarkeit der Datenbank über das Webinterface unter Zuhilfenahme des vergebenen Usernamens und Passworts zu testen.
docker-compose down
<syntaxhighlight lang="HTML">
</code>
http://<ip-des-dockercontainers>:8086
gestoppt werden.
</syntaxhighlight>


=== Konfiguration des Loggers als Device ===
== Konfiguration des Loggers als Device in FHEM ==
{{Randnotiz|RNText='''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 {{Link2Forum|Topic=114860|Message=1119696|LinkText=(Forum).}}. }}
Das InfluxDBLogger Device wird dann definiert mit
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>
 
wobei bei der Verwendung der InfluxDB Version 2 folgende Attributfestlegungen notwendig werden:
wobei bei der Verwendung der InfluxDB Version 2
* 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''. 
* ''dbname'' dem vergebenen Bucket entspricht.
* Das Attribut org=myorg, das die vergebene Org festlegt.
* Das Attribut api=v2 die InfluxDV Version 2 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 <code> set <Device-name> token <mytoken></code> festlegt.
* Das Attribut org=myorg die vergebene Org festlegt.
* Das Attribut security=token die Verwendung eines Tokens festlegt.
 
Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.


Ein Beispiel für eine Konfiguration wäre:
Ein Beispiel für eine Konfiguration wäre:
<pre>
<syntaxhighlight lang="Text">
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
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 api v2
attr influxDB org myorg
attr influxDB org myorg
attr influxDB security token
attr influxDB security token
</pre>
</syntaxhighlight>
 
== 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. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})
* event-aggregator ({{Link2Forum|Topic=114860|Message=1110435|LinkText=Forum}})
 
=== Einschränkung über den zentralen <code>define</code>-Eintrag ===
Verweis auf die commandref {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} bzgl. der Attribute <code>readingInclude</code> und <code>readingInclude</code> bzw. ein Link ins Forum zu einem {{Link2Forum|Topic=114860|Message=1119696|LinkText=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 {{Link2Forum|Topic=114860|Message=1127469|LinkText=Beitrag 1}} und {{Link2Forum|Topic=114860|Message=1131301|LinkText=Beitrag 2}} im Forum).
 
Sollen nun Zustände von z.B. Fenster- oder Türkontakten geloggt werden, kommt das Attribut <code> conversion </code> zum Einsatz. Mit ihm lassen sich Zustände entsprechend in Werte umwandeln.


Ich bin mir nicht sicher, ob das Setzen eines Passwords und Users in Verbindung mit der oben beschriebenen Authentifizierungsmethodik (v2 mit Token) dazu führt, dass die Authentifizierung damit fehlschlägt.
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 ({{Link2Forum|Topic=114860|Message=1122035|LinkText=Forum}}).  


=== Finetuning des Loggings ===
Ein entsprechendes Beispiel für die Anwendung findet sich in der commandref.
{{Todo|Todo}}


==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
=== Mehrere Logging-Devices ===
{{Todo|Todo}}
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 <code>Site_name</code> und <code>value</code> in die Datenbank geschrieben. Dieses ist historisch bedingt, siehe entsprechende Hinweise im Forum zum {{Link2Forum|Topic=71551|Message=1072372|LinkText="alten" InfluxDBLog}} und im {{Link2Forum|Topic=114860|Message=1090782|LinkText="neuen" InfluxDBLogger}}.


==== Einschränkung über die jeweiligen Devices ====
Als nützlich Kombination hat sich beispielsweise die Definition folgender Attribute herausgestellt:
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] und Events zu unterdrücken:
<syntaxhighlight lang="Text">
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})
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;;}
</syntaxhighlight>
 
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 ==
== Datenbank ==
Zeile 124: Zeile 165:
* influxDB 1.x
* influxDB 1.x
* influxDB 2.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) {{Link2Forum|Topic=121454|Message=1160757|LinkText=(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:
** {{Link2Forum|Topic=114860|Message=1104495|LinkText=Beitrag von gvzdus}}
** {{Link2Forum|Topic=71551|Message=732935|LinkText=Beitrag von fervor}}
* Scripte, um Mysql Daten zu migrieren:
** {{Link2Forum|Topic=118049|Message=1129622|LinkText=addlog (import.py)}}
** {{Link2Forum|Topic=71551|Message=838940|LinkText=Skripte von kadettilac89}}
** {{Link2Forum|Topic=71551|Message=895012|LinkText=Hinweis zur Anwendung der Skripte von kadettilac89}}
** {{Link2Forum|Topic=71551|Message=895764|LinkText=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 {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} für weitere Details).
Ein entsprechendes DOIF müsste dann so aussehen:
<syntaxhighlight lang="Text">
define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always
</syntaxhighlight>
=== Device Alias mit Leerzeichen als tag ===
Über das Attribut <code>tags</code> 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 ({{Link2Forum|Topic=114860|Message=1108269|LinkText=Forum}}):
<syntaxhighlight lang="Text">
attr influxDB tags device={my $str = AttrVal($device,"alias",$device);; $str =~ s/\s/_/g;; return $str;;}
</syntaxhighlight>
== Links ==
* https://www.influxdata.com/


[[Kategorie:Logging]]
[[Kategorie:Logging]]

Aktuelle Version vom 29. November 2021, 10:33 Uhr

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.

Emblem-question-yellow.svgAlternativmodul

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:

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

Info green.pngUnterschiede 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:

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.

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