python-structlog-logging

Logging with structlog

Logs are the cheapest observability. With structlog, every log line is a structured event with key=value fields — searchable in Loki, Datadog, CloudWatch without regex acrobatics. Per-request context (correlation_id, user_id) propagates automatically via contextvars, so call sites stay focused on what just happened rather than on plumbing.

This skill encodes the canonical setup: structlog primary, stdlib bridge for libraries, env-driven console renderer for local dev and JSON for everywhere else.

When to use this skill

• Setting up logging in a new service (app/common/logging.py, middleware)
• Writing log calls in any code (log.info("order.placed", order_id=...))
• Adding fields to a per-request context (user_id, tenant_id)
• Diagnosing why library logs (SQLAlchemy, httpx) aren't appearing in the structured stream

The rules

1. Configure structlog once, in configure_logging(env=...)

# app/common/logging.py — shape; full version in examples/logging_setup.py
correlation_id_var: Final[contextvars.ContextVar[str]] = contextvars.ContextVar(
    "correlation_id", default="-",
)


def configure_logging(*, env: str) -> None:
    is_local = env == "local"
    renderer = (
        structlog.dev.ConsoleRenderer(colors=True) if is_local
        else structlog.processors.JSONRenderer()
    )
    # Configure structlog with: contextvars merge, correlation_id, ISO timestamp,
    # log level, exc_info, then the renderer.
    # Bridge stdlib logging through structlog.stdlib.ProcessorFormatter so
    # library logs (SQLAlchemy, httpx, uvicorn) join the structured stream.
    ...

Called once in provide_app(config):

def provide_app(config: AppConfig) -> FastAPI:
    configure_logging(env=config.ENV)
    ...

2. correlation_id_var is a module-level ContextVar

Why ContextVar: it's the only way to propagate per-request data through async code without passing it as an arg. Async tasks inherit the contextvar from their parent task automatically.