FileLog

FileLog
Zweck / Funktion
Protokollierung von Fhem-Ereignissen
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Automatisierung
Modulname	92_FileLog.pm
Ersteller	rudolfkoenig (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Das Modul FileLog dient zur Protokollierung von Ereignissen in FHEM. Die Einträge werden in eine einfache Textdatei geschrieben. Zur Protokollierung in eine Datenbank kann alternativ oder auch parallel das Modul DbLog verwendet werden.

Logdateien sind die Basis für die Erstellung von Diagrammen (SVG).

Definition

Ein FileLog wird (Details in der commandref/FileLogdefine) mittels

define <name> FileLog <filename> <regexp> [readonly]

angelegt. Dabei bezeichnet

<name>

- wie üblich - das Device

<filename>

legt den Namen der Datei auf Dateisystemebene fest

Hilfe für addRegexpPart

<regexp>

bestimmt, welche Daten in die Datei geschrieben werden. Für die Bearbeitung der regexp stellt FHEMWEB die gezeigte Hilfsfunktion zur Verfügung (siehe hierzu auch dieses Forenthema sowie den Abschnitt Sonderfälle)

[readonly]

ist optional und wird in Sonderfällen benötigt. Dieser Parameter ist seit März 2015 (Changeset 8264) verfügbar.

Attribute

Über Attribute lässt sich unter anderem auch festlegen, wie die Archivierung von Logdateien durchgeführt werden soll (Archivierungsbefehl, -pfad sowie Anzahl von Archivgenerationen).

Wenn bestimmte Zeilen nicht in die Logdatei geschrieben werden sollen, ist das Attribut ignoreRegexp hilfreich. Wenn beispielsweise alle Zeilen, die die Zeichenfolge "AbCd" oder "CdEf" enthalten nicht geloggt werden sollen, dann wäre

attr <log-name> ignoreRegexp .*AbCd.*|.*CdEf.*

eine Attributdefinition, die das ermöglicht.

Dies bezieht sich aber nur auf normale FileLog-Instanzen. Falls Events aus dem globalen FHEM-Logfile ausgeschlossen werden sollen, muss man das Attribut in global angeben. (Zusammenhang siehe #Globale Logdatei)

attr global ignoreRegexp .*AbCd.*|.*CdEf.*

Funktionen

FileLog bietet Funktionen wie reopen, absorb und get. Details dazu sind in der commandref/FileLogset zu finden.

Sofern eine Instanz vom Objekt eventTypes angelegt ist, bietet die Detailansicht eines FileLog eine komfortable Möglichkeit, die regulären Ausdrücke für den/die Filter zu bearbeiten.

Sonderfälle

Üblicherweise sind FileLog Devices dafür zuständig, aufgrund von Events die gewünschten Daten in die Logdatei zu schreiben, in Sonderfällen kann FileLog aber auch dafür verwendet werden, "bestehende" Dateien (in die aus anderen Quellen / von anderen Programme geschrieben wird) zu behandeln.

Globale Logdatei

Bis August 2021 war die Spezifikation von fakelog erforderlich bzw. möglich, um die Sonderbehandlung für diese Logdatei zu unterstützen. Mittlerweile ist das nicht mehr nötig und es wird (auch in der Beispielkonfiguration) der Wert Logfile empfohlen.

Die globale Logdatei für FHEM (üblicherweise als fhem.log bezeichnet) wird mit dem Attribut

attr global logfile <filename>

für das global-Objekt definiert, wobei für <filename> normalerweise ./log/fhem-%Y-%m.log verwendet wird.

Um das fhem.log über das Web Interface anzeigen zu können, ist ein weiterer Eintrag in der Konfiguration erforderlich, nämlich:

define Logfile FileLog <filename> fakelog Logfile

Das <filename> muss zwingend durch den gleichen Wert ersetzt werden, der in der Definition des globalen logfile Attributs verwendet wurde, weil anderenfalls unterschiedliche Dateien verwendet werden - mit dem Effekt, dass die über das Web Interface angezeigte Datei nicht die erwarteten Einträge enthält (Details dazu auch in diesem Forenbeitrag).

Logdaten aus anderen Quellen

Soll ein FileLog Device Daten aus anderen Quellen anzeigen, empfiehlt es sich, den Parameter readonly anzugeben. Damit wird vermieden, dass FHEM ebenfalls versucht, in die angegebene Datei (<filename>) zu schreiben.

Unterdrückung der addRegexpPart Hilfsfunktion

Wird bei einem FileLog Device die Anzeige der addRegxepPart Hilfsfunktion nicht gewünscht, muss als <regexp>-Parameter der gleiche Wert angegeben werden, der auch für den <name>-Parameter spezifiziert wurde (bisher (Nov. 2021) konnte dafür auch der Wert fakelog als <regexp>-Parameter verwendet werden; das wird in späteren Versionen nicht mehr unterstützt werden).

Anwendungsbeispiele

Werte auslesen

Manchmal möchte man Daten aus den Logs abrufen, ohne händisch in den Logfiles herumzuwühlen. Dies ist insbesondere auch dann hilfreich, wenn man eigene Funktionen, Notifys oder spezielle Plots entwirft, bei denen man auf Logdaten zugreifen möchte.

Grundsätzlich beschrieben ist dies in der commandref/FileLog und unterscheidet sich minimal (aber entscheidend) von der Struktur bei DbLogs.

Hier ein paar Beispiele, was man damit anstellen kann:

• get FileLog_FHT_3a32 - - 2016-10-01 2016-10-03

alle Einträge des FileLog_FHT_3a32 vom 01.10.-03.10.2016

• get FileLog_FHT_3a32 - - 2016-10-01_08:00:00 2016-10-01_16:00:00

alle Einträge des FileLog_FHT_3a32 von 8-16 Uhr am 01.10.2016

• get FileLog_FHT_3a32 - - 2016-10-01_08:00:00 2016-10-01_16:00:00 4:measured:0:

nur die Temperatur-Werte

• { ReadingsTimestamp("FHT_3a32","state","0") }

Timestamp des aktuellen state des FHT_3a32

• { OldTimestamp("FHT_3a32") }

Timestamp des letzten state des FHT_3a32

• { time_str2num(OldTimestamp("FHT_3a32")) }

Timestamp in Sekunden des letzten state des FHT_3a32

• ...

Weitere Beispiele kann man sich gut aus den SVG-Dateien ziehen.

Mehrere Werte und Dummy in einer Zeile formatiert in Logdatei schreiben

Manchmal möchte man die einzelnen Werte nicht untereinander in der Logdatei haben, sondern wie bei einer CSV-Datei in einer Zeile.

Hierzu kann man wie im Beispiel die einzelnen Readings Kesseltemperatur, Vorlauftemperatur und Rücklauftemperatur aus One-Wire-Sensoren DS18B20 und die Außentemperatur als vierten Wert aus einem Dummy über sprintf formatieren. Wer das durcht Komma oder Semikolon getrennt haben möchte, ersetzt die Leerzeichen zwischen den einzelnen Werten durch sein Wunschtrennzeichen.

attr HEIZUNG userReadings HeizDataLog {sprintf("K: %3.1f VL: %3.1f  RL: %3.1f Pr: %4.1f", ReadingsVal("OWX_28_4C966XXXXXXX","temperature", 0),ReadingsVal("OWX_28_4F9XXXXXXXXX","temperature", 0),ReadingsVal("OWX_28_FFAXXXXXXXXX","temperature", 0), (Value("Heiz_Temp_Outside")))}

Für die einzelnen Userreadings lassen sich auch unterschiedliche Intervalle angeben.

attr HEIZUNG event-min-interval HeizDataLog:300, HeizKesselTemp:20

Da im Beispiel nur Userreading HeizDataLog geschreiben werden soll, muss es bei <regexp> dementsprechend angegeben werden.

# logging
define FileLog_Heizung FileLog ./log/Heizung/Heizung_%Y_%m.log HEIZUNG:HeizDataLog.*
attr FileLog_Heizung logtype text
attr FileLog_Heizung room LogFiles,Heizung
attr FileLog_Heizung group Heizung

Das ergibt folgendes Ergebnis:

2020-09-27_19:36:57 HEIZUNG HeizDataLog: K: 66.8 VL: 60.8  RL: 35.7 Out: 18.4
2020-09-27_19:41:58 HEIZUNG HeizDataLog: K: 60.0 VL: 56.9  RL: 34.3 Out: 18.3
2020-09-27_19:46:58 HEIZUNG HeizDataLog: K: 50.2 VL: 47.9  RL: 34.4 Out: 18.2

Links

• Forenbeitrag zum Thema fhem.log / fakelog
• Forenthema zum "Deprecate" von fakelog