Improved documentation for mentat-inspector.py.

(Redmine issues: #3376 and 3361)

bin/mentat-inspector.py

@@ -11,9 +11,6 @@
 """
 Daemon component capable of inspection IDEA messaes according to given
 set of filtering rules and performing number of associated actions.
-
-encapsulating :py:mod:`mentat.idea.mongodb`
-library and capable .
 """
 
 
@@ -32,8 +29,6 @@ import sys
 # Generate the path to custom 'lib' directory
 lib = os.path.abspath(os.path.join(os.path.dirname(__file__), '../lib'))
 sys.path.insert(0, lib)
-lib = os.path.abspath(os.path.join(os.path.dirname(__file__), '../bin'))
-sys.path.insert(0, lib)
 
 
 #

doc/sphinx/_doclib/lib.rst

@@ -16,4 +16,5 @@ Python submodules
     lib.mentat.idea.internal
     lib.mentat.idea.mongodb
 
+    lib.mentat.daemon.component.inspector
     lib.mentat.daemon.component.storage

lib/mentat/daemon/component/inspector.py

@@ -12,8 +12,178 @@ Daemon component providing simple yet powerfull message processing tools
 based on performing conditional actions according to list of filtering
 rules.
 
-Implementation is based on ZenDaemonComponent and encapsulating the
-mentat.filtering library.
+It is dependent on services of following modules:
+
+* :py:mod:`mentat.filtering.filters`
+
+  Filtering rule library.
+
+
+.. _subsubsection-configuration:
+
+Setup configuration
+^^^^^^^^^^^^^^^^^^^
+
+
+This daemon component requires that following configurations are provided by
+external daemon:
+
+inspection_rules
+    List of inspection rules. See section :ref:`subsubsection-inspection-rules`
+    below for more information about available actions.
+
+fallback_actions
+    List of fallback actions. See section :ref:`subsubsection-inspection-actions`
+    below for more information about available actions.
+
+
+.. _subsubsection-inspection-rules:
+
+Inspection rules
+^^^^^^^^^^^^^^^^
+
+Inspection rules define what actions should be performed with what messages.
+Every inspection rule may have following attributes:
+
+rule
+    Filtering rule compatible with :py:mod:`mentat.filtering.filters` library. All
+    messages will be compared to this rule and actions will be performed with those
+    that match.
+
+    (``string``, **mandatory**)
+
+name
+    Optional name for the rule to be used in logs and other user output. This should
+    be something brief and meaningfull to uniquelly identify the rule. When not set
+    this defaults to **rule** attribute.
+
+    (``string``, *optional*)
+
+description
+    Optional user description of the meaning of the rule. When not set defaults to ``???``.
+
+    (``string``, *optional*)
+
+final
+    Boolean flag indicating the rule is final and all subsequent rules should not be
+    considered. When not set defaults to ``False``.
+
+    (``boolean``, *optional*)
+
+
+enabled
+    Boolean flag indicating the rule is enabled or disabled. When not set defaults
+    to ``True``.
+
+    (``boolean``, *optional*)
+
+actions
+    List of inspection action to be performed upon filter match. See section
+    :ref:`subsubsection-inspection-actions` for more details.
+
+
+.. _subsubsection-inspection-actions:
+
+Inspection actions
+^^^^^^^^^^^^^^^^^^
+
+Every action has following common attributes:
+
+action
+    Type of the action. See below for list of all currently available actions.
+
+    (``string``, **mandatory**)
+
+name
+    Optional name for the action to be used in logs and other user output. This should
+    be something brief and meaningfull to uniquelly identify the action. When not set
+    this defaults to **action** attribute.
+
+    (``string``, *optional*)
+
+description
+    Optional user description of the meaning of the action. When not set defaults to ``???``.
+
+    (``string``, *optional*)
+
+enabled
+    Boolean flag indicating the action is enabled or disabled. When not set defaults
+    to ``True``.
+
+    (``boolean``, *optional*)
+
+args
+    Dictionary of additional arguments for the action. The appropriate arguments
+    are specific for particular action. See below for more information for each
+    action.
+
+    (``dict``, *optional*)
+
+There are following inspection actions, that can be performed with matching messages
+or as fallback action:
+
+tag
+    Tag the corresponding message at given JPath with given value. The tag value
+    may be only constant value.
+
+    *Arguments:*
+
+    * **path** - :py:mod:`JPath <mentat.filtering.jpath>` to be set (``string``, **mandatory**)
+    * **value** - value to be set (``any``, **mandatory**)
+    * **overwrite** - flag indicating whether existing value should be overwritten, or not, defaults to ``True`` (``boolean``, *optional*)
+    * **unique** - flag indicating whether value should be unique, or not, defaults to ``False`` (``boolean``, *optional*)
+
+set
+    Set the corresponding message at given JPath with result of given expression.
+    The expression must be compatible with :py:mod:`JPath <mentat.filtering.filters>`
+    module.
+
+    *Arguments:*
+
+    * **path** - :py:mod:`JPath <mentat.filtering.jpath>` to be set (``string``, **mandatory**)
+    * **expression** - :py:mod:`JPath <mentat.filtering.filters>` compatible expression to be set (``string``, **mandatory**)
+    * **overwrite** - flag indicating whether existing value should be overwritten, or not, defaults to ``True`` (``boolean``, *optional*)
+    * **unique** - flag indicating whether value should be unique, or not, defaults to ``False`` (``boolean``, *optional*)
+
+report
+    Report the corresponding message via email.
+
+    *Arguments:*
+
+    * **to** - recipient email address (``string``, **mandatory**)
+    * **from** - sender email address (``string``, **mandatory**)
+    * **subject** - email report subject (``string``, **mandatory**)
+    * **report_type** - email report type, will be inserted into ``X-Cesnet-Report-Type`` email header (``string``, **mandatory**)
+
+    .. todo::
+        Finish usage of default arguments and then update this documentation. Currently every argument is mandatory, which makes users repeat themselves.
+
+drop
+    Drop the corresponding message from processing (filter out).
+
+    *This action currently does not have any arguments.*
+
+dispatch
+    Dispatch (move) the corresponding message into another queue directory.
+
+    *Arguments:*
+
+    * **queue_tgt** - path to target queue (``string``, **mandatory**)
+
+duplicate
+    Duplicate (copy) the corresponding message into another queue directory.
+
+    *Arguments:*
+
+    * **queue_tgt** - path to target queue (``string``, **mandatory**)
+
+log
+    Log the corresponding message into daemon module log.
+
+    *Arguments:*
+
+    * **label** - log message label, defaults to ``Inspection rule matched`` (``string``, **optional**)
+
 """
 
 __version__ = "0.1"
@@ -91,7 +261,7 @@ class InspectorDaemonComponent(pyzenkit.zendaemon.ZenDaemonComponent):
 
     def _setup_action_args(self, action, args):
         """
-        Setup default action arguments
+        Setup default action arguments.
         """
         if action in self.default_action_args:
             for arg_name, arg_val in self.default_action_args[action].items():
@@ -377,9 +547,3 @@ class InspectorDaemonComponent(pyzenkit.zendaemon.ZenDaemonComponent):
         daemon.logger.warning("Log - Message '{}':'{}': '{}'".format(mid, iid, label))
         self.inc_statistics(self.STATS_CNT_LOGGED)
         return daemon.FLAG_CONTINUE
-
-if __name__ == "__main__":
-    """
-    Perform the demonstration.
-    """
-    pass