From 4a123706b9619be3a1ba266fce5244d95a8524d4 Mon Sep 17 00:00:00 2001 From: Emily Howell Date: Thu, 16 Jan 2025 15:42:39 -0800 Subject: [PATCH] Adding some basic documentation of the new logging actions --- CHANGELOG.md | 1 + src/docs/sphinx/Actions/Actions.rst | 5 ++ src/docs/sphinx/Actions/Logging.rst | 85 +++++++++++++++++++++++++++++ src/docs/sphinx/Actions/index.rst | 1 + 4 files changed, 92 insertions(+) create mode 100644 src/docs/sphinx/Actions/Logging.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 0860caf66..2abd4c2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s - mfem@4.7 ### 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. diff --git a/src/docs/sphinx/Actions/Actions.rst b/src/docs/sphinx/Actions/Actions.rst index cd8dd73f3..d122f8a75 100644 --- a/src/docs/sphinx/Actions/Actions.rst +++ b/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. diff --git a/src/docs/sphinx/Actions/Logging.rst b/src/docs/sphinx/Actions/Logging.rst new file mode 100644 index 000000000..3437a6abd --- /dev/null +++ b/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" diff --git a/src/docs/sphinx/Actions/index.rst b/src/docs/sphinx/Actions/index.rst index 94b3e0d2b..09261aa31 100644 --- a/src/docs/sphinx/Actions/index.rst +++ b/src/docs/sphinx/Actions/index.rst @@ -16,6 +16,7 @@ Ascent Actions Pipelines Extracts Triggers + Logging Examples ExpressionsOverview expression_objects