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 two CMake options: ACTS_ENABLE_LOG_FAILURE_THRESHOLD and ACTS_LOG_FAILURE_THRESHOLD. Depending on their configuration, the logging can operate in three modes:

1. No log failure threshold exists, log levels are informative only. This is the default behavior.
2. A compile-time log failure threshold is set. If ACTS_ENABLE_LOG_FAILURE_THRESHOLD=ON and ACTS_LOG_FAILURE_THRESHOLD=<LEVEL> are set, the logger code will compile in a fixed check if the log level of a particular message exceeds <LEVEL>. If that is the case, an exception of type Acts::Logging::ThresholdFailure is thrown.
3. A runtime log failure threshold is set. If only ACTS_ENABLE_LOG_FAILURE_THRESHOLD=ON and no fixed threshold level is set, the logger code will compile in a check of a global runtime threshold variable.

Note

If only ACTS_LOG_FAILURE_THRESHOLD is set, ACTS_ENABLE_LOG_FAILURE_THRESHOLD will be set automatically, i.e. a compile-time threshold will be set.

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 preprocessor settings ACTS_ENABLE_LOG_FAILURE_THRESHOLD and ACTS_LOG_FAILURE_THRESHOLD, this operations 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_LOG_FAILURE_THRESHOLD is unset, i.e. no compile-time threshold is used. Otherwise an exception is thrown.

Parameters

level

Log level above which exceptions will be thrown