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:
- Erstellen einer entsprechenden Datenbank
- Anpassen aller (oder einzelner) Konfigurationen von FileLog nach DbLog
- Anpassen der gplot-Konfigurationen
Definition
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.
Device
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. 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).*
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.
Anlegen einer SQLite-Datenbank
x
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