1.7. 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.7.1. Enabling Logging

To enable logging, the CMake option SUNDIALS_LOGGING_LEVEL must be set to a value greater than 0 when configuring SUNDIALS. This option specifies the maximum desired output level. See the documentation entry for SUNDIALS_LOGGING_LEVEL for the numeric values correspond to errors, warnings, info output, and debug output where errors < warnings < info output < debug output < extra debug output. More details in regards to configuring SUNDIALS with CMake can be found in §1.1.

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.

Warning

A non-default logger should be created prior to any other SUNDIALS calls in order to capture all log events.

Note

If SUNDIALS_LOGGING_LEVEL was set to 1 (corresponding to error-level output) at build-time, then setting the environment variable SUNLOGGER_INFO_FILENAME will do nothing.

Note

Extra debugging output is turned on by setting SUNDIALS_LOGGING_LEVEL to 5. This extra output includes vector-values (so long as the N_Vector used supports printing).

1.7.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

The SUNLogger class provides the following methods.

int SUNLogger_Create(SUNComm comm, int output_rank, SUNLogger *logger)

Creates a new SUNLogger object.

Arguments:

  • comm – the MPI communicator to use, if MPI is enabled, otherwise can be SUN_COMM_NULL.

  • output_rank – the MPI rank used for output (can be -1 to print to all ranks).

  • logger – [in,out] On input this is a pointer to a

    SUNLogger, on output it will point to a new SUNLogger instance.

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
Arguments:

  • comm – the MPI communicator to use, if MPI is enabled, otherwise can be SUN_COMM_NULL.

  • logger – [in,out] On input this is a pointer to a

    SUNLogger, on output it will point to a new SUNLogger instance.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_SetErrorFilename(SUNLogger logger, const char *error_filename)

Sets the filename for error output.

Arguments:

  • logger – a SUNLogger 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 – a SUNLogger 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 – a SUNLogger 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 – a SUNLogger 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 – a SUNLogger 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 – a SUNLogger 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 – a SUNLogger 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.

int SUNLogger_Destroy(SUNLogger *logger)

Free the memory for the SUNLogger object.

Arguments:

  • logger – a pointer to the SUNLogger object.

Returns:

  • Returns zero if successful, or non-zero if an error occur.

1.7.3. Example Usage

As previously mentioned, if it is enabled at build time, there is a default SUNLogger attached to a SUNContext instance when it is created. This logger can be configured using the environment variables, e.g.,

SUNDIALS_INFO_FILENAME=stdout ./examples/cvode/serial/cvKrylovDemo_ls

SUNDIALS also includes several example codes that 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