tlo.logging.core module

exception InconsistentLoggedColumnsWarning

Bases: UserWarning

Warning raised when structured log entry has different columns from header.

initialise(add_stdout_handler: bool = True, simulation_date_getter: ~typing.Callable[[], str] = <function _mock_simulation_date_getter>, root_level: int = 30, stdout_handler_level: int = 10, formatter: ~logging.Formatter = <logging.Formatter object>) → None

Initialise logging system and set up root tlo logger.

Parameters:

  • add_stdout_handler – Whether to add a handler to output log entries to stdout.

  • simulation_date_getter – Zero-argument function returning simulation date as string in ISO format to use in log entries. Defaults to function returning a a fixed dummy date for use before a simulation has been initialised.

  • root_level – Logging level for root tlo logger.

  • formatter – Formatter to use for logging to stdout.

reset()

Reset global logging state to values at initial import.

set_output_file(log_path: ~pathlib.Path, formatter: ~logging.Formatter = <logging.Formatter object>) → FileHandler

Add file handler to logger.

Parameters:

log_path – Path for file.

Returns:

File handler object.

disable(level: int) → None

Disable all logging calls of specified level and below.

getLogger(name: str = 'tlo') → Logger

Returns a TLO logger of the specified name

class Logger(name: str, level: int = 20)

Bases: object

Logger for structured log messages output by simulation.

Outputs structured log messages in JSON format along with simulation date log entry was generated at. Log messages are associated with a string key and for each key the log message data is expected to have a fixed structure:

  • Collection like data (tuples, lists, sets) should be of fixed length.

  • Mapping like data (dictionaries, pandas series and dataframes) should have a fixed set of keys and the values should be of fixed data types.

The first log message for a given key will generate a ‘header’ log entry which records the structure of the message with subsequent log messages only logging the values for efficiency, hence the requirement for the structure to remain fixed.

HASH_LEN = 10
property level: int
property handlers: List[Handler]
addHandler(hdlr: Handler)
isEnabledFor(level: int) → bool
reset_attributes() → None

Reset logger attributes to an unset state

setLevel(level: int) → None
log(level: int, key: str, data: str | dict | list | set | tuple | DataFrame | Series, description: str | None = None) → None

Log structured data for a key at specified level with optional description.

Parameters:

  • level – Level the message is being logged as.

  • key – Logging key.

  • data – Data to be logged.

  • description – Description of this log type.

critical(key: str, data: LogData, description: str | None = None) → None
debug(key: str, data: LogData, description: str | None = None) → None
info(key: str, data: LogData, description: str | None = None) → None
warning(key: str, data: LogData, description: str | None = None) → None