Logging

matchbox.common.logging

Logging utilities.

Classes:

• PrefixedLoggerAdapter –

  A logger adapter that supports adding a prefix enclosed in square brackets.

Functions:

• build_progress_bar –

  Create a progress bar.

• profile_time –

  Decorator to profile running time of functions and methods using logger.

• log_mem_usage –

  Log current memory usage for this process.

• get_formatter –

  Retrieve plugin registered in ‘matchbox.logging’ entry point, or fallback.

• configure_celery_logging –

  Configure root and celery loggers to use matchbox formatting.

Attributes:

• LogLevelType –

  Type for all Python log levels.

• logger (Final[PrefixedLoggerAdapter]) –

  Logger for Matchbox.

• console (Final[Console]) –

  Console for Matchbox.

LogLevelType module-attribute

LogLevelType = Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']

Type for all Python log levels.

logger module-attribute

logger: Final[PrefixedLoggerAdapter] = PrefixedLoggerAdapter(getLogger('matchbox'), {})

Logger for Matchbox.

Used for all logging in the Matchbox library.

Allows passing a prefix to any logging call.

Examples:

log_prefix = f"Model {name}"
logger.debug("Inserting metadata", prefix=log_prefix)
logger.debug("Inserting data", prefix=log_prefix)
logger.info("Insert successful", prefix=log_prefix)

console module-attribute

console: Final[Console] = Console()

Console for Matchbox.

Used for any CLI utilities in the Matchbox library.

PrefixedLoggerAdapter

Bases: LoggerAdapter

A logger adapter that supports adding a prefix enclosed in square brackets.

This adapter allows passing an optional prefix parameter to any logging call without modifying the underlying logger.

Methods:

• process –

  Process the log message, adding a prefix if provided.

process

process(msg: Any, kwargs: dict[str, Any]) -> tuple[Any, dict[str, Any]]

Process the log message, adding a prefix if provided.

Parameters:

• msg

  (Any) –

  The log message

• kwargs

  (dict[str, Any]) –

  Additional arguments to the logging method

Returns:

• tuple[Any, dict[str, Any]] –

  Tuple of (modified_message, modified_kwargs)

build_progress_bar

build_progress_bar(console_: Console | None = None) -> Progress

Create a progress bar.

profile_time

profile_time(logger: PrefixedLoggerAdapter = logger, level: int = INFO, prefix: str | None = 'Profiling', attr: str | None = None, kwarg: str | None = None) -> Callable[[Callable[P, T]], Callable[P, T]]

Decorator to profile running time of functions and methods using logger.

Parameters:

• logger

  (PrefixedLoggerAdapter, default: logger ) –

  The logger to use.

• level

  (int, default: INFO ) –

  The level to use to log the profiling information. It defaults to INFO.

• prefix

  (str | None, default: 'Profiling' ) –

  Prefix to pass to the logged message.

• attr

  (str | None, default: None ) –

  Attribute name to extract from instantiated class.

• kwarg

  (str | None, default: None ) –

  Argument name to extract from function call.

attr should be used when we want to include some class atribute in the log, e.g. node name in Source. kwarg should be used when we want to include the value passed to some function argument, e.g. path in set_data. This will only work if the argument is passed to the function as a kwarg, and not a positional argument.

log_mem_usage

log_mem_usage(logger: PrefixedLoggerAdapter = logger, level: int = INFO, prefix: str | None = 'Profiling') -> None

Log current memory usage for this process.

get_formatter

get_formatter() -> Formatter

Retrieve plugin registered in ‘matchbox.logging’ entry point, or fallback.

configure_celery_logging

configure_celery_logging(level: int = INFO) -> None

Configure root and celery loggers to use matchbox formatting.

This should also get logging from matchbox code running in forked processes.