Logging Thresholds

Detailed Description

Functions and classes to manage logging failure thresholds.

Generally, log levels in ACTS are only of informative value: even Acts::Logging::Level::ERROR and Acts::Logging::Level::FATAL will only print messages, and not terminate execution.

This is desirable in an experiment context, where jobs should not immediately terminate when ACTS encounters something that is logged as an error. In a test context, however, this behavior is not optimal: the tests should ensure in known configurations errors do not occur, or only in specific circumstances. To solve this, ACTS implements an optional log threshold mechanism.

The threshold mechanism is steered via the CMake option ACTS_ENABLE_LOG_FAILURE_THRESHOLD, so the logging operates in one of two modes:

1. No log failure threshold exists, log levels are informative only. This is the default behavior.
2. A runtime log failure threshold is available. With ACTS_ENABLE_LOG_FAILURE_THRESHOLD=ON the logger code compiles in a check against a global threshold variable, seeded from the ACTS_LOG_FAILURE_THRESHOLD environment variable and settable with Acts::Logging::setFailureThreshold. A message at or above it raises Acts::Logging::ThresholdFailure after it has been emitted. The threshold defaults to Acts::Logging::Level::MAX, so an enabled build with no threshold set behaves like a disabled one.

Classes
class	Acts::Logging::ScopedFailureThreshold
	Helper class that changes the failure threshold for the duration of its lifetime. More...
class	Acts::Logging::ThresholdFailure
	Custom exception class so threshold failures can be caught. More...

Functions
Level	Acts::Logging::getFailureThreshold ()
	Get debug level above which an exception will be thrown after logging.
void	Acts::Logging::setFailureThreshold (Level level)
	Set debug level above which an exception will be thrown after logging.

Function Documentation

getFailureThreshold()

Level Acts::Logging::getFailureThreshold

(

)

Get debug level above which an exception will be thrown after logging.

All messages with a debug level equal or higher than the return value of this function will cause an exception to be thrown after log emission.

Note

Depending on the preprocessor setting ACTS_ENABLE_LOG_FAILURE_THRESHOLD this operation is either constexpr or a runtime operation.

Returns

The log level threshold for failure

setFailureThreshold()

void Acts::Logging::setFailureThreshold

(

Level

level

)

Set debug level above which an exception will be thrown after logging.

All messages with a debug level equal or higher than level will cause an exception to be thrown after log emission.

Warning

The runtime log failure threshold is global state, therefore this function is not threadsafe. The intention is that this level is set once, before multi-threaded execution begins, and then not modified before the end of the job.

Note

This function is only available if ACTS_ENABLE_LOG_FAILURE_THRESHOLD is set. Otherwise an exception is thrown.

Parameters

level

Log level above which exceptions will be thrown