Logging

SVS uses the excellent spdlog <https://github.com/gabime/spdlog> to support logging functionality. Logging levels (in order of increasing severity) are:

SVS Logging Levels

Log Level

Environment Variables

Descriptions

Trace

trace, TRACE

Tracing control flow through functions. Potentially extremely verbose.

Debug

debug, DEBUG

Verbose logging useful for debugging.

Info

info, INFO

Informative prints. This level is used by long-running process to provide periodic updates that progress is being made.

Warn (default)

warn, WARN

Diagnostic warnings about feature deprecation and other situations upon which the user may need to take action.

Error

error, ERROR

Hard program errors that which may be recoverable but likely require intervention from the user.

Critical

critical, CRITICAL

Critical errors that must be addressed and will likely lead to program termination.

Off

off, OFF

Disable loging.

Each logging level suppresses all diagnostic messages with a lower severity.

If SVS is compiled using -DSVS_INITIALIZE_LOGGER=YES, then the environment variable SVS_LOG_LEVEL can be used set the initial logging level. The string values for these variables is provided in the table above. For example, starting an SVS application with

SVS_LOG_LEVEL=debug ./application

Will initialize logging at the “debug” level, passing through messages with severity “debug” or higher. If this environment variable is not supplied or if it is the empty string, then the default logging level of “warn” will be used. Using any other string value for the environment variable results in unspecified behavior.

Hint

Generally, if SVS doesn’t understand a string value, it will default to “warn”. However, this behvaior should not be relied upon.

Logging Sinks

By default, log messages will be sent to stdout. This behavior can be changed if desired using the SVS_LOG_SINK environment variable. Values for this variable are shown below.

SVS Built-in Sinks

Sink

Enironment Variable

Description

stdout (default)

stdout

Send all log messages to stdout.

stderr

stderr

Send all log messages to stderr.

null

null

Send all log messages into the abyss (no logging whatsoever).

file

file:path/to/file

Write log messages to the file path/to/file. SVS will try to make all paths necessary to create the file. Insufficient permissions will result in an exception.

The contents of any existing file with the exact same path will be deleted.

For example, to send all log messages to a file ~/svslog.txt, an application linked with SVS could be started as

SVS_LOG_SINK=file:~/log.txt ./application

Note

Writes to a file are buffered and periodically flushed. If an SVS application is interrupted and that brings down the application, it is possible that some log messages could be lost.

Logging API

Both the C++ library and svs provide APIs for configuring logging, with the former accepting any instance of a std::shared_ptr<spdlog::logger>. Configuration made through the API superseded those configured using the environment variables.

Hint

Environment variable based initialization can be disabled by compiling SVS applications with -DSVS_INITIALIZE_LOGGER=NO. The global logger will then have a null sink and no messages will be logged.