add example doc for registering a custom log handler

Author: dmargala

docs/howto.rst

@@ -1162,3 +1162,60 @@ If you use a Python-based configuration file, you can define your custom launche
 .. note::
 
    In versions prior to 4.0, launchers could only be implemented inside the source code tree of ReFrame.
+
+
+.. _custom-loggers:
+
+Implementing a custom log handler
+---------------------------------
+
+Here's an example implementation of a custom log handler defined in a Python-based configuration file.
+
+Define a custom log handler class based on :class:`~logging.Handler` which uses a custom logging API:
+
+.. code-block:: python
+
+   import logging
+   import mylogger
+
+   class MyLoggerHandler(logging.Handler):
+      def __init__(self, key):
+         super().__init__()
+         self.key = key
+
+      def emit(self, record):
+         myrecord = {
+            'value': record.check_perf_value,
+         }
+         mylogger.log(self.key, myrecord)
+
+Apply the :func:`~reframe.core.logging.register_log_handler` decorator to a function returns an instance of the custom log handler:
+
+.. code-block:: python
+
+   from reframe.core.logging import register_log_handler
+
+   @register_log_handler("mylogger")
+   def _create_mylogger_handler(site_config, config_prefix):
+      key = site_config.get(f'{config_prefix}/key')
+      return MyLoggerHandler(key)
+
+
+Finally, add a handler entry with type matching registered name for the custom log handler to the site config:
+
+.. code-block:: python
+
+   site_configuration = {
+      'logging': [
+         {
+            'handlers': [
+               {
+                  'type': 'mylogger',
+                  'key': 'abc',
+               },
+               ...
+            ]
+         }
+      ],
+      ...
+   }