Logging
Contents
5.2. Logging#
The Logging system of the Belle II Software is rather flexible and allows
extensive configurations. In the most simple case a call to
set_log_level
is all that is needed to set the minimum severity of
messages to be printed. However in addition to this global log level one can
set the log level for specific packages and even for individual modules
separately. The existing log levels are defined as
- class basf2.LogLevel#
Class for all possible log levels
- DEBUG#
The lowest possible severity meant for expert only information and disabled by default. In contrast to all other log levels DEBUG messages have an additional numeric indication of their priority called the
debug_level
to allow for different levels of verbosity.The agreed values for
debug_level
are0-9 for user code. These numbers are reserved for user analysis code and may not be used by any part of basf2.
10-19 for analysis package code. The use case is that a user wants to debug problems in analysis jobs with the help of experts.
20-29 for simulation/reconstruction code.
30-39 for core framework code.
Note
The default maximum debug level which will be shown when running
basf2 --debug
without any argument for--debug
is 10
- INFO#
Used for informational messages which are of use for the average user but not very important. Should be used very sparsely, everything which is of no interest to the average user should be a debug message.
- RESULT#
Informational message which don’t indicate an error condition but are more important than a mere information. For example the calculated cross section or the output file name.
Deprecated since version release-01-00-00: use
INFO
messages instead
- WARNING#
For messages which indicate something which is not correct but not fatal to the processing. This should not be used to make informational messages more prominent and they should not be ignored by the user but they are not critical.
- ERROR#
For messages which indicate a clear error condition which needs to be recovered. If error messages are produced before event processing is started the processing will be aborted. During processing errors don’t lead to a stop of the processing but still indicate a problem.
- basf2.set_log_level(level)[source]#
Sets the global log level which specifies up to which level the logging messages will be shown
- Parameters
level (basf2.LogLevel) – minimum severity of messages to be logged
- basf2.set_debug_level(level)[source]#
Sets the global debug level which specifies up to which level the debug messages should be shown
- Parameters
level (int) – The debug level. The default value is 100
- basf2.logging#
An instance of the
LogPythonInterface
class for fine grained control over all settings of the logging system.
5.2.1. Creating Log Messages#
Log messages can be created in a very similar way in python and C++. You can
call one of the logging functions like B2INFO
and supply the message as
string, for example
B2INFO("This is a log message of severity INFO")
In Python you can supply multiple arguments which will all be converted to string and concatenated to form the log message
for i in range(1,4):
B2INFO("This is log message number ", i)
which will produce
[INFO] This is log message number 1
[INFO] This is log message number 2
[INFO] This is log message number 3
This works almost the same way in C++ except that you need the <<
operator
to construct the log message from multiple parts
for(int i=1; i<4; ++i) {
B2INFO("This is log message " << i << " in C++");
}
Log Variables
New in version release-03-00-00.
However, the log system has an additional feature to include variable parts in a fixed message to simplify grouping of similar log messages: If a log message only differs by a number or detector name it is very hard to filter repeating messages. So we have log message variables which can be used to specify varying parts while having a fixed message.
In Python these can just be given as keyword arguments to the logging functions
B2INFO("This is a log message", number=3.14, text="some text")
In C++ this again almost works the same way but we need to specify the variables a bit more explicitly.
B2INFO("This is a log message" << LogVar("number", 3.14) << LogVar("text", "some text"));
In both cases the names of the variables can be chosen feely and the output should be something like
[INFO] This is a log message
number = 3.14
text = some text
Logging functions
To emit log messages from within Python we have these functions:
- basf2.B2DEBUG(debugLevel, message, *args, **kwargs)#
Print a
DEBUG
message. The first argument is thedebug_level
. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.
- basf2.B2INFO(message, *args, **kwargs)#
Print a
INFO
message. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.
- basf2.B2RESULT(message, *args, **kwargs)#
Print a
RESULT
message. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.Deprecated since version release-01-00-00: use
B2INFO()
instead
- basf2.B2WARNING(message, *args, **kwargs)#
Print a
WARNING
message. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.
- basf2.B2ERROR(message, *args, **kwargs)#
Print a
ERROR
message. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.
- basf2.B2FATAL(message, *args, **kwargs)#
Print a
FATAL
message. All additional positional arguments are converted to strings and concatenated to the log message. All keyword arguments are added to the function as Log Variables.Note
This also exits the programm with an error and is guaranteed to not return.
The same functions are available in C++ as macros once you included <framework/logging/Logger.h>
5.2.2. The Logging Configuration Objects#
The logging
object provides a more fine grained control over the
settings of the logging system and should be used if more than just a global
log level should be changed
- class basf2.LogPythonInterface#
Logging configuration (for messages generated from C++ or Python), available as a global
basf2.logging
object in Python. See alsobasf2.set_log_level()
andbasf2.set_debug_level()
.This class exposes a object called
logging
to the python interface. With this object it is possible to set all properties of the logging system directly in the steering file in a consistent manner This class also exposes theLogConfig
class as well as theLogLevel
andLogInfo
enums to make setting of properties more transparent by using the names and not just the values. To set or get the log level, one can simply do:>>> logging.log_level = LogLevel.FATAL >>> print("Logging level set to", logging.log_level) FATAL
This module also allows to send log messages directly from python to ease consistent error reporting throughout the framework
>>> B2WARNING("This is a warning message")
See also
For all features, see
b2logging.py
- property abort_level#
Attribute for setting/getting the
log level
at which to abort processing. Defaults toFATAL
but can be set to a lower level in rare cases.
- add_console([(bool)enable_color]) None : #
Write log output to console. (In addition to existing outputs). If
enable_color
is not specified color will be enabled if supported
- add_file((str)filename[, (bool)append=False]) None : #
Write log output to given file. (In addition to existing outputs)nn”
- add_json([(bool)complete_info=False]) None : #
Write log output to console, but format log messages as json objects for simplified parsing by other tools. Each log message will be printed as a one line JSON object.
New in version release-03-00-00.
- Parameters
complete_info (bool) – If this is set to True the complete log information is printed regardless of the
LogInfo
setting.
See also
- add_udp((str)hostname, (int)port) None : #
Send the log output as a JSON object to the given hostname and port via UDP.
New in version release-04-00-00.
- Parameters
See also
- property debug_level#
Attribute for getting/setting the debug level. If debug messages are enabled, their level needs to be at least this high to be printed. Defaults to 100.
- property enable_escape_newlines#
Enable or disable escaping of newlines in log messages to the console. If this is set to true than any newline character in log messages printed to the console will be replaced by a “n” to ensure that every log messages fits exactly on one line.
New in version release-04-02-00.
- property enable_python_logging#
Enable or disable logging via python. If this is set to true than log messages will be sent via
sys.stdout
. This is probably slightly slower but is useful when running in jupyter notebooks or when trying to redirect stdout in python to a buffer. This setting affects all log connections to the console.New in version release-03-00-00.
- enable_summary((bool)on) None : #
Enable or disable the error summary printed at the end of processing. Expects one argument whether or not the summary should be shown
- get_info((LogLevel)log_level) int : #
Get info to print for given log level.
- Parameters
log_level (basf2.LogLevel) – Log level for which to get the display info
- property log_level#
Attribute for setting/getting the current
log level
. Messages with a lower level are ignored.
- property log_stats#
Returns dictionary with message counters.
- property max_repetitions#
Set the maximum amount of times log messages with the same level and message text (excluding variables) will be repeated before it is suppressed. Suppressed messages will still be counted but not shown for the remainder of the processing.
This affects messages with the same text but different ref:Log Variables. If the same log message is repeated frequently with different variables all of these will be suppressed after the given amount of repetitions.
New in version release-05-00-00.
- package((str)package) LogConfig : #
Get the
LogConfig
for given package to set detailed logging pararameters for this package.>>> logging.package('svd').debug_level = 10 >>> logging.package('svd').set_info(LogLevel.INFO, LogInfo.LEVEL | LogInfo.MESSAGE | LogInfo.FILE)
- reset() None : #
Remove all configured logging outputs. You can then configure your own via
add_file()
oradd_console()
- set_info((LogLevel)log_level, (int)log_info) None : #
Set info to print for given log level. Should be an OR combination of
basf2.LogInfo
constants. As an example, to show only the level and text for all debug messages one could use>>> basf2.logging.set_info(basf2.LogLevel.DEBUG, basf2.LogInfo.LEVEL | basf2.LogInfo.MESSAGE)
- Parameters
log_level (LogLevel) – log level for which to set the display info
log_info (int) – Bitmask of
basf2.LogInfo
constants.
- set_package((str)package, (LogConfig)config) None : #
Set
basf2.LogConfig
for given package, see alsopackage()
.
- static terminal_supports_colors() bool : #
Returns true if the terminal supports colored output
- zero_counters() None : #
Reset the per-level message counters.
- class basf2.LogConfig#
Defines logging settings (log levels and items included in each message) for a certain context, e.g. a module or package.
See also
- property abort_level#
set or get the severity which causes program abort
- property debug_level#
set or get the current debug level
- get_info((LogLevel)log_level) int : #
get the current bitmask of which parts of the log message will be printed for a given log level
- property log_level#
set or get the current log level
- set_abort_level((LogLevel)abort_level) None : #
Set the severity which causes program abort.
This can be set to a
LogLevel
which will cause the processing to be aborted if a message with the given level or higher is encountered. The default isFATAL
. It cannot be set any higher but can be lowered.
- set_debug_level((int)debug_level) None : #
Set the maximum debug level to be shown. Any messages with log level
DEBUG
and a larger debug level will not be shown.
- set_info((LogLevel)log_level, (int)log_info) None : #
set the bitmask of LogInfo members to show when printing messages for a given log level
- set_log_level((LogLevel)log_level) None : #
Set the minimum log level to be shown. Messages with a log level below this value will not be shown at all.
- class basf2.LogInfo#
The different fields of a log message.
These fields can be used as a bitmask to configure the appearance of log messages.
- LEVEL#
The severity of the log message, one of
basf2.LogLevel
- MESSAGE#
The actual log message
- MODULE#
The name of the module active when the message was emitted. Can be empty if no module was active (before/after processing or outside of the normal event loop)
- PACKAGE#
The package the code that emitted the message belongs to. This is empty for messages emitted by python scripts
- FUNCTION#
The function name that emitted the message
- FILE#
The filename containing the code emitting the message
- LINE#
The line number in the file emitting the message