DbRep - Reporting und Management von DbLog-Datenbankinhalten
| DbRep | |
|---|---|
| Zweck / Funktion | |
| Reporting und Management von DbLog-Datenbankinhalten | |
| Allgemein | |
| Typ | Hilfsmodul |
| Details | |
| Dokumentation | EN / DE |
| Support (Forum) | Sonstiges |
| Modulname | 93_DbRep.pm |
| Ersteller | nasseeder1 (Forum: DS_Starter) |
| Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref! | |
Zweck und Einsatz des Moduls
Zweck des Moduls ist es, den Inhalt von DbLog-Datenbanken nach bestimmten Kriterien zu durchsuchen, zu managen, das Ergebnis hinsichtlich verschiedener Aggregationen auszuwerten und als Readings darzustellen. Die Abgrenzung der zu berücksichtigenden Datenbankinhalte erfolgt durch die Angabe von Device, Reading und die Zeitgrenzen für Auswertungsbeginn bzw. Auswertungsende.
Alle Datenbankoperationen werden nichtblockierend ausgeführt. Die Ausführungszeit der (SQL)-Hintergrundoperationen kann optional ebenfalls als Reading bereitgestellt werden (siehe Attribute). Alle vorhandenen Readings werden vor einer neuen Operation gelöscht. Durch das Attribut "readingPreventFromDel" kann eine Komma separierte Liste von Readings angegeben werden die nicht gelöscht werden sollen.
Zur Zeit werden folgende Operationen unterstützt:
- Selektion aller Datensätze innerhalb einstellbarer Zeitgrenzen.
- Darstellung der Datensätze einer Device/Reading-Kombination innerhalb einstellbarer Zeitgrenzen.
- Selektion der Datensätze unter Verwendung von dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt.
- Berechnung der Anzahl von Datensätzen einer Device/Reading-Kombination unter Berücksichtigung von Zeitgrenzen und verschiedenen Aggregationen.
- Die Berechnung von Summen- , Differenz- , Maximum- , Minimum- und Durchschnittswerten von numerischen Readings in Zeitgrenzen und verschiedenen Aggregationen.
- Löschung von Datensätzen. Die Eingrenzung der Löschung kann durch Device und/oder Reading sowie fixer oder dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt erfolgen.
- Export von Datensätzen in ein File im CSV-Format.
- Import von Datensätzen aus File im CSV-Format.
- Umbenennen von Device-Namen in Datenbanksätzen
- automatisches Umbenennen (Autorename) von Device-Namen in Datenbanksätzen und DbRep-Definitionen nach FHEM "rename" Befehl (siehe DbRep-Agent)
Zur Aktivierung der Funktion "Autorename" wird dem definierten DbRep-Device mit dem Attribut "role" die Rolle "Agent" zugewiesen. Die Standardrolle nach Definition ist "Client". Mehr ist dazu im Abschnitt DbRep-Agent beschrieben.
FHEM-Forum: Modul 93_DbRep - Reporting und Management von Datenbankinhalten (DbLog)
Voraussetzungen und Abgrenzungen
Das Modul setzt den Einsatz einer oder mehrerer DBLog-Instanzen voraus (bisher getestet mit MySQL und SQLite). Es werden die Zugangsdaten dieser Datenbankdefinition aus der Konfiguration des entsprechenden DbLog-Device genutzt. Es werden nur Inhalte der Tabelle "history" berücksichtigt.
Überblick welche anderen Perl-Module DbRep verwendet:
POSIX Time::HiRes Time::Local Scalar::Util DBI Blocking (FHEM-Modul)
Aus Performancegründen sollte zusätzlich folgender Index erstellt werden:
ALTER TABLE 'fhem'.'history' ADD INDEX `Reading_Time_Idx` (`READING`, `TIMESTAMP`) USING BTREE; oder: CREATE INDEX Reading_Time_Idx ON `fhem`.`history` (READING, TIMESTAMP);
Wenn nicht vorhanden das DBI-Modul installieren (z.B. unter Debian):
sudo apt-get install libdbi-perl
Definition
define <name> DbRep <Name der DbLog-instanz>
- <Name der DbLog-Instanz>: Es wird der Name der auszuwertenden DBLog-Datenbankdefinition angegeben, NICHT die Datenbank selbst.
Set
Zur Zeit gibt es folgende "Set"-Kommandos. Über sie werden die Auswertungen angestoßen und definieren selbst die Auswertungsvariante. Nach welchen Kriterien die Datenbankinhalte durchsucht werden und die Aggregation erfolgt, wird durch Atribute gesteuert.
- averageValue : berechnet den Durchschnittswert der Readingwerte (DB-Spalte "VALUE") in den gegebenen Zeitgrenzen ( siehe Attribute). Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein.
- countEntries : liefert die Anzahl der DB-Einträge in den gegebenen Zeitgrenzen ( siehe Attribute). Sind die Timestamps nicht gesetzt werden alle Einträge gezählt. Beschränkungen durch die Attribute Device bzw. Reading gehen in die Selektion mit ein.
- deviceRename : benennt den Namen eines Device innerhalb der angeschlossenen Datenbank (Internal DATABASE) um. Der Gerätename wird immer in der gesamten Datenbank umgesetzt. Eventuell gesetzte Zeitgrenzen oder Beschränkungen durch die Attribute Device bzw. Reading werden nicht berücksichtigt.
Eingabeformat: set <name> deviceRename <alter Devicename>,<neuer Devicename>
# Die Anzahl der umbenannten Device-Datensätze wird im Reading "device_renamed" ausgegeben.
# Wird der umzubenennende Gerätename in der Datenbank nicht gefunden, wird eine WARNUNG im Reading "device_not_renamed"
ausgegeben.
# Entsprechende Einträge erfolgen auch im Logfile mit verbose=3
- exportToFile : exportiert DB-Einträge im CSV-Format in den gegebenen Zeitgrenzen. Einschränkungen durch die Attribute Device bzw. Reading gehen in die Selektion mit ein. Der Filename wird durch das Attribut "expimpfile" bestimmt.
- fetchrows : liefert alle DB-Einträge in den gegebenen Zeitgrenzen ( siehe Attribute). Eine evtl. gesetzte Aggregation wird nicht berücksichtigt.
- insert : Manuelles Einfügen eines Datensatzes in die Tabelle "history". Obligatorisch sind Eingabewerte für Datum, Zeit und Value. Die Werte für die DB-Felder Type bzw. Event werden mit "manual" gefüllt, sowie die Werte für Device, Reading aus den gesetzten Attributen genommen.
Format: Datum,Zeit,Value,[Unit]
# Unit ist optional, Attribute "reading" und "device" müssen gesetzt sein.
# Soll "Value=0" eingefügt werden, ist "Value = 0.0" zu verwenden.
#
Beispiel: 2016-08-01,23:00:09,TestValue,TestUnit
# die Feldlänge ist maximal 32 Zeichen lang, es sind KEINE Leerzeichen im Feldwert erlaubt !
#
Hinweis:
Bei der Eingabe ist darauf zu achten dass im beabsichtigten Aggregationszeitraum (Tag, Woche, Monat, etc.) MINDESTENS
zwei Datensätze für die Funktion diffValue zur Verfügung stehen. Ansonsten kann keine Differenz berechnet werden und
diffValue gibt in diesem Fall "0" in der betroffenen Periode aus !
- importFromFile : importiert Datensätze im CSV-Format aus einem File in die Datenbank. Der Filename wird durch das Attribut "expimpfile" bestimmt.
Datensatzformat: "TIMESTAMP","DEVICE","TYPE","EVENT","READING","VALUE","UNIT"
# Die Felder "TIMESTAMP","DEVICE", "READING" müssen gesetzt sein. Alle anderen Felder sind optional. Der Fileinhalt
wird als Transaktion importiert, d.h. es wird der Inhalt des gesamten Files oder, im Fehlerfall, kein Datensatz des
Files importiert. Wird eine umfangreiche Datei mit vielen Datensätzen importiert sollte KEIN verbose=5 gesetzt werden.
Es würden sehr viele Sätze in das Logfile geschrieben werden was FHEM blockieren oder überlasten könnte !
Beispiel: "2016-09-25 08:53:56","STP_5000","SMAUTILS","etotal: 11859.573","etotal","11859.573",""
- sumValue : berechnet die Summenwerte eines Readingwertes (DB-Spalte "VALUE") in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading im Attribut "reading" angegeben sein. Diese Funktion ist sinnvoll wenn fortlaufend Wertedifferenzen eines Readings in die Datenbank geschrieben werden.
- maxValue : berechnet den Maximalwert eines Readingwertes (DB-Spalte "VALUE") in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein. Die Auswertung enthält den Zeitstempel des ermittelten Maximumwertes innerhalb der Aggregation bzw. Zeitgrenzen. Im Reading wird der Zeitstempel des letzten Auftretens vom Maximalwert ausgegeben falls dieser Wert im Intervall mehrfach erreicht wird.
- minValue : berechnet den Minimalwert eines Readingwertes (DB-Spalte "VALUE") in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein. Die Auswertung enthält den Zeitstempel des ermittelten Minimumwertes innerhalb der Aggregation bzw. Zeitgrenzen. Im Reading wird der Zeitstempel des ersten Auftretens vom Minimalwert ausgegeben falls dieser Wert im Intervall mehrfach erreicht wird.
- diffValue : berechnet den Differenzwert eines Readingwertes (DB-Spalte "Value") in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading im Attribut "reading" angegeben sein. Diese Funktion ist z.B. zur Auswertung von Eventloggings sinnvoll, deren Werte sich fortlaufend erhöhen und keine Wertdifferenzen wegschreiben. Es wird immer die Differenz aus dem Value-Wert des ersten verfügbaren Datensatzes und dem Value-Wert des letzten verfügbaren Datensatzes innerhalb der angegebenen Zeitgrenzen/Aggregation gebildet. Dabei wird ein Zählerüberlauf (Neubeginn bei 0) mit berücksichtigt (vergleiche Attribut "diffAccept"). Wird in einer auszuwertenden Zeit- bzw. Aggregationsperiode nur ein Datensatz gefunden, kann keine Differenz berechnet werden und das Reading "not_enough_data_in_period" mit einer Liste der betroffenen Perioden wird erzeugt.
Hinweis:
Im Auswertungs- bzw. Aggregationszeitraum (Tag, Woche, Monat, etc.) MÜSSEN dem Modul pro Periode MINDESTENS zwei Datensätze zur
Verfügung stehen. Ansonsten kann keine Differenz berechnet werden und diffValue ergibt in diesem Fall "0" !
- delEntries : löscht alle oder die durch die Attribute Device und/oder Reading definierten Datenbankeinträge. Die Eingrenzung über Timestamps erfolgt folgendermaßen:
"timestamp_begin" gesetzt: gelöscht werden DB-Einträge '''ab''' diesem Zeitpunkt bis zum aktuellen Datum/Zeit
"timestamp_end" gesetzt : gelöscht werden DB-Einträge '''bis''' bis zu diesem Zeitpunkt
beide Timestamps gesetzt : gelöscht werden DB-Einträge '''zwischen''' diesen Zeitpunkten
Aus Sicherheitsgründen muss das Attribut "allowDeletion" gesetzt sein um die Löschfunktion freizuschalten.
Für alle Auswertungsvarianten gilt:
Zusätzlich zu dem auszuwertenden Reading kann das Device mit angegeben werden um das Reporting nach diesen Kriterien einzuschränken. Sind keine Zeitgrenzen-Attribute angegeben, wird '1970-01-01 01:00:00' und das aktuelle Datum/Zeit als Zeitgrenze genutzt.
Attribute
Über die modulspezifischen Attribute wird die Abgrenzung der Auswertung und die Aggregation der Werte gesteuert.
Hinweis zur SQL-Wildcard Verwendung:
Innerhalb der Attribut-Werte für "device" und "reading" können SQL-Wildcards, "%" und "_", angegeben werden. Dabei ist "%" = beliebig viele Zeichen und "_" = ein Zeichen.
Dies gilt für alle Funktionen außer "insert", "deviceRename" und "delEntries".
Die Funktion "insert" erlaubt nicht dass die genannten Attribute das Wildcard "%" enthalten, "_" wird als normales Zeichen gewertet.
Die Löschfunktion "delEntries" wertet die Zeichen "$", "_" NICHT als Wildcards und löscht nur Device/Readings die exakt wie in den Attributen angegeben in der DB gespeichert sind.
In den Readings wird das Wildcardzeichen "%" durch "/" ersetzt um die Regeln für erlaubte Zeichen in Readings einzuhalten.
- aggregation : Zusammenfassung der Device/Reading-Selektionen in Stunden,Tages,Kalenderwochen,Kalendermonaten oder "no". Liefert z.B. die Anzahl der DB-Einträge am Tag (countEntries), Summation von Differenzwerten eines Readings (sumValue), usw. Mit Aggregation "no" (default) erfolgt keine Zusammenfassung in einem Zeitraum sondern die Ausgabe ergibt alle Werte eines Device/Readings zwischen den definierten Zeiträumen.
- allowDeletion : schaltet die Löschfunktion des Moduls frei
- device : Abgrenzung der DB-Selektionen auf ein bestimmtes Device
- diffAccept : gilt für Funktion diffValue. diffAccept legt fest bis zu welchem Schwellenwert eine berechnete positive Werte-Differenz zwischen zwei unmittelbar aufeinander folgenden Datensätzen akzeptiert werden soll (Standard ist 20). Damit werden fehlerhafte DB-Einträge mit einem unverhältnismäßig hohen Differenzwert von der Berechnung ausgeschlossen und verfälschen nicht das Ergebnis. Sollten Schwellenwertüberschreitungen vorkommen, wird das Reading "diff-overrun_limit-<diffLimit>" erstellt. (<diffLimit> wird dabei durch den aktuellen Attributwert ersetzt) Es enthält eine Liste der relevanten Wertepaare. Mit verbose 3 werden diese Datensätze ebenfalls im Logfile protokolliert.
Beispiel Ausgabe im Logfile beim Überschreiten von diffAccept=10: # DbRep Rep.STP5000.etotal -> data ignored while calc diffValue due to threshold overrun (diffAccept = 10): 2016-04-09 08:50:50 0.0340 -> 2016-04-09 12:42:01 13.3440 # # Der erste Datensatz mit einem Wert von 0.0340 ist untypisch gering zum nächsten Wert 13.3440 und führt zu einem zu hohen Differenzwert. # Es ist zu entscheiden ob der Datensatz gelöscht, ignoriert, oder das Attribut diffAccept angepasst werden sollte.
- disable : deaktiviert das Modul
- expimpfile : Pfad/Dateiname für Export/Import in/aus einem File.
- reading : Abgrenzung der DB-Selektionen auf ein bestimmtes Reading
- readingNameMap : der Name des ausgewerteten Readings wird mit diesem String für die Anzeige überschrieben
- readingPreventFromDel : Komma separierte Liste von Readings die vor einer neuen Operation nicht gelöscht werden sollen
- role : die Rolle des DbRep-Device. Standard ist "Client". Die Rolle "Agent" ist im Abschnitt DbRep-Agent beschrieben.
- showproctime : wenn gesetzt, zeigt das Reading "sql_processing_time" die benötigte Abarbeitungszeit (in Sekunden) für die SQL-Ausführung der durchgeführten Funktion. Dabei wird nicht ein einzelnes SQl-Statement, sondern die Summe aller notwendigen SQL-Abfragen innerhalb der jeweiligen Funktion betrachtet.
- timestamp_begin : der zeitliche Beginn für die Datenselektion (*)
- timestamp_end : das zeitliche Ende für die Datenselektion. Wenn nicht gesetzt wird immer die aktuelle Datum/Zeit-Kombi für das Ende der Selektion eingesetzt. (*)
- timeDiffToNow : der Selektionsbeginn wird auf den Zeitpunkt "aktuelle Zeit - timeDiffToNow" gesetzt (in Sekunden). Dadurch werden immer die letzten <timeDiffToNow>-Sekunden berücksichtigt (z.b. 86400 wenn immer die letzten 24 Stunden in die Selektion eingehen sollen). Die Timestampermittlung erfolgt dynamisch zum Ausführungszeitpunkt.
- timeOlderThan : das Selektionsende wird auf den Zeitpunkt "aktuelle Zeit - timeOlderThan" gesetzt (in Sekunden). Dadurch werden alle Datensätze bis zu dem Zeitpunkt "<aktuelle Zeit> - <timeOlderThan>" berücksichtigt (z.b. wenn auf 86400 gesetzt werden alle Datensätze die älter als ein Tag sind berücksichtigt). Die Timestampermittlung erfolgt dynamisch zum Ausführungszeitpunkt.
- timeout : das Attribut setzt den Timeout-Wert für die Blocking-Call Routinen (Standard 60) in Sekunden
(*) Das Format von Timestamp ist wie in DbLog "YYYY-MM-DD HH:MM:SS". Für die Attribute "timestamp_begin", "timestamp_end" kann ebenso eine der folgenden Eingaben verwendet werden:
current_year_begin : belegt das timestamp-Attribut dynamisch mit "<aktuelles Jahr>-01-01 00:00:00"
current_year_end : belegt das timestamp-Attribut dynamisch mit "<aktuelles Jahr>-12-31 23:59:59"
previous_year_begin : belegt das timestamp-Attribut dynamisch mit "<voriges Jahr>-01-01 00:00:00"
previous_year_end : belegt das timestamp-Attribut dynamisch mit "<voriges Jahr>-12-31 23:59:59"
Natürlich sollte man immer darauf achten dass timestamp_begin < timestamp_end ist.
Hinweis
Wird das Attribut "timeDiffToNow" gesetzt, werden die evtentuell gesetzten Attribute "timestamp_begin" bzw. "timestamp_end" gelöscht. Das Setzen von "timestamp_begin" bzw. "timestamp_end" bedingt die Löschung von Attribut "timeDiffToNow", wenn gesetzt.
Readings
Abhängig von der ausgeführten DB-Operation werden die Ergebnisse in entsrechnden Readings dargestellt. Zu Beginn einer neuen Operation werden alle alten Readings einer vorangegangenen Operation gelöscht um den Verbleib unpassender bzw. ungültiger Readings zu vermeiden.
Zusätzlich werden folgende Readings erzeugt:
- state : enthält den aktuellen Status der Auswertung. Wenn Warnungen auftraten (state = Warning) vergleiche Readings "diff-overrun_limit-<diffLimit>" und "not_enough_data_in_period"
- errortext : Grund eines Fehlerstatus
- background_processing_time : die gesamte Prozesszeit die im Hintergrund/Blockingcall verbraucht wird
- sql_processing_time : der Anteil der Prozesszeit die für alle SQL-Statements der ausgeführten Operation verbraucht wird
- diff-overrun_limit-<diffLimit> : enthält eine Liste der Wertepaare die eine durch das Attribut "diffAccept" festgelegte Differenz <diffLimit> (Standard: 20) überschreiten. Gilt für Funktion "diffValue".
- not_enough_data_in_period : enthält eine Liste der Zeitperioden in denen nur ein einziger Datensatz gefunden wurde und dadurch keine Differenzberechnung durchgeführt werden konnte. Gilt für Funktion "diffValue".
DbRep Agent - automatisches Ändern von Device-Namen in Datenbanken und DbRep-Definitionen nach FHEM "rename"
Mit dem Attribut "role" wird die Rolle des DbRep-Device festgelegt. Die Standardrolle ist "Client". Mit der Änderung der Rolle in "Agent" wird das Device veranlasst auf Umbenennungen von Geräten in der FHEM Installation zu reagieren.
Durch den DbRep-Agenten werden folgende Features aktiviert wenn ein Gerät in FHEM mit "rename" umbenannt wird:
- in der dem DbRep-Agenten zugeordneten Datenbank (Internal Database) wird nach Datensätzen mit dem alten Gerätenamen gesucht und dieser Gerätename in allen betroffenen Datensätzen in den neuen Namen geändert.
- in dem DbRep-Agenten zugeordneten DbLog-Device wird in der Definition das alte durch das umbenannte Device ersetzt. Dadurch erfolgt ein weiteres Logging des umbenannten Device in der Datenbank.
- in den existierenden DbRep-Definitionen vom Typ "Client" wird ein evtl. gesetztes Attribut "device = alter Devicename" in "device = neuer Devicename" geändert. Dadurch werden Auswertungsdefinitionen bei Geräteumbenennungen automatisch konsistent gehalten.
Mit der Änderung in einen Agenten sind folgende Restriktionen verbunden, die mit dem Setzen des Attributes "role = Agent" eingeschaltet und geprüft werden:
- es kann nur einen Agenten pro Datenbank in der FHEM-Installation geben. Ist mehr als eine Datenbank mit DbLog definiert, können ebenso viele DbRep-Agenten eingerichtet werden
- mit der Umwandlung in einen Agenten wird nur noch das Set-Komando "renameDevice" verfügbar sein sowie nur ein eingeschränkter Satz von DbRep-spezifischen Attributen zugelassen. Wird ein DbRep-Device vom bisherigen Typ "Client" in einen Agenten geändert, werden evtl. gesetzte und nun nicht mehr zugelassene Attribute glöscht.
Die Aktivitäten wie Datenbankänderungen bzw. Änderungen an anderen DbRep-Definitionen werden im Logfile mit verbose=3 protokolliert. Damit die renameDevice-Funktion bei großen Datenbanken nicht in ein timeout läuft, sollte das Attribut "timeout" entsprechend dimensioniert werden. Wie alle Datenbankoperationen des Moduls wird auch das Autorename nonblocking ausgeführt.
Beispiel für die Definition eines DbRep-Device als Agent:
define Rep.Agent DbRep LogDB
attr Rep.Agent devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Agent icon security
attr Rep.Agent role Agent
attr Rep.Agent room DbLog
attr Rep.Agent showproctime 1
attr Rep.Agent stateFormat { ReadingsVal("$name","state", undef) eq "running" ? "renaming" : ReadingsVal("$name","state", undef). " »; ProcTime: ".ReadingsVal("$name","sql_processing_time", undef)." sec"}
attr Rep.Agent timeout 3600
Praxisbeispiele / Hinweise und Lösungsansätze für verschiedene Aufgaben
Definieren eines DbRep-Devices
Das DbRep-Device wird bei der Definition mit der DbLog-Instanz verbunden, in deren angeschlossener Datenbank später die Auswertungen und Operationen stattfinden sollen. Es ist also nicht die Datenbank selbst, sondern das vorher definierte DbLog-Device anzugeben. Die Definition erfolgt z.B. durch:
define Rep.Energy DbRep LogDB #LogDB ist das zu verbindende DbLog-Device
Bei der Definition werden die Zugangsdaten aus der DbLog-Instanz gelesen und das DbRep-Device mit der Datenbank verbunden. Nach der Definition ist der Status "initialized". Nach ca. 5 Sekunden wechselt er nach "connected" sofern die Verbindung zur Datenbank erfolgreich war. Zu welcher Datanbank das DbRep-Device sich verbunden hat, zeigt das Internal DATABASE.
Damit ist das DbRep-Device grundsätzlich einsatzbereit, aber noch nicht praxistauglich. Werden keine weiteren Eingrenzungen angegeben, kann mit dem so definierten Device mit dem Befehl
set Rep.Energy countEntries
die gesamte Anzahl der Datensätze in der Datenbank ermittelt werden. Für eine weitere Verwendung sind weitere Attribute zu setzen. Um die Funktionen von "Rep.Energy" nur auf z.B. Datensätze in der Datenbank anzuwenden die "STP_5000" im Feld "DEVICE" enthalten, wird das Attribut:
attr Rep.Energy device STP_5000
gesetzt. Weitere Begrenzungen der gerätespezifischen Selektion erfolgt durch das Attribut "reading". So wird durch
attr Rep.Energy reading etotal
festgelegt, dass sich die (allermeisten) Operationen auf die Kombination aus dem "device STP_5000" und dem "reading etotal" beziehen. Eine zeitliche Eingrenzung der Ergebnisse erfolgt durch die Attribute "timeDiffToNow", "timeOlderThan", "timestamp_begin", "timestamp_end". In dem Beispiel sollen sich die Selektionsergebnisse immer auf die letzten 120 Minuten beziehen. Dazu wird das Attribut
attr Rep.Energy timeDiffToNow 7200 #Der Wert für timeDiffToNow ist in Sekunden anzugeben
gesetzt. Es wird dynamisch bei jeder Operation "<Selektionsbeginn> = <aktuelle Zeit> - 3600s" berechnet und die Datensätze bis zu <aktuelle Zeit> berücksichtigt. Die gesamten Datenbankoperationen und teilweise auch Auswertungen von Selektionen erfolgt mit Blockingcall im Hintergrund. Der Timeout für die Operationen ist per Default auf 60s gesetzt. Über das Attribut "timeout" kann es den eigenen Bedingungen angepasst werden. In dem Beispiel wird timeout auf 300s geändert um auch bei sehr großen Selektionen und Auswertungen nicht in einen timeout zu laufen.
attr Rep.Energy timeout 300
Um auch die Verarbeitungszeiten im Hintergrund als Reading anzeigen zu lassen wird mit mit dem Attribut
attr Rep.Energy showproctime 1
erreicht. Mit diesen Einstellungen ist das Device für den konfiguriert und man kann sich zum Beispiel mit
set Rep.Energy fetchrows
die Datensätze mit der Gesamtenergierzeugung "etotal" des Wechselrichters "STP_5000" die in den letzten 2 Stunden in die DB geschrieben wurden. Nachdem der Befehl in der Gerätedetailsicht ausgeführt wurde, wechselt der state im DeviceOverview auf "running". Sobald im DeviceOverview "done" angezeigt wird sieht man die Ergebnisse nach einem Browserrefresh. Bei der Ausführung einer erneuten Operation werden alle Readings gelöscht. Sollen bestimmte Readings davon ausgenommen werden, kann dem Attribut eine kommaseparierte Liste von zu schützenden Readings übergeben werden.
Allgemein wird empfohlen sich für jede Aufgabe eine separates DbRep-Device anzulegen und entsprechend zu konfigurieren anstatt die Einstellungen ständig den neuen Aufgaben anzupassen.
Um den Prozess zu vereinfachen, kann das einmal angelegte Device für eine neue Selektionsaufgabe (zum Beispiel die Datensätze eines SMA Energymeters anzuzeigen bzw. auszuwerten) auf ein neues DbRep-Device kopiert
copy Rep.Energy Rep.SMAMeter
und entsprechend angepasst werden.
Hinweis zur Eventgenerierung:
Je nach genutzter Funktion können sehr viele Readings als Ergebnis generiert werden. Zum Beispiel können mit "fetchrows", wobei jedes Reading einer selektierte Zeile aus der Datenbank entspricht, durchaus mehrere hundert Readings entstehen.
Sollte man nicht durch die Attribute "event-on-update-reading" bzw. "event-on-change-reading" die Eventerzeugung auf nur relevante Readings begrenzt haben, können in diesem Fall ebenso viele Events enstehen die das System entsprechend belasten können.
Deswegen wird empfohlen die Eventerzeugung sofort auf z.B. "state" zu begrenzen.
Datensätze (Devices) von einer Datenbank in eine andere umziehen (Export/Import)
Zweck
Oft ist es so, dass man zunächst eine DbLog-Datenbank anlegt um alle zu loggenden Events dort aufzuzeichnen. Mit zunehmender Größe bzw. mit dem Wunsch nach einer höheren Strukturierung werden weitere DbLog-Instanzen angelegt. Die bereits geschriebenen Datensätze eines Gerätes müssen nun in eine andere Datenbank verlagert werden, weil das Device nunmehr in dieser Datenbank geloogt und ausgewertet werden soll.
Für das Beispielszenario gilt folgendes:
- Quelldatenbank aus der das Device entfernt werden soll ist "fhem" mit der DbLog-Instanz "LogDB"
- Zieldatenbank ist "fhemshort" mit der DbLog-Instanz "LogDBShort"
- das umzuziehende Device ist "MelderCP1"
- das definierte DbRep-Device ist "Rep.MelderCP1"
Vorbereitung
Zunächst wird ein DbRep-Device definiert (falls es noch nicht existiert) und für den Verwendungszweck vorbereitet (zur Definition siehe Definieren eines DbRep-Devices).
Das Attribut "reading" bzw. eventuell gesetzte Attribute zur Zeiteingrenzung werden gelöscht, damit alle Datensätze des Devices erfasst werden können. Für den bevorstehenden Export wird mit dem Attribut "expimpFile" der (beschreibbare) Pfad und Dateiname festgelegt, hier im Beispiel ist es "/media/sf_Backup_FHEM/meldercp1.txt".
Mit
set Rep.MelderCP1 countEntries
kann man sich nun einen Überblick verschaffen wieviel Datensätze in der Quelldatenbank für "MelderCP1" enthalten sind und wieviel auch exportiert werden müssen. In dem Beispiel sind es, wie in dem Screenshot zu sehen, 1144 Datensätze.
Falls noch nicht geschehen, wird in der bisherigen DbLog-Definition das zu loggende Device entfernt und in der neuen DbLog-Definition aufgenommen damit nun keine neuen Datensätze mehr für "MelderCP1" in die bisherige Datenbank geschrieben werden. Hierzu siehe die Commandref zu DbLog.
Export
Nun werden die Datensätze des Devices "MelderCP1" mit dem folgenden set-Kommando in die Datei "/media/sf_Backup_FHEM/meldercp1.txt" exportiert.
set Rep.MelderCP1 exportToFile
Nach dem Export sollte natürlich im Reading von "Rep.MelderCP1" die gleiche Anzahl von exportierten Datensätzen ausgegeben werden wie vorher mit "countEntries" ermittelt wurde (siehe Screenshot).
In der Export-Datei sind nun die Datensätze im CVS-Format enthalten.
Ein Ausschnitt:
............ "2016-07-04 17:32:03","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 07:47:50","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 08:27:57","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 08:28:25","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 10:23:42","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 10:27:35","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-05 17:26:30","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-06 07:46:31","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-06 11:24:04","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-06 11:25:43","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" "2016-07-06 11:26:52","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60","" ...........
In der bisherigen Datenbank "fhem" können die Datensätze nun gelöscht werden. Dazu versehen wir das DbRep-Device "Rep.MelderCP1" mit dem Attribut "allowDeletion" um die Löschfunktion des Moduls freizuschalten. Nun werden die vorher exportierten Datensätze gelöscht mit:
set Rep.MelderCP1 delEntries
Auch jetzt ist wieder sicherzustellen dass in der Ausgabe der gelöschten Rows dieselbe Anzahl (1144) der exportierten Datensätze enthalten ist.
Import
Im nächsten Schritt werden die exportierten Daten in die neue Datenbank importiert. Dazu wird in unserem DbRep-Device "Rep.MelderCP1" zunächst das "allowDeletion"-Attribut sicherheitshalber gelöscht. Zur Umstellung des DbRep-Devices auf die neue Datenbank wird die Definition von "Rep.MelderCP1" editiert und dort die neue DbLog-Instanz "LogDBShort" angegeben.
modify Rep.MelderCP1 LogDBShort
Nach einem kurzen Moment wird der state von "Rep.MelderCP1" sich wieder von "initialized" auf "connected" ändern sofern die Umstellung funktioniert hat. Mit einem Vergleichslauf durch
set Rep.MelderCP1 countEntries
wird ersichtlich, dass sich in dieser Datenbank noch keine (oder vllt. bereits neu geloggte) Einträge von "MelderCP1" befinden.
Nun kann der Import erfolgen. Mit
set Rep.MelderCP1 importFromFile
werden die Daten aus der immer noch im Attribut "expimpFile" hinterlegten Datei "/media/sf_Backup_FHEM/meldercp1.txt" in die Datenbank "fhemshort" importiert. Dieser Vorgang wird als Transaktion ausgeführt. Es werden immer alle Daten oder, im Falle eines Fehlers, KEINE Daten importiert. Damit ist sichergestellt dass der Datenimport immer einen definierten Zustand hat. Sollte der Datenimport sehr umfangreiche Datensätze enthalten und somit schon absehbar sein dass der voreingestellte timeout-Wert von 60 Sekunden nicht ausreichen wird, kann man vorsorglich das Attribut "timeout" höher setzen, z.B. auf 3600).
Hier in dem Beispiel sind es lediglich 1144 Datensätze die sehr schnell importiert werden. Somit ist keine Anpassung des timeout-Parameters notwendig. Auch nach dem Import wird wieder die Anzahl der verarbeiteten Dataensätze ausgegeben. Sie sollte natürlich ebenfalls mit den vorab ermittelten Zahlen der exportierten Datensätze übereinstimmen.
Abschluss
Nach dem erfolgreichen Import sollte das Attribut "expimpFile" wieder entfernt werden damit man nicht versehentlich einen erneuten Import durchführt. Das verwendete Rep.MelderCP1 kann nun wieder mit Zeitbegrenzungsattributen usw. versehen werden um die ursprüngliche Verwendung wieder herzustellen.
Die dargestellte Prozedur stellt einen Komplettumzug eines Devices dar, kann jedoch durch die Angabe der bekannten Attribute auch auf bestimmte Readings in der Datenbank oder Zeitgrenzen eingeschränkt werden. Dadurch würden nur bestimmte Datensätze exportiert und wieder importiert werden. Weiterhin sollte man daran denken die vorhandenen Auswertungsszenarien mit DbRep-Devices bzw. SVG-Diagrammen usw. auch auf die neue Datanbank umzustellen.
Ermittlung und Darstellung der täglichen Energieerzeugung eines Wechselrichters
Gegeben sei dass die Energiedaten eines Wechselrichters (STP_5000) mit SMAUtils in Verbindung mit SBFSpot in die Datenbank geschrieben werden. Neben vielen anderen Werten liefert SMAUtils die Tageserzeugung in kWh als Reading "etoday". Der Wert dieses Readings wird alle paar Minuten in der Datenbank gespeichert.
Zur Auswertung wird ein DbRep-Device angelegt wie unter Definieren eines DbRep-Devices) beschrieben (z.B. Rep.etoday.STP_5000).
Es soll die täglich erzeugte Energiemenge beginnend ab dem 01.10.2016 0 Uhr bis zum 13. Oktober angezeigt werden.
attr Rep.etoday.STP_5000 timestamp_begin 2016-10-01 00:00:00 attr Rep.etoday.STP_5000 timestamp_end 2016-10-13 23:59:59
Da es sich um eine tägliche Aggregation handelt (es soll pro Auswertung der Tag von 00:00:00 bis 23:59:59 betrachtet werden) und die Hintergrundverarbeitungszeit dargestellt werden soll, wird eingestellt:
attr Rep.etoday.STP_5000 aggregation day attr Rep.etoday.STP_5000 showproctime 1
Die Eingrenzung der auszuwertenden Devices und der dazu gehörigen Readings wird durch die entsprechenden Attribute gewährleistet. Es soll nur das Device "STP_5000" mit dem Reading "etoday" berücksichtigt werden. Dazu stellen wir ein:
attr Rep.etoday.STP_5000 reading etoday attr Rep.etoday.STP_5000 device STP_5000
DbRep ist nun grundsätzlich zur Auswertung konfiguriert (siehe Screenshot).
Zur Selektion und Berechnung von numerischen Daten stehen die Funktionen average-, max-, min-, sum- und diffValue zur Verfügung. Bei den in diesem Beispiel verwendeten Daten handelt es sich um einen täglich neu erzeugten und über 24 Stunden stetig steigenden Wert. Demnach ist für diese Art Daten die Funktion "maxValue" geeignet. Sie gibt den maximalen Wert des Readings im eingestellten Aggregationszeitraum (day) aus.
Die Berechnung wird ausgeführt durch:
set Rep.etoday.STP_5000 maxValue
Danach kurzer Zeit ist die Berechnung erfolgt (state=done in DeviceOverview). Nach einem Browserrefresh in der Detailansicht sind die erzeugten Readings sichtbar.
Jedes Reading hat einen bestimmten Aufbau. Die Funktion "maxValue" erzeugt Readings folgenden Aufbaus.
2016-10-07_18-19-03__STP_5000__etoday__MAX__2016-10-07
Zunächst wird der Timestring "2016-10-07_18-19-03" ausgegeben der in diesem Kontext den höchsten (d.h. letzten) Wert von "etotal" an dem Tag markiert. Bei dem Wechselrichter ist es damit auch der Zeitpunkt zu dem die Energieerzeugung eingestellt wurde (in dem Fall 07.10.2016 um 18:19:03).
Anmerkung: Die Notation des Timestrings wurde so gewählt, um die Regeln für in Readings erlaubte Zeichen einzuhalten. Wenn keine auswertbaren Daten vorliegen und berechnet werden konnten, werden Readings mit "-" ausgegeben. Im Beispiel sind es die Tagesaggregate 10.10.-13.10. da diese Tage in der Zukunft liegen.
Danach folgt im Reading die Angabe des Devices (STP_5000), des augewerteten Readings (etoday) und der Funktion die dieses Ergebnis ermittelt hat (MAX für maxValue).
Die letzte Angabe, hier "2016-10-07" definiert den Auswertungszeitraum. In dem Beispiel ist es der 07.10.2016. Würde die Berechnung mit aggregation=week durchgeführt werden, würde man als an dieser Stelle den Auswertungszeitraum "week_39" erhalten, also die Kalenderwoche 39.
Um die Auswertungsergebniss etwas benutzerfreundlicher zu gestalten, steht das Attribut "readingNameMap" zur Verfügung.
Im Beispiel setzen wir es auf:
attr Rep.etoday.STP_5000 readingNameMap Tageserzeugung_kWh
Ein erneuter maxValue-Lauf erzeugt Readings des folgenden Aufbaus:
2016-10-01_18-03-13__Tageserzeugung_kWh__2016-10-01 4.9870
(regelmäßiges) löschen von Datenbanksätzen
Dieses DbRep-Device dient dazu einmalig oder verbunden mit einem AT-Device Einträge aus einer Datenbank zu löschen. Zunächst wird das Device wie im Abschnitt "Definieren eines DbRep-Devices" beschrieben definiert. Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Del.DbShort" und das DbLog-Device "LogDBShort".
In diesem Beispiel sollen alle Datensätze gelöscht werden die älter als 180 Tage sind. Die Löschfunktion des Moduls ist standardmäßig ausgeschaltet und muß per Attribut enabled werden.
Dazu werden die Attribute
attr Rep.Del.DbShort timeOlderThan 5552000 attr Rep.Del.DbShort allowDeletion 1
gesetzt. Die Zeitangabe erfolgt in Sekunden.
Der Löschvorgang wird mit
set Rep.Del.DbShort delEntries
gestartet. Nach Abschluß der Datenlöschung wird die Anzahl der deleted rows als Reading ausgegeben und auch im Log mit verbose=3 geschrieben.
Müssen sehr viele Datensätze gelöscht werden könnte nach 60s der Standardtimeout erreicht werden und der Vorgang mit "error" enden. In diesem Fall ist der timout mit dem Attribut:
attr Rep.Del.DbShort timeout <timeout in Sekunden>
entsprechend angepasst werden.
Ein fhem.cfg Eintrag für das beschriebene Beispieldevice sieht folgendermaßen aus:
define Rep.Del.DbShort DbRep LogDBShort attr Rep.Del.DbShort allowDeletion 1 attr Rep.Del.DbShort comment löschen aller Einträge in LogDBShort älter als 180 Tage attr Rep.Del.DbShort devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen attr Rep.Del.DbShort event-on-update-reading state attr Rep.Del.DbShort room DbLog attr Rep.Del.DbShort timeOlderThan 15552000
Die Löschung der relevanten Datensätze kann weiterhin über Attribute "device" bzw. "reading" kann selektiv auf bestimmte Device- und/oder Readingloggings beschränkt werden. Wird keine Zeitbeschränkung (z.B. durch "timeOlderThan") vorgenommen, erfolgt die Löschung aller Datensätze der durch "device" bzw. "reading" spezifizierten Datenbankinhalte.
Als Argument der Attribute "device" bzw. "reading" können SQL-Wildcards "%" bzw. "_" verwendet werden.
% substituiert ein oder mehrere Zeichen _ Platzhalter für ein einzelnes Zeichen
Beispiel:
attr Rep.Del.DbShort device %5000
Mit dieser Spezifikation werden alle Devices gelöscht die auf "5000" enden, also z.B. STP_5000 und MySTP_5000.
Ein einfaches AT kann dazu dienen den Löschjob über das Device Rep.Del.DbShort regelmäßig alle x-Stunden/Minuten auszuführen. Dadurch werden nicht mehr benötigte Datenbankeinträge automatisiert und nicht FHEM blockierend im Hintergrund entfernt.
define At.Del.DbShort at +*23:45:00 set Rep.Del.DbShort delEntries attr At.Del.DbShort room DbLog
Größe der FHEM-Datenbank ermitteln
Zunächst wird das Device wie im Abschnitt "Definieren eines DbRep-Devices" beschrieben definiert. Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Fhem.Size".
Um die Größe der Datenbank beziehungsweise der Tabellen "history" und "current" zu ermitteln steht das Kommando:
get Rep.Fhem.Size tableinfo (MySQL, PostgreSQL) get Rep.Fhem.Size svrinfo (SQLite)
zur Verfügung.
Mit diesem Befehl werden sehr viele Informationen bezüglich der Tabellen des FHEM-Schemas (MySQL) als Readings ausgegeben.
Um nur die relevanten bzw. interessierenden Selektionsergebnisse auszugeben, kann mit dem Attribut showTableInfo (MySQL, PostgreSQL) bzw. showSvrInfo (SQLite) eine kommaseparierte Liste der relevanten Tabellen angegeben werden.
attr Rep.Fhem.Size showTableInfo %history%,%current% (MySQL, PostgreSQL)
So wie in diesem Beispiel gesetzt, werden nur Informationen der Tabellen "history" und "current" ausgegeben. Diese Ausgabe ich bereits recht übersichtlich, kann aber durch die Verwendung des Attributs suppressReading weiter eingegrenzt werden.
Beispiele:
attr Rep.Fhem.Size suppressReading ^(?!.*INFO_history.data_index_length_MB).*$ attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(state)).*$ attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(background_processing_time)|(state)).*$
Mit diesen Attributwerten wird nur das Reading "INFO_history.data_index_length_MB" oder aber "INFO_history.data_index_length_MB" und "state" bzw. "INFO_history.data_index_length_MB", "state" und "background_processing_time" dargestellt.
Die Datenbankgröße (MB) ist je nach DB-Typ in den Readings:
INFO_current.data_index_lenth_MB INFO_history.data_index_lenth_MB SQLITE_FILE_SIZE_MB
enhalten.
Wird z.B. über ein AT dieser Befehl regelmäßig durch Rep.Fhem.Size ausgeführt und die Ergebnisse wiederum in DbLog gespeichert kann die Größenentwicklung der Datenbank mittels SVG-Diagrammen dargestellt werden.
Reading von DbRep nach Dummy übertragen
In dem Beispiel werden alle erzeugten Readings des DbRep-Devices in den Dummy übertragen und heißen dann genauso.
define Dum.Rep dummy
attr Dum.Rep room DbLog
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep ".(split(":",$EVTPART0))[0]." $EVTPART1"}
attr N.Dum.Rep room DbLog
Soll im Dummy ein Reading mit eigenem Namen gefüllt werden, sieht das Notify so aus:
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep DeinReading"." $EVTPART1"}