DbLog

Todo: Diese Seite muss noch vervollständigt werden. Informationen sind bisher verstreut, hauptsächlich über PGM3 dbLog und Neues Charting Frontend.

DbLog
Zweck / Funktion
Protokolliert Ereignisse in einer Datenbank
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Modulname	93_DbLog.pm
Ersteller	Tobias
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Einleitung

Mit der Zeit entstehen im fhem recht umfangreiche Log-Daten für die verschiedensten konfigurierten Devices. Die übliche Einstiegs-Konfiguration sieht vor, dass die Logs als FileLog gespeichert werden - je nach Einstellung in wenigen sehr großen oder vielen kleineren Dateien. Der Datei-basierte Zugriff ist allerdings nicht wirklick performant und kann schnell zum Flaschenhals werden (zB. bei der Darstellung von Graphen über einen längeren Zeitraum).

Alternativ kann der fhem die Log-Daten mittels DbLog in einer Datenbank speichern. Diese kann lokal als einfache SQLite- oder als zentrale Server-Datenbank (s.u.) gestaltet sein. Schon eine lokale einfache SQLite-Datenbank ist idR. deutlich performanter als File-basierte Logs.

Damit eine Datenbank-Nutzung möglich ist, müssen folgende Anpassungen gemacht werden:

1. Erstellen einer entsprechenden Datenbank
2. Konfiguration der Datenbank-Anbindung des FHEM
3. Anpassen aller (oder einzelner) Konfigurationen von FileLog nach DbLog
4. Ggf. anpassen der gplot-Konfigurationen

Konfiguration

Datenbank-Anbindung mittels db.conf

DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens db.conf werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden. Für eine MySQL-Datenbank sieht die db.conf folgendermassen aus:

%dbconfig= (
    connection => "mysql:database=fhem;host=db;port=3306",
    user => "fhemuser",
    password => "fhempassword",
);

Im Verzeichnis contrib/dblog der FHEM-Installation befindet sich eine Beispielkonfiguration mit der Syntax für jeden unterstützen Datenbanktypen.

Konfiguration als Device in fhem.cfg

Das DbLog Device wird dann in der fhem.cfg definiert mit

define <name> DbLog <configfilename> <regexp>

wobei <configfilename> dem Pfad zur zuvor angelegten db.conf entspricht. Ein Beispiel hierfür wäre:

define logdb DbLog ./db.conf .*:.*

Die Angabe von .*:.* bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Dies ist in #Finetuning des Loggings beschrieben.

Finetuning des Loggings

Bei der Konfiguration des Log-Devices werden die zu loggenden Daten definiert - in der einfachsten Form sieht das so aus: define logdb DbLog ./db.conf .*:.* . Die Angabe von .*:.* bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit sehr vielen und teils nicht benötigten Werten gefüllt wird und schnell wächst. Die Datenbank ist zwar deutlich leistungsfähiger, was große Datenmengen angeht, Datensparsamkeit kann aber schnell sinnvoll werden...

Um das Log-Aufkommen einzugrenzen gibt es 2 Ansätze:

• Einschränkung über den define-Eintrag
• Einschränkung über DbLogExclude-Einträge der jeweiligen Devices

Einschränkung über den zentralen define-Eintrag

Man kann die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste .*, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen, zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt.

Ein Beispiel um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:

define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).*

Einschränkung über die jeweiligen Devices

Man kann die zu loggenden Werte für einzelne Devices separat einschränken, ohne dies im zentralen define-Eintrag machen zu müssen. Dies kann interessant sein, wenn bspw. ein Device Fehlerwerte meldet, die uninteressant sind, oder es meldet unnötig häufig Werte - beides ist bspw. bei 1-wire-Temperatursensoren gerne der Fall.

Um das einzuschränken gibt es 2 Stellparameter, die als Attribute direkt zum jeweiligen Device konfiguriert werden:

• DbLogExclude - definiert Werte, die nicht gelogt werden sollen
• event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. commandref)

Ein konkrete Konfiguration für einen sehr gesprächigen 1-wire-Temperatursensor könnte wie folgt aussehen:

define EG_Balkon GPIO4 BUSMASTER
attr EG_Balkon DbLogExclude failures,T,85     # logge keine "failures", "T"-Werte und "85"-Werte (default-Werte, wenn keine Temperatur gelesen werden kann)
attr EG_Balkon event-on-change-reading state  # logge nur, wenn sich ein Wert ändert (wenn sich die Temperatur nicht ändert, logge das nicht)
attr EG_Balkon event-min-interval state:900   # logge spätestens alle 900sec = 15min
attr EG_Balkon event-on-update-reading .*     # logge alle Werte, die aktualisiert werden

Datenbank

Unterstützte Datenbanksysteme (Auswahl):

• Sqlite
• MySQL
• PostGreSql

Tabellen

• current
• history

Tabellenlayout

DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:

Spalte	Beschreibung (en)	Beschreibung (de)	Beispiel
TIMESTAMP	timestamp of event	Zeitstempel	2007-12-30 21:45:22
DEVICE	device name	Device-Name	Wetterstation
TYPE	device type	Device-Typ	KS300
EVENT	event specification as full string	Eventspezifikation als Text	humidity: 71 (%)
READING	name of reading extracted from event	Bezeichnung des Readings	humidity
VALUE	actual reading extracted from event	Wert des Readings	71
UNIT	unit extracted from event	Einheit des Readings	%

Die Vorlagen zur Anlage von Tabellen und Indices sind für jeden unterstützten Datenbanktyp im Verzeichnis contrib/dblog der FHEM-Installation, oder hier zu finden: Link. Das MySQL-Skript (db_create_mysql.sql) legt eine neue Datenbank, das PostGres-Skript (db_create_postgresql.sql) ein neues Schema mit Namen "fhem" an.

Bsp.: Anlegen und Nutzung einer SQLite-Datenbank

Im folgenden wird eine lokale SQLite-Datenbank auf einen Ubuntu-System angelegt (nach Quelle: http://www.tatsch-it.de/fhem-dblog/)

1. Installation von SQLite:

   sudo aptitude install sqlite3 libdbi-perl libdbd-sqlite3-perl

2. Anlegen der SQLite-Datenbank fhem.db (öffnet auch direkt eine SQL-Kommandozeile):

   sudo sqlite3 /opt/fhem/fhem.db

   In der geöffneten SQL-Kommandozeile eingeben:

   CREATE TABLE 'history' (TIMESTAMP TIMESTAMP, DEVICE varchar(32), TYPE varchar(32), EVENT varchar(512), READING varchar(32), VALUE varchar(32), UNIT varchar(32));
   CREATE TABLE 'current' (TIMESTAMP TIMESTAMP, DEVICE varchar(32), TYPE varchar(32), EVENT varchar(512), READING varchar(32), VALUE varchar(32), UNIT varchar(32));
   

   Die Kommandozeile verlässt man mit .exit.

3. Anpassen des Besitzers und der Rechte der Datenbank-Datei:

   sudo chown fhem /opt/fhem/fhem.db
   sudo chmod 666 /opt/fhem/fhem.db
   

4. Datenbank-Anbindung des FHEM konfigurieren:

   sudo nano /opt/fhem/db.conf

   Inhalt:

   %dbconfig= (
     connection => "SQLite:dbname=/opt/fhem/fhem.db",
     user => "",
     password => ""
   );
   

5. Logging des FHEM auf die Datenbank konfigurieren: (hier sind nur die Anpassungen aufgeführt)

   sudo nano /opt/fhem/fhem.conf

   ...
   attr global userattr DbLogExclude ...  # erlaubt es einzelne Einträge nicht zu loggen
   ...
   define logdb DbLog ./db.conf .*:.*     # logt alle(!) auflaufenden Events aller Konfigurationen
   ...
   

   Da durch diese define-Definition alle auflaufenden Events gelogt werden, müssen keine weiteren Anpassungen in der fhem.cfg gemacht werden. Die FileLog-Einträge sollen ruhig bestehen bleiben - dann wird in Datenbank und FileLog gelogt und man verliert keine Daten falls etwas nicht klappt. Wenn alles wie geplant läuft, können die FileLog-Einträge auskommentiert oder gelöscht werden (ebenso die Log-Dateien). Ebenso können die zu loggenden Daten später eingegrenzt werden (s. #Finetuning).

6. FHEM neu starten:

   sudo service fhem stop
   sudo service fhem start
   

7. Kontrollieren, ob Logs in die Datenbank geschrieben werden:

   sudo sqlite3 /opt/fhem/fhem.db

   In der geöffneten SQL-Kommandozeile eingeben:

   select * from history order by TIMESTAMP;       # dies gibt alle(!) Logs chronologisch aus (kann nach längerem Betrieb recht lange dauern)
   

   Die Kommandozeile verlässt man mit .exit.

8. Anpassung der glot-Dateien: siehe #gplot-Konfigurationen anpassen

Integration von DBLog in eigene Module

Bereitstellung der UNITS

Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten. Weitere Informationen siehe hier: DevelopmentModuleIntro#X_DbLog_splitFn

Links

• Beispiel das DbLog-Daten für SVG-Plots verwendet
• SVG-Plots von FileLog auf DbLog umstellen