Merge pull request #608 from cylc/8.1.x

8.1.x

Author: oliver-sanders

src/tutorial/furthertopics/message-triggers.rst

@@ -51,6 +51,11 @@ In order to get our workflow to trigger messages, we need to:
 
 * Refer to these messages in the ``[dependencies]`` section of our workflow.
 
+.. note::
+
+   The message will be recorded in the workflow's scheduler log.
+   See :ref:`scheduler logs.cylc message` for details of how messages appear.
+
 These outputs are then triggered during the running of the task.
 We can use these to manage tasks dependent on partially completed tasks.
 

src/user-guide/running-workflows/scheduler-log-files.rst

@@ -24,11 +24,44 @@ The information logged here includes:
 
    Workflow log files are primarily intended for human eyes. If you need
    to have an external system to monitor workflow events automatically, use:
-   
+
    * Event hooks (see :cylc:conf:`flow.cylc[scheduler][events]` and
      :cylc:conf:`flow.cylc[runtime][<namespace>][events]`).
    * The GraphQL interface (can be accessed via GraphiQL in the Cylc GUI).
    * The sqlite *workflow run database*
      (see :ref:`Workflow Run Databases`)
-     
+
    Rather than parse the log files.
+
+
+.. _scheduler Logs.Cylc message:
+
+Cylc Message
+^^^^^^^^^^^^
+
+The Scheduler Log also records messages sent by ``cylc message`` allowing you
+to add custom messages to this log.
+
+For example, if your task contained the following code:
+
+.. code-block:: shell
+
+   cylc message -- "ERROR:some_function failed."
+
+Your log should produce output similar to:
+
+.. code-block:: none
+
+   ERROR - [21491012T0410Z/mytask running job:01 flows:1] (received)some_function failed ERROR at 2023-04-14T11:36:35+01:00
+
+Severity levels are the same as those used by
+`Python's logger <https://docs.python.org/3/library/logging.html#logging-levels>`_:
+
+- CRITICAL
+- ERROR
+- WARNING
+- INFO
+- DEBUG
+
+Messages logged at "DEBUG" will only appear in the scheduler log if the
+workflow is played with ``cylc play --debug``.