Logging

matchbox.common.logging

Logging utilities.

Classes:

• LoggingPlugin –

  Protocol for logging plugins that can be registered with Matchbox.

• PrefixedLoggerAdapter –

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

• ASIMFormatter –

  Format logging with ASIM standard fields.

Functions:

• get_logging_plugins –

  Retrieve logging plugins registered in the ‘matchbox.logging’ entry point.

• build_progress_bar –

  Create a progress bar.

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.

LoggingPlugin

Bases: Protocol

Protocol for logging plugins that can be registered with Matchbox.

Methods:

• get_trace_context –

  Get trace context information for logging.

• get_metadata –

  Get additional fields for logging.

get_trace_context

get_trace_context() -> tuple[str | None, str | None]

Get trace context information for logging.

get_metadata

get_metadata() -> dict[str, Any]

Get additional fields for logging.

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)

ASIMFormatter

ASIMFormatter(
    fmt=None, datefmt=None, style="%", validate=True
)

Bases: Formatter

Format logging with ASIM standard fields.

Methods:

• format –

  Convert logs to JSON including basic ASIM fields.

Attributes:

• plugins –
• event_severity (dict[str, str]) –

  Event severity level lookup.

plugins instance-attribute

plugins = get_logging_plugins()

event_severity cached property

event_severity: dict[str, str]

Event severity level lookup.

format

format(record)

Convert logs to JSON including basic ASIM fields.

get_logging_plugins

get_logging_plugins()

Retrieve logging plugins registered in the ‘matchbox.logging’ entry point.

build_progress_bar

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

Create a progress bar.