Skip to main content

# Logging

Logging in Bean Machine is provided through the logging module in Python. It is recommended that users get familiar with the basics (logger, handler, levels, etc.) of this module before reading further.

## The Bean Machine Logger​

Upon importing the beanmachine module, the base logger "beanmachine" is initialized with two handlers such that it saves every message at or above the WARNING level to a local file and prints every message at or above the INFO level to the console. Users could control the information to be logged by replacing the default handlers with customized ones.

## Log Levels and Sub-Loggers​

To keep sufficient flexibility and ease of use, Bean Machine provides multiple sub-loggers under the base logger "beanmachine", such as "beanmachine.inference", "beanmachine.proposer", "beanmachine.world", etc. The name of the sub-logger indicates where the message is generated. Following the convention of Python logging, users could modify the logging levels of the base or sub-loggers as they need. Experienced users could also create customized filters based on the message itself.

In Bean Machine, we also offer a LogLevel class that maps the level name to its numeric value. The mapping is consistent with the logging module with additional levels inserted between INFO and DEBUG to differentiate different priorities in debugging. The following table provides the level description in details.

Level NameNumric ValueType of Information to Log
ERROR40Exceptions that are caught and handled with alternative solutions.
WARNING30Gradient calculation returns NaN or Inf.
Falling back to other proposer.
INFO20User-provided messages.
DEBUG_UPDATES16Node name and value
Proposed value
Proposal log update
Children log update
Node log update
Accept/Reject
Proposer type
Proposer properties
Step size
The dependency graph of random variables
DEBUG10All logging messages

The level INFO is reserved for users who would like to print any information from their model.

## For Developers​

Developers are welcome to add additional loggings following the above pattern. e.g. When a new proposer is added, its associated information should use the "beanmachine.proposer" logger. If a new logging level must be added, please set the level (LogLevel class) based on the type of information and the expected frequency of use (higher frequency -> higher level), and update the above table.