Adding some basic documentation of the new logging actions

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 - [email protected]
 
 ### Added
+- Added action options relating to logging functionality including `open_log`, `flush_log`, and `close_log` to toggle logging as well as `set_log_threshold` and `set_echo_threshold` to control logging and standard output levels.
 - Added a new unified logging infrastructure.
 - Added support for unstructured topologies with mixed elements types (for example, hexs and tets).
 - Added support for `pyramid` and `wedge` elements.

src/docs/sphinx/Actions/Actions.rst

@@ -19,6 +19,11 @@ The currently supported actions are:
 - ``add_triggers`` : adds a list of triggers that executes a set of actions based on a condition
 - ``save_info`` : saves ascent info result at the end of execution
 - ``save_session`` : saves expression session info at the end of execution (see :ref:`ExpressionsSaveSession`)
+- ``open_log`` : opens an assent logging stream and starts logging
+- ``flush_log`` : flushes the current logging stream to the output file
+- ``close_log`` : closes the current logging stream which stops logging
+- ``set_log_threshold`` : changes the threshold of messages recorded in the log file
+- ``set_echo_threshold`` : changes the threshold of messages displayed in standard output
 
 
 Ascent actions can be specified within the integration using Conduit Nodes and can be read in through a file.

src/docs/sphinx/Actions/Logging.rst

@@ -0,0 +1,85 @@
+.. ############################################################################
+.. # Copyright (c) Lawrence Livermore National Security, LLC and other Ascent
+.. # Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+.. # other details. No copyright assignment is required to contribute to Ascent.
+.. ############################################################################
+
+.. _Logging:
+
+Logging Overview
+================
+
+Ascent's logging options allow for control over the types of messages and information that are
+recorded and displayed. These functionalities are provided to allow for additional information to
+be recorded while the tool is being run in order to identify and diagnose any erroneous behavior. 
+
+The ``log`` options refer to the messages that are collected in a designated log stream and output
+to a designated log file. The ``echo`` options control the messages and types of information output
+to the standard output stream.
+
+Log Levels:
+- ``all`` : all messages will be recorded
+- ``debug`` : extra verbose output messages useful for diagnosing issues
+- ``info`` : normal system operations
+- ``warn`` : potential issues that could become a problem
+- ``error`` : significant issues that need to be addressed
+- ``none`` : no messages will be recorded.
+
+Opening Logs
+------------
+
+The ``open_log`` action can be used to start a logging stream. While there are no required keywords,
+options to set the output log file name and location using the ``file_pattern`` keyword as well as
+the logging threshold level using the ``log_threshold`` are available. The Default ``file_pattern``
+is ``ascent_log_output.yaml`` and the default ``log_threshold`` is ``debug``.
+
+.. code-block:: yaml
+
+  -
+    action: "open_log"
+    file_pattern: "ascent_log_out_{rank:05d}.yaml"
+    log_threshold: "debug"
+
+Flushing Logs
+-------------
+
+The ``flush_log`` action can be used to flush the current log streams to disk.
+
+.. code-block:: yaml
+
+  -
+    action: "flush_log"
+
+Closing Logs
+------------
+
+The ``close_log`` action can be used to close the current log stream.
+
+.. code-block:: yaml
+
+  -
+    action: "close_log"
+
+Setting the Logging Threshold
+-----------------------------
+
+The ``set_log_threshold`` action allows for the adjustment of the level of log messages being
+recorded to the current log stream.
+
+.. code-block:: yaml
+
+  -
+    action: "set_log_threshold"
+    log_threshold: "all"
+
+Setting the Echo Threshold
+-----------------------------
+
+The ``set_echo_threshold`` action allows for the adjustment of the level of log messages being
+recorded to the standard output stream.
+
+.. code-block:: yaml
+
+  -
+    action: "set_echo_threshold"
+    echo_threshold: "info"

src/docs/sphinx/Actions/index.rst

@@ -16,6 +16,7 @@ Ascent Actions
    Pipelines
    Extracts
    Triggers
+   Logging
    Examples
    ExpressionsOverview
    expression_objects