Skip to content

StructLogger

rn_forge.commons.logging.structlog

Structlog context binding over :class:AppLogger handlers.

Use :meth:~rn_forge.commons.logging.logger.AppLogger.get_logger directly for unstructured logging. :class:StructLogger binds context carried across a chain of calls while retaining the configured Rich, file, or JSON handlers. :func:otel_processor adds the active OpenTelemetry span's ids to every event. :func:redact_processor replaces secrets in every event.

Call :meth:~rn_forge.commons.logging.logger.AppLogger.initialize before the first :class:StructLogger log call (not necessarily before constructing one — the underlying logger is resolved lazily, on first use). The custom TRACE, SPAM, VERBOSE, NOTICE, and SUCCESS levels are available alongside the standard levels.

Requires the structlog extra — this module is not imported by rn_forge.commons's curated __init__.py, so import rn_forge.commons never requires it.

StructLogger(name, **initial_context)

Structlog front end over :class:AppLogger handlers.

Bound context and structured fields flow through the handlers configured by :meth:AppLogger.initialize.

Initialize :class:StructLogger, bound to name with initial_context.

structlog property

The underlying structlog.stdlib.BoundLogger.

bind(**new_context)

Return a new :class:StructLogger with new_context merged in.

critical(event, **kwargs)

Log event at the CRITICAL level with kwargs as structured fields.

debug(event, **kwargs)

Log event at the DEBUG level with kwargs as structured fields.

error(event, **kwargs)

Log event at the ERROR level with kwargs as structured fields.

info(event, **kwargs)

Log event at the INFO level with kwargs as structured fields.

new(**context)

Return a new :class:StructLogger with its context reset to context.

notice(event, **kwargs)

Log event at the NOTICE level with kwargs as structured fields.

spam(event, **kwargs)

Log event at the SPAM level with kwargs as structured fields.

success(event, **kwargs)

Log event at the SUCCESS level with kwargs as structured fields.

trace(event, **kwargs)

Log event at the TRACE level with kwargs as structured fields.

unbind(*keys)

Return a new :class:StructLogger with keys removed from its bound context.

verbose(event, **kwargs)

Log event at the VERBOSE level with kwargs as structured fields.

warning(event, **kwargs)

Log event at the WARNING level with kwargs as structured fields.

otel_processor(logger, method_name, event_dict)

Add the active OpenTelemetry span's ids to a structlog event dict.

Usable as a structlog processor in any chain.

Parameters:

Name Type Description Default
logger Any

The bound logger. Unused; part of the processor signature.

required
method_name str

The log method's name. Unused; part of the signature.

required
event_dict MutableMapping[str, Any]

The event dictionary, mutated in place and returned.

required

Returns:

Type Description
MutableMapping[str, Any]

event_dict, with trace_id (32 hex digits) and span_id (16 hex

MutableMapping[str, Any]

digits) set when a valid span is active, and unchanged when none is or

MutableMapping[str, Any]

when opentelemetry is not installed.

redact_processor(logger, method_name, event_dict)

Redact secrets in a structlog event dict.

Usable as a structlog processor in any chain, ahead of the renderer. Uses :meth:~rn_forge.commons.logging.redaction.RedactionPolicy.default.

Parameters:

Name Type Description Default
logger Any

The bound logger. Unused; part of the processor signature.

required
method_name str

The log method's name. Unused; part of the signature.

required
event_dict MutableMapping[str, Any]

The event dictionary. Not mutated.

required

Returns:

Type Description
MutableMapping[str, Any]

A redacted copy of event_dict.