diff --git a/memlog/README.md b/memlog/README.md deleted file mode 100755 index 7dcf8c289..000000000 --- a/memlog/README.md +++ /dev/null @@ -1,169 +0,0 @@ -# memlog - -This plugins can be used to create in-memory logs which can be used by items or other -plugins. - -## Requirements - -No special requirements. - -## Configuration - -### plugin.yaml - -Use the plugin configuration to configure the in-memory logs. - -``` -memlog: - plugin_name: memlog - name: alert - mappings: - - time - - thread - - level - - message -# maxlen: 50 -# items -# - first.item.now -# - second.item.thread.info -# - third.item.level -# - fourth.item.msg -``` - -This will register a in-memory log with the name "alert". This can be used to attach -to items. - -#### name attribute - -This will give the in-memory log a name which can be used when accessing them. - -#### mappings attribute - -This configures the list of values which are logged for each log message. The following -internal mappings can be used and will be automatically set - if not given explicitely -when logging data: - -* ``time`` - the timestamp of log -* ``thread`` - the thread logging data -* ``level`` - the log level (defaults to INFO) - -#### maxlen attribute - -Defines the maximum amount of log entries in the in-memory log. - -#### items attribute - -Each time an item is updated using the `memlog` configuration setting, a log entry will -be written using the list of items configured in this attribute as log values. - -If items are defined, then four items should be named, -each with the following purpose: - - * Item A - the value of this item is entered as the timestamp - * Item B - the value of this item is entered as the thread info - * Item C - the value of this item is entered as the level of log message - * Item D - the value of this item is entered as the message - -Using Items this way it is possible to set the values of those items first -and then trigger the item which has the ``memlog`` attribute. - -When the items attribute is not configured, the default mapping values will be used and the value of the item will be logged which has the ``memlog`` attribute. - -### items.yaml - -The following attributes can be used. - -#### memlog - -Defines the name of in-memory log which should be used to log the item's content to -the log. Everything is logged with 'INFO' level. - -#### Example - -Simple item logging: - -```yaml -some: - item: - type: str - memlog: alert -``` - -An update to item ``some.item`` will cause a log entry to be generated with the value of item ``some.item``. - -### logic.yaml - -#### memlog - -Configures that a message should be logged whenever the logic was triggered. It logs a -default message which can be overwritten by the `memlog_message` attribute. - -#### memlog_message - -Defines the message to be logged. It configures a string which may contain placeholders -which got replaced by using the `format()` function. - -The following placeholders or object can be used in the message string: -* `logic` - the logic object. A format of ``{logic.name}`` will include the logics name -* `plugin` - the memlog plugin instance object -* `by` - the string containing the origin of logic trigger -* `source` - the source -* `dest` - the destination - -The `logic` and `plugin` placeholders are always available, the rest depends on the -logic invocation/trigger. - -Example: - -```yaml -memlog_message: The logic {logic.name} was triggered! -``` - -## Methods - -The plugin name defined it ``etc/plugin.yaml`` can be used as callable. - -### memlog(entry) -This log the given list of elements of `entry` parameter. The list should have the same amount -of items you used in the mapping parameter (see also the default for this value). - -`sh.memlog((self._sh.now(), threading.current_thread().name, 'INFO', 'Some information'))` - -### memlog(msg) - -This log the given message in `msg` parameter with the default log level. - -### memlog(lvl, msg) - -This logs the message in ``msg`` parameter with the given log level specified in ``lvl`` -parameter. - -### Examples - -Given the following base snippet of ``etc/plugin.yaml``: - -```yaml -my_memlog: - plugin_name: memlog - name: my_personal_memlog -``` - -The following expressions (e.g. in a logic) - -```python -sh.my_memlog("DEBUG","Debug Message") -sh.my_memlog("Hello world!") # info -sh.my_memlog("WARNING","This is a warning!") -sh.my_memlog("ERROR","This is already an error!!") -sh.my_memlog("CRITICAL","This is critical, just shutdown everything!!!") -``` - -together with this definition in SmartVISU pages: - -```html -{{ status.log('log_id', 'my_personal_memlog', 10) }} -``` - -will show a screen like this: - -![Screenshot of messages displayed with SmartVISU](callable.png "Result with SmartVISU") diff --git a/memlog/__init__.py b/memlog/__init__.py index 5b2437f4a..478309b99 100755 --- a/memlog/__init__.py +++ b/memlog/__init__.py @@ -30,10 +30,10 @@ class MemLog(SmartPlugin): - PLUGIN_VERSION = '1.6.0' + PLUGIN_VERSION = '1.6.1' def __init__(self, sh, *args, **kwargs): - + super().__init__() self.name = self.get_parameter_value('name') self.mappings = self.get_parameter_value('mappings') self.items = self.get_parameter_value('items') @@ -139,4 +139,3 @@ def log(self, logvalues, level = 'INFO'): logvalues = logvalues[1:] self._log.add(log) - diff --git a/memlog/callable.png b/memlog/assets/visu_callable.png similarity index 100% rename from memlog/callable.png rename to memlog/assets/visu_callable.png diff --git a/memlog/plugin.yaml b/memlog/plugin.yaml index a27eacd94..248d5e444 100755 --- a/memlog/plugin.yaml +++ b/memlog/plugin.yaml @@ -3,15 +3,14 @@ plugin: # Global plugin attributes type: system # plugin type (gateway, interface, protocol, system, web) description: - de: 'Speichern der Logeinträge im Speicher (zur Anzeige in der VISU)' - en: 'Store log entries in memory (for display in VISU)' + de: 'Speichern der Logeinträge im Speicher (zur Anzeige in der VISU). Durch Bordmittel ersetzbar.' + en: 'Store log entries in memory (for display in VISU). Can be replaced by standard config.' maintainer: ohinckel tester: cmalo - state: ready + state: deprecated keywords: memory log # keywords, where applicable -# documentation: https://github.com/smarthomeNG/plugins/blob/develop/mqtt/README.md # url of documentation (wiki) page - version: 1.6.0 # Plugin version + version: 1.6.1 # Plugin version sh_minversion: 1.4 # minimum shNG version to use this plugin # sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest) multi_instance: True @@ -40,26 +39,26 @@ parameters: # [time, thread, level, message] description: de: > - Definiert eine Liste mit kommagetrennten Werten die für jede Nachricht geloggt werden. + Definiert eine Liste mit kommagetrennten Werten die für jede Nachricht geloggt werden. Die folgenden internen Zuordnungen können benutzt werden: - + time - Zeitstempel des Eintrags thread - Thread der die Daten erzeugt level - Der log level (Standard ist INFO) message - Die Nachricht - - Die Vorgabe sollte beibehalten werden, wenn das Log in SmartVISU angezeigt werden soll, + + Die Vorgabe sollte beibehalten werden, wenn das Log in SmartVISU angezeigt werden soll, sonst werden die Werte von der SmartVISU für die Darstellung nicht korrekt interpretiert. en: > - This configures the list of values with comma separated values which are logged for each log message. + This configures the list of values with comma separated values which are logged for each log message. The following internal mappings can be used and will be automatically set if not given explicitely when logging data: - + time - the timestamp of log thread - the thread logging data level - the log level (defaults to INFO) message - the message - + The default value should not be changed. Otherwise the SmartVISU might misinterpret the values for display. maxlen: @@ -75,7 +74,7 @@ parameters: de: > Jedes mal wenn ein Item aktualisiert wird, wird ein Logeintrag geschrieben unter der Berücksichtigung der konfigurierten Items und deren Werte als Log Werte - + Wird dies nicht angegeben, dann werden die vorgegebenen Zuordnungswerte verwendet: - item_a --> now - item_b --> thread info @@ -85,7 +84,7 @@ parameters: en: > Each time an item is updated using the memlog configuration setting, a log entry will be written using the list of items configured in this attribute as log values. - + When this is not configured, the default mapping values will be used the associated item's value will be logged. e.g.: - item_a --> now @@ -100,7 +99,7 @@ item_attributes: description: de: > Bezeichnet den Namen des Logs in dem die Nachricht aufgezeichnet werden soll. - Alle´Einträge werden mit Level INFO erstellt + Alle Einträge werden mit Level INFO erstellt en: > Defines the name of in-memory log which should be used to log the item's content to the log. Everything is logged with 'INFO' level. @@ -128,36 +127,33 @@ logic_parameters: type: str description: de: > - Legt das Mitteilungsformat des Logeintrages fest. In der Zeichenkette können folgende Platzhalter enthalten + Legt das Mitteilungsformat des Logeintrages fest. In der Zeichenkette können folgende Platzhalter enthalten sein, die durch eine format Anweisung ersetzt werden: - + logic - Das Logik Objekt, z.B. logic.name für den Logiknamen plugin - Die Instanz des Memlog Plugins by - Ursprung des Logiktriggers source - Die Quelle dest - Das Ziel - Die Logik und Plugin Platzhalter sind immer verfügbar, die weiteren hängen davon ab + Die Logik und Plugin Platzhalter sind immer verfügbar, die weiteren hängen davon ab wie die Logik aufgerufen bzw. getriggert wurde - + Beispiel: memlog_message: "Die Logik {logic.name} wurde getriggert!" en: > Defines the message to be logged. It configures a string which may contain placeholders which got replaced by using the format() function. - + The following placeholders or object can be used in the message string: - + logic - the logic object, e.g. logic.name for the logic's name plugin - the memlog plugin instance object by - the string containing the origin of logic trigger source - the source dest - the destination - The logic and plugin placeholders are always available, the rest depends on the logic + The logic and plugin placeholders are always available, the rest depends on the logic invocation/trigger. - + Example: memlog_message: "The logic {logic.name} was triggered!" - - - diff --git a/memlog/user_doc.rst b/memlog/user_doc.rst new file mode 100644 index 000000000..8be5a1962 --- /dev/null +++ b/memlog/user_doc.rst @@ -0,0 +1,228 @@ +.. index:: Plugins; memlog +.. index:: memlog + +====== +memlog +====== + +.. image:: webif/static/img/plugin_logo.svg + :alt: plugin logo + :width: 300px + :height: 300px + :scale: 50 % + :align: left + + +Dieses Plugin stellt für Items und Plugins eine Loggingvariante +zur Verfügung, bei der die Logeinträge im Arbeitsspeicher abgelegt werden. + +.. important:: + + Das Plugin ist als "deprecated" abgekündigt. Ersatz der Funktionalität ist im nächsten Absatz beschrieben. + +Ersatz durch Bordmittel +======================= + +Details zum Memory Loghandler sind unter :doc:`Logging Handler ` +zu finden. Informationen zum Loggen bei Itemänderungen findet man unter +:doc:`log_change `. + +Beispiel Logik +-------------- + +In diesem Beispiel werden sämtliche Aufrufe des Loggers in der Logik ex_logging +in das Memorylog namens memory_info geschrieben. Während beim memlog Plugin durch +einen Eintrag in der ``etc/logic.yaml`` Datei beim Triggern einer Logik +automatisch ein Logeintrag erstellt wird, sind hier in der Logik selbst die +entsprechenden logger Methoden einzubinden. Somit können wie gewohnt auch +verschiedene Loglevel genutzt werden. + +Das Memorylog wird in der Datei ``etc/logging.yaml`` wie folgt konfiguriert: + +.. code-block:: yaml + + # etc/logging.yaml + handlers: + memory_info: + (): lib.log.ShngMemLogHandler + logname: memory_info + maxlen: 60 + level: INFO + cache: True + + loggers: + logics.ex_logging: + handlers: [memory_info] + level: INFO + +Die Logeinträge werden aus der Logik ``logics/.py`` wie folgt erstellt: + +.. code-block:: python + + # logics/ex_logging.py + sourceitem = items.return_item(trigger['source']) + logger.info(f"Logik '{logic.name}' wurde durch {trigger} getriggert. Source = {sourceitem}") + logger.debug(f"Logik '{logic.name}' (filename '{logic.filename}') wurde getriggert (DEBUG)") + +Beispiel Item +------------- + +Das Memorylog wird in der Datei ``etc/logging.yaml`` wie folgt konfiguriert: + +.. code-block:: yaml + + # etc/logging.yaml + handlers: + memory_info: + (): lib.log.ShngMemLogHandler + logname: memory_info + maxlen: 60 + level: INFO + cache: True + + loggers: + items.memory-items: + handlers: [memory_info] + level: INFO + +Nun können mehrere Items über die entsprechenden Attribute in das Memory Log +schreiben. Möchte man dabei die Möglichkeit des memlog Plugins, Mitteilungen +über ein Item zu deklarieren, nutzen, kommt das Attribut +``log_rules: "{'itemvalue': ''}"`` zum Einsatz. + +.. code-block:: yaml + + item: + type: num + log_change: memory-items + log_level: INFO + log_text: 'Wert={mvalue}, Alter={age}, Zeit={now}' + +Das Einbinden in eine SmartVISU Seite erfolgt mittels: + +.. code-block:: html + + {{ status.log('', 'memory_info', 10) }} + +Konfiguration +============= + +.. important:: + + Detaillierte Informationen zur Konfiguration des Plugins sind + unter :doc:`/plugins_doc/config/memlog` zu finden. + +plugin.yaml +----------- + +.. code-block:: yaml + + # etc/plugin.yaml + memlog: + plugin_name: memlog + name: alert + mappings: + - time + - thread + - level + - message + #maxlen: 50 + #items: + # - first.item.now + # - second.item.thread.info + # - third.item.level + # - fourth.item.msg + +Das angegebene Beispiel registriert ein Memory Log namens "alert". +Das `mappings` Attribut konfiguriert die Liste der Werte, die für jede Protokollmeldung +genutzt werden sollen. Die Werte werden dabei aus den angegebenen Items ausgelesen. + +items.yaml +---------- + +Das ``memlog`` Attribut legt den Namen des speicherinternen Logs fest, +das verwendet werden soll, um den Inhalt des Elements ins Log zu schreiben. + +.. code-block:: yaml + + some: + item: + type: str + memlog: alert + +Eine Aktualisierung des Eintrags "some.item" führt zur Erstellung eines Protokolleintrags +mit dem Wert des Eintrags ``some.item``. + +logic.yaml +---------- + +.. code-block:: yaml + + # etc/logic.yaml + ex_logging: + filename: example_logging.py + memlog: testing + memlog_message: The logic {logic.name} was triggered! + +Bei jeder Auslösung der Logik, im Beispiel example_logging.py, wird der Eintrag +im optionalen Attribut ``memlog_message`` in das entsprechende Speicherprotokoll geschrieben. + +Einsatz in Logiken +================== + +Funktionsaufruf +--------------- + +Der unter ``etc/plugin.yaml`` angegebene Pluginname kann durch () aufgerufen werden. +Dies protokolliert die angegebene Liste der Elemente des Parameters ``Eintrag``. Die Liste +sollte die gleiche Anzahl an Elementen haben, die in dem Mapping-Parameter angegeben wurde. + +.. code-block:: python + + sh.memlog((self._sh.now(), threading.current_thread().name, 'INFO', 'Some information')) + +Wird im Eintrag nur eine Mitteilung als String angegeben, werden die anderen Werte +entsprechend den Vorgaben in etc/plugin.yaml genutzt. Außerdem ist es möglich, +nur das Loglevel und die Mitteilung anzugeben, also z.B. +``sh.memlog('INFO', 'Some information')``. + +Beispiel +-------- + +In ``etc/plugin.yaml`` wird das Plugin wie folgt eingebunden: + +.. code-block:: yaml + + my_memlog: + plugin_name: memlog + name: my_personal_memlog + +Die folgenden Aufrufe können in einer Logik eingebunden werden: + +.. code-block:: python + + sh.my_memlog("DEBUG", "Debug Message") + sh.my_memlog("Hello world!") # info + sh.my_memlog("WARNING", "This is a warning!") + sh.my_memlog("ERROR", "This is already an error!!") + sh.my_memlog("CRITICAL", "This is critical, just shutdown everything!!!") + +Das Einbinden in eine SmartVISU Seite erfolgt mittels: + +.. code-block:: html + + {{ status.log('log_id', 'my_personal_memlog', 10) }} + +Das resultiert in einer Liste von Logeinträgen wie beispielsweise: + +.. image:: assets/visu_callable.png + :height: 302px + :width: 528px + :scale: 100% + :alt: Visu + :align: center + +Web Interface +============= + +Das Plugin verfügt über kein Web Interface, es kann aber in der SmartVISU genutzt werden. diff --git a/memlog/webif/static/img/plugin_logo.svg b/memlog/webif/static/img/plugin_logo.svg new file mode 100644 index 000000000..90543db16 --- /dev/null +++ b/memlog/webif/static/img/plugin_logo.svg @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + MEMLOG + \ No newline at end of file diff --git a/memlog/webif/static/img/readme.txt b/memlog/webif/static/img/readme.txt deleted file mode 100755 index 1a7c55eef..000000000 --- a/memlog/webif/static/img/readme.txt +++ /dev/null @@ -1,6 +0,0 @@ -This directory is for storing images that are used by the web interface. - -If you want to have your own logo on the top of the web interface, store it here and name it plugin_logo.. - -Extension can be png, svg or jpg - diff --git a/memlog/webif/templates/index.html b/memlog/webif/templates/index.html deleted file mode 100755 index 0d49ce7de..000000000 --- a/memlog/webif/templates/index.html +++ /dev/null @@ -1,124 +0,0 @@ -{% extends "base_plugin.html" %} - -{% set logo_frame = false %} - - -{% set update_interval = 0 %} - - -{% block pluginscripts %} - -{% endblock pluginscripts %} - - -{% block headtable %} - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Prompt 1{% if 1 == 2 %}{{ _('Ja') }}{% else %}{{ _('Nein') }}{% endif %}Prompt 4{{ _('Wert 4') }}
Prompt 2{{ _('Wert 2') }}Prompt 5-
Prompt 3-Prompt 6-
-{% endblock headtable %} - - - -{% block buttons %} -{% if 1==2 %} -
- -
-{% endif %} -{% endblock %} - - -{% set tabcount = 4 %} - - - -{% if item_count==0 %} - {% set start_tab = 2 %} -{% endif %} - - - -{% set tab1title = "" ~ p.get_shortname() ~ " Items (" ~ item_count ~ ")" %} -{% block bodytab1 %} -
- {{ _('Hier kommt der Inhalt des Webinterfaces hin.') }} -
-{% endblock bodytab1 %} - - - -{% set tab2title = "" ~ p.get_shortname() ~ " Geräte (" ~ device_count ~ ")" %} -{% block bodytab2 %} -{% endblock bodytab2 %} - - - -{% block bodytab3 %} -{% endblock bodytab3 %} - - - -{% block bodytab4 %} -{% endblock bodytab4 %}