Documentation for Auditor plugin

MatterMiners · Aug 30, 2022 · c97cf61 · c97cf61
1 parent a12b003
commit c97cf61
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 1 deletion.
diff --git a/docs/source/plugins/plugins.rst b/docs/source/plugins/plugins.rst
@@ -161,6 +161,62 @@ Available configuration options
             index: cobald_tardis
             meta: instance1
 
+Auditor Accounting
+------------------
+
+.. content-tabs:: left-col
+
+    The :py:class:`~tardis.plugins.auditor.Auditor` implements an interface to push
+    information from the drones relevant for accounting to an `Auditor <https://alu-schumacher.github.io/AUDITOR/>`_ instance.
+    The plugin extracts the components to be accounted for from the ``MachineMetaData`` in the configuration, 
+    Scores which help relating resources of the same kind with different performance to each other, can be configured as well.
+    Scores are configured for each ``MachineType`` individually and multiple scores per ``MachineType`` are possible.
+    An Auditor record requires a ``site_id``, a ``user_id`` and a ``group_id``. The latter two can be configured in the
+    ``Auditor`` plugin configuration (and default to ``tardis`` if omitted). The ``site_id`` is taken from the ``Sites`` in
+    the TARDIS config.
+
+Available configuration options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. content-tabs:: left-col
+
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+    | Option     | Short Description                                                                                    | Requirement     |
+    +============+======================================================================================================+=================+
+    | host       | Hostname or IP address of the Auditor instance.                                                      |  **Required**   |
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+    | port       | Port the Auditor instance is listening on.                                                           |  **Required**   |
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+    | user       | User name added to the record. Defaults to ``tardis``.                                               |  **Optional**   |
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+    | group      | Group name added to the record. Defaults to ``tardis``.                                              |  **Optional**   |
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+    | components | Configuration of the components per ``MachineType``. Used to attach scores to individual components. |  **Optional**   |
+    +----------------+--------------------------------------------------------------------------------------------------+-----------------+
+
+.. content-tabs:: right-col
+
+    .. rubric:: Example configuration
+
+    .. code-block:: yaml
+
+        Plugins:
+          Auditor:
+            host: "127.0.0.1"
+            port: 8000
+            user: "some-user"
+            group: "some-group"
+            components:
+              machinetype_1:
+                Cores:
+                  HEPSPEC06: 1.2
+                  OTHERBENCHMARK: 1.4
+              machinetype_2:
+                Cores:
+                  HEPSPEC06: 1.0
+                Memory:
+                  PRECIOUSMEMORY: 2.0
+
 .. content-tabs:: left-col
 
     Your favorite monitoring is currently not supported?

diff --git a/tardis/plugins/auditor.py b/tardis/plugins/auditor.py
@@ -13,7 +13,13 @@
 
 class Auditor(Plugin):
     """
-    The :py:class:`~tardis.plugins.auditor.Auditor` TODO
+    The :py:class:`~tardis.plugins.auditor.Auditor` plugin is a collector for the
+    accounting tool Auditor. It sends accounting information of individual drones to an
+    Auditor instance. The records contain information about the provided resources of
+    the drones as well as start and stop times. When a drone enters `AvailableState`, a
+    record with the start time set to the time it went into this state is stored in the
+    Auditor database. The stop time remains empty until the drone goes into `DownState`.
+    The Auditor plugin does not keep any state.
     """
 
     def __init__(self):