logrus package

logrus package

Better logging made easy with support for structlog and the standard logging module.

class BetterBoundLogger(logger, processors, context)[source]

Bases: BoundLogger

A better version of structlog’s standard BoundLogger.

Used to add additonal methods to the default BoundLogger.

Parameters:

  • logger (Any) –

  • processors (Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, bytearray, Tuple[Any, ...]]]]) –

  • context (Union[Dict[str, Any], Dict[Any, Any]]) –

bind(**new_values)[source]

Return a new logger with new_values added to the existing ones.

Parameters:

new_values (Any) –

Return type:

BetterBoundLogger

bind_fargs(fargs_map=None, **kwargs)[source]

Helper function for binding function arguments to logger.

These arguments are passed in as a mapping and then jsonified into a string.

Parameters:

  • fargs_map (Mapping[str, Any]) – A mapping of function arguments. We typically pass in locals() for this argument at the start of a function that contains log messages.

  • kwargs (Any) – Additional function arguments can be passed in as keyword arguments.

Return type:

BetterBoundLogger

new(**new_values)[source]

We override this function’s type signature _only_.

Parameters:

new_values (Any) –

Return type:

BetterBoundLogger

trace(event=None, *args, **kwargs)[source]

Log a new TRACE level message.

Parameters:

  • event (Union[str, Dict[str, Any]]) –

  • args (Any) –

  • kwargs (Any) –

Return type:

None

try_unbind(*keys)[source]

We override this function’s type signature _only_.

Parameters:

keys (str) –

Return type:

BetterBoundLogger

unbind(*keys)[source]

We override this function’s type signature _only_.

Parameters:

keys (str) –

Return type:

BetterBoundLogger

class Log(file, format='json', level=None)[source]

Bases: object

Log specification for a file or stream.

Parameters:

  • file (str) – The file to add log messages to (special values: stderr, stdout).

  • format (Literal['json', 'color', 'nocolor']) – The logging format (e.g. color or json).

  • level (Optional[Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']]) – The logging level. If this is not set, a reasonable default level is used depending on whether we are logging to a file or the console (e.g. stderr).

file
format = 'json'
level = None
Logger(name=None, **kwargs)[source]

Returns a structured logger.

This logger is capable of handling positional format arguments as well as keyword arguments and can be bound for context-specific logging.

Parameters:

  • name (str) – The name of the logger.

  • kwargs (Any) – These parameters will be bound to the returned logger.

Return type:

BetterBoundLogger

Returns:

A structlog logger with a few extra custom methods (e.g. logger.trace() and logger.bind_fargs()). See structlog’s documentation for more information:

https://www.structlog.org/en/stable/loggers.html

Warning

This logger should only be used for applications, NOT libraries.

get_default_logfile(stem)[source]

Returns full path to logfile using default directory locations.

Parameters:

stem (str) – The logfile’s final path component, without its suffix.

Return type:

Path

init_logging(*, logs=(Log(file='stderr', format='color', level=None),), verbose=0)[source]

Configure standard logging (for libraries) and structlog (for apps).

This function can be called multiple times but will do nothing if called with the same arguments and structlog is still configured (this latter check is mostly just needed for testing).

Parameters:

  • logs (Iterable[Log]) – This list of Log objects determines which logging handlers we configure and enable, what logging level we use for each handler, and what log message format we use for each handler.

  • verbose (int) –

    A non-negative integer. If greater than zero, this option affects the default logging level used when a Log object in logs does not have its level attribute set and causes additional values (e.g. PID, thread name) to be added to each log record. More precisely, the following rules apply to the verbose argument:

    if verbose >= 1…

    • The default log level is set to DEBUG instead of INFO.

    • We show microseconds in each log record’s timestamp instead of milliseconds.

    • The current PID and thread name are added to each log record.

    if verbose >= 2…

    • The line number, function name, module name, and function parameters [if the logger bound them by calling logger.bind_fargs()] are added to each log record.

    if verbose >= 3…

    • The default log level is set to TRACE instead of INFO.

Return type:

None

Note

If no ‘stderr’ or ‘stdout’ Log is found in logs, we add a default ‘stderr’ Log object to the list.

Submodules