silkworm.logging

Structured logging interfaces and configuration helpers for Silkworm.

Log records accept arbitrary keyword context. The shared logger defaults to stderr and reads SILKWORM_LOG_LEVEL the first time it is requested.

type silkworm.logging.LogLevel = _NormalizedLogLevel | Literal['WARN', 'ERR', 'FATAL'] | None

class silkworm.logging.Logger

Bases: Protocol

Structured logger returned by get_logger() and Spider.log.

Keyword arguments become structured context fields on each record.

configure(*, handlers=None)

Replace the logger’s handlers with the supplied configurations.

Each handler mapping accepts sink, level, serialize, and colorize. A sink may be "stderr", "stdout", a filesystem path, or a writable text stream.

Parameters:

handlers (list[dict[str, object]] | None)

Return type:

None

bind(**context)

Return a logger carrying context on every subsequent record.

Parameters:

context (object)

Return type:

Logger

info(message, **context)

Emit an informational record with structured context.

Parameters:

• message (str)

• context (object)

Return type:

None

debug(message, **context)

Emit a diagnostic record with structured context.

Parameters:

• message (str)

• context (object)

Return type:

None

warning(message, **context)

Emit a warning record with structured context.

Parameters:

• message (str)

• context (object)

Return type:

None

error(message, **context)

Emit an error record with structured context.

Parameters:

• message (str)

• context (object)

Return type:

None

exception(message, **context)

Emit an error record including the active exception traceback.

Parameters:

• message (str)

• context (object)

Return type:

None

complete()

Flush all configured handlers.

Return type:

None

__init__(*args, **kwargs)

silkworm.logging.complete_logs()

Flush configured log handlers if logging has been initialized.

Return type:

None

silkworm.logging.get_logger(**context)

Return the shared structured logger, optionally bound to context.

The first call configures stderr output using SILKWORM_LOG_LEVEL. Bound context is copied into every record without mutating the shared base logger.

Parameters:

context (object)

Return type:

Logger

silkworm.logging.log_at_level(logger, level, message, **context)

Emit a log message at a caller-selected level.

Passing None intentionally suppresses the message. That escape hatch is useful for very noisy per-item paths, but should be used sparingly.

Parameters:

• logger (Logger)

• level (LogLevel)

• message (str)

• context (object)

Return type:

None