Structlog Python

structlog Python

Produce one version-grounded event pipeline whose context lifetime, processor order, output ownership, event schema, and tests are explicit.

Boundary

Use this skill when the project uses structlog or the user explicitly requests it. Do not introduce structlog into a standard-library-only or Loguru-only task. Metrics, traces, OpenTelemetry collector pipelines, and logging-platform queries are outside scope unless the requested change is the Python structlog boundary. Preserve the application's established logging owner and event schema unless the task explicitly changes them.

Know the runtime model

A call follows this path:

bound context + call fields + event
                -> fresh event_dict
                -> processor 1 -> ... -> processor N
                -> exactly one terminal renderer/adapter
                -> wrapped logger / handler / stream

Read the object and event model whenever .bind(), processor return values, configuration caching, or output ownership is unclear.

Ordered workflow

1. Recover the event contract: stable event names, required keys, levels, timestamps, correlation fields, exceptions, redaction, and output consumer.
2. Inventory existing logging handlers/formatters, framework initialization, and foreign stdlib emitters. Choose one integration architecture.
3. Build shared processors in semantic order. Put one renderer or handoff last.
4. Configure at the composition root before application work or cached loggers.
5. Bind long-lived component data on returned loggers; clear and bind request/job context at its boundary.
6. Emit named events with structured keyword fields. Do not duplicate values in interpolated prose.
7. Test event dictionaries separately from final transport/rendering.

Choose by intent

Read the intent-to-API map before reaching for an unfamiliar helper or relying on an exact signature.

Canonical standalone pipeline

import logging

import structlog


def configure_logging(*, development: bool = False) -> None:
    renderer = (
        structlog.dev.ConsoleRenderer() if development else structlog.processors.JSONRenderer()
    )
    structlog.configure(
        processors=[
            structlog.contextvars.merge_contextvars,
            structlog.stdlib.add_log_level,
            structlog.processors.TimeStamper(fmt="iso", utc=True),
            structlog.processors.StackInfoRenderer(),
            structlog.processors.format_exc_info,
            renderer,
        ],
        wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
        logger_factory=structlog.WriteLoggerFactory(),
        cache_logger_on_first_use=True,
    )


log = structlog.get_logger("payments").bind(component="authorizer")
log.info("payment_authorized", payment_id="pay_123", amount_cents=2500)

get_logger() returns a proxy; the event dictionary is assembled and processed when a log method runs. WriteLoggerFactory writes a whole line atomically. Choose the factory that matches the application stream and renderer return type.

Choose exactly one integration architecture

Do not put JSONRenderer before ProcessorFormatter.wrap_for_formatter. Do not render once in structlog and again in a formatter. Read stdlib integration.

Processor and context rules

• Order filters before expensive enrichment when the selected logger makes that valid. Merge context before processors that consume those fields.
• A normal custom processor must return the event dictionary on every retained path. It may mutate it because structlog copied the call context first.
• Redact or omit secrets before any renderer or stdlib handoff. Never bind raw tokens, credentials, authorization headers, full request bodies, or unbounded objects.
• Keep one stable machine event name such as inventory_reservation_failed; put changing values in fields. Treat field names as an external contract.
• Use logger .bind() for data scoped to a returned logger. Use contextvars for data that follows the current execution context. These are different stores.
• In hybrid sync/async frameworks, test propagation across the actual boundary; contextvars can be isolated between execution mechanisms.

Read processor contracts and context lifecycle.

Failure routing

• Duplicate lines: inspect propagation, root/child handlers, repeated startup, and whether two layers render the same record.
• Missing foreign fields: verify the chosen formatter/adapter path and its foreign_pre_chain; do not assume all LogRecord extras survive.
• Missing exception detail: pass exc_info via .exception(...) or the intended signal and run an exception processor before rendering.
• Leaked request IDs: clear at unit-of-work start and test two sequential units.
• Changed configuration has no effect: inspect cached loggers and initialization order; do not repeatedly reset production global state as a workaround.
• Slow async code: measure the actual processor and I/O cost, then inspect the installed async methods and executor behavior before redesigning.

Version grounding and completion

Inspect project locks and run python scripts/inspect_structlog.py from the installed skill directory when names, signatures, async methods, renderer byte contracts, or integration helpers can drift. Read API grounding.

Do not declare completion until one output owner is evident; processor ordering and the terminal step are coherent; event keys, level filtering, exception shape, context cleanup, and secret exclusion are tested; foreign records and duplicate initialization are tested when applicable; and project checks pass or skipped evidence and consequences are reported.

References

• Event pipeline recipes
• Integration and test recipes
• Object and event model
• Intent-to-API map
• Processor contracts
• Standard-library integration
• Context lifecycle
• Testing structlog behavior
• API grounding