1.6. Status and Error Logging
Added in version 6.2.0.
SUNDIALS includes a built-in logging functionality which can be used to direct error messages, warning messages, informational output, and debugging output to specified files. This capability requires enabling both build-time and run-time options to ensure the best possible performance is achieved.
1.6.1. Enabling Logging
To enable logging, the CMake option SUNDIALS_LOGGING_LEVEL
must be
set to the maximum desired output level when configuring SUNDIALS. See the
SUNDIALS_LOGGING_LEVEL
documentation for the numeric values
corresponding to errors, warnings, info output, and debug output where errors <
warnings < info output < debug output < extra debug output. By default only
warning and error messages are logged.
Note
As of version 7.0.0, enabling MPI in SUNDIALS enables MPI-aware logging.
When SUNDIALS is built with logging enabled, then the default logger (stored in
the SUNContext
object) may be configured through environment variables
without any changes to user code. The available environment variables are:
SUNLOGGER_ERROR_FILENAME
SUNLOGGER_WARNING_FILENAME
SUNLOGGER_INFO_FILENAME
SUNLOGGER_DEBUG_FILENAME
These environment variables may be set to a filename string. There are two
special filenames: stdout
and stderr
. These two filenames will
result in output going to the standard output file and standard error file.
The different variables may all be set to the same file, or to distinct files,
or some combination there of. To disable output for one of the streams, then
do not set the environment variable, or set it to an empty string.
If SUNDIALS_LOGGING_LEVEL
was set at build-time to a level lower than
the corresponding environment variable, then setting the environment variable
will do nothing. For example, if the logging level is set to 2
(errors and
warnings), setting SUNLOGGER_INFO_FILENAME
will do nothing.
Warning
A non-default logger should be created and attached to the context object prior to any other SUNDIALS calls in order to capture all log events.
Error or warning logs are a single line output with an error or warning message
[level][rank][scope][label] message describing the error or warning
Informational or debugging logs are either a single line output with a comma-separated list of key-value pairs of the form
[level][rank][scope][label] key1 = value, key2 = value
or multiline output with one value per line for keys corresponding to a vector or array e.g.,
[level][rank][scope][label] y(:) =
y[0]
y[1]
...
In the example log outputs above, the values in brackets have the following meaning:
level
is the log level of the message and will beERROR
,WARNING
,INFO
, orDEBUG
rank
is the MPI rank the message was written from (0
by default or if SUNDIALS was built without MPI enabled)scope
is the message scope i.e., the name of the function from which the message was writtenlabel
provides additional context or information about the logging output e.g.,begin-step
,end-linear-solve
, etc.
Note
When extra debugging output is enabled, the output will include vector values
(so long as the N_Vector
used supports printing). Depending on the
problem size, this may result in very large logging files.
1.6.2. Logger API
The central piece of the Logger API is the SUNLogger
type:
-
type SUNLogger
An opaque pointer containing logging information.
When SUNDIALS is built with logging enabled, a default logging object is stored
in the SUNContext
object and can be accessed with a call to
SUNContext_GetLogger()
.
The enumerated type SUNLogLevel
is used by some of the logging
functions to identify the output level or file.
-
enum SUNLogLevel
The SUNDIALS logging level
-
enumerator SUN_LOGLEVEL_ALL
Represents all output levels
-
enumerator SUN_LOGLEVEL_NONE
Represents none of the output levels
-
enumerator SUN_LOGLEVEL_ERROR
Represents error-level logging messages
-
enumerator SUN_LOGLEVEL_WARNING
Represents warning-level logging messages
-
enumerator SUN_LOGLEVEL_INFO
Represents info-level logging messages
-
enumerator SUN_LOGLEVEL_DEBUG
Represents deubg-level logging messages
-
enumerator SUN_LOGLEVEL_ALL
The SUNLogger
class provides the following methods.
-
int SUNLogger_Create(SUNComm comm, int output_rank, SUNLogger *logger)
Creates a new
SUNLogger
object.- Arguments:
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_CreateFromEnv(SUNComm comm, SUNLogger *logger)
Creates a new
SUNLogger
object and opens the output streams/files from the environment variables:SUNLOGGER_ERROR_FILENAME SUNLOGGER_WARNING_FILENAME SUNLOGGER_INFO_FILENAME SUNLOGGER_DEBUG_FILENAME
-
int SUNLogger_SetErrorFilename(SUNLogger logger, const char *error_filename)
Sets the filename for error output.
- Arguments:
logger
– aSUNLogger
object.error_filename
– the name of the file to use for error output.
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_SetWarningFilename(SUNLogger logger, const char *warning_filename)
Sets the filename for warning output.
- Arguments:
logger
– aSUNLogger
object.warning_filename
– the name of the file to use for warning output.
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_SetInfoFilename(SUNLogger logger, const char *info_filename)
Sets the filename for info output.
- Arguments:
logger
– aSUNLogger
object.info_filename
– the name of the file to use for info output.
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_SetDebugFilename(SUNLogger logger, const char *debug_filename)
Sets the filename for debug output.
- Arguments:
logger
– aSUNLogger
object.debug_filename
– the name of the file to use for debug output.
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_QueueMsg(SUNLogger logger, SUNLogLevel lvl, const char *scope, const char *label, const char *msg_txt, ...)
Queues a message to the output log level.
- Arguments:
logger
– aSUNLogger
object.lvl
– the message log level (i.e. error, warning, info, debug).scope
– the message scope (e.g. the function name).label
– the message label.msg_txt
– the message text itself....
– the format string arguments
- Returns:
Returns zero if successful, or non-zero if an error occurred.
Warning
When compiling for ANSI C / C89 / C90 (and without compiler extensions), it is dangerous to pass any user input to this function because it falls back to using
sprintf
with a fixed buffer size.It is highly recommended to compile with C99 or newer if your compiler does not support
snprintf
through extensions.
-
int SUNLogger_Flush(SUNLogger logger, SUNLogLevel lvl)
Flush the message queue(s).
- Arguments:
logger
– aSUNLogger
object.lvl
– the message log level (i.e. error, warning, info, debug or all).
- Returns:
Returns zero if successful, or non-zero if an error occurred.
-
int SUNLogger_GetOutputRank(SUNLogger logger, int *output_rank)
Get the output MPI rank for the logger.
- Arguments:
logger
– aSUNLogger
object.output_rank
– [in,out] On input this is a pointer to an int, on output it points to the int holding the output rank.
- Returns:
Returns zero if successful, or non-zero if an error occurred.
1.6.3. Example Usage
As noted above, enabling logging must be done when configuring SUNDIALS by
setting the CMake option SUNDIALS_LOGGING_LEVEL
to the desired
logging level. When running a program with SUNDIALS logging enabled, a default
logger is created and attached to the SUNContext
instance at creation.
Environment variables or run-time functions can be used to determine where the
logging output is written. For example, consider the CVODE Roberts example, where
we can direct the informational output to the file sun.log
as follows
SUNDIALS_INFO_FILENAME=sun.log ./examples/cvode/serial/cvRoberts_dns
Alternatively, the following examples demonstrate how to use the logging interface via the C API:
examples/arkode/CXX_serial/ark_analytic_sys.cpp
examples/cvode/serial/cvAdvDiff_bnd.c
examples/cvode/parallel/cvAdvDiff_diag_p.c
examples/kinsol/CXX_parallel/kin_em_p.cpp
examples/kinsol/CUDA_mpi/kin_em_mpicuda.cpp
To assist with extracting informational logging data from output files the
tools
directory contains a Python module, suntools
, that provides
utilities for parsing log files. Some example scripts using the suntools
module are included in the tools
directory. For example, we can plot the
step size history from the CVODE Roberts problem with
./log_example.py sun.log