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/assets/visu_callable.png b/memlog/assets/visu_callable.png new file mode 100755 index 000000000..7fa4eac43 Binary files /dev/null and b/memlog/assets/visu_callable.png differ diff --git a/memlog/user_doc.rst b/memlog/user_doc.rst new file mode 100644 index 000000000..7d07f1e41 --- /dev/null +++ b/memlog/user_doc.rst @@ -0,0 +1,229 @@ +.. 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:: + + Die Funktionalität des Plugins ist auch über entsprechende Konfiguration der + ``etc/logging.yaml`` Datei sowie durch Nutzen des ``log_change`` Itemattributs abbildbar. + +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