request-correlation

Skill: request-correlation

Core stance

Every request or job must produce a traceable log story.

A single correlation ID must propagate through:

• HTTP handlers
• service functions
• outbound HTTP calls
• background jobs and async tasks

The correlation ID must appear automatically in logs.

Infrastructure vs. convention: Some rules are wired once at app startup (middleware, logging config, HTTP client factory). Others are conventions followed everywhere (raise don't log in services, never pass correlation as a function argument). Keep them separate in your mental model -- the infrastructure makes the conventions effortless.

Canonical locations

Correlation infrastructure must live in predictable modules.

Use:

{pkg_name}/observability/correlation.py
{pkg_name}/observability/logging.py

Do not duplicate correlation logic elsewhere.

Rules

1. Wire correlation at entrypoints

Entrypoints include HTTP requests, background job workers, CLI tasks, and async task roots.

For HTTP requests, use a functional middleware to read x-request-id if present, otherwise generate one, then set it into context:

import uuid
from fastapi import Request
from {pkg_name}.observability.correlation import correlation_id

@app.middleware("http")
async def correlation_middleware(request: Request, call_next):
    cid = request.headers.get("x-request-id") or str(uuid.uuid4())
    correlation_id.set(cid)
    response = await call_next(request)
    response.headers["x-request-id"] = cid
    return response

Prefer @app.middleware("http") over BaseHTTPMiddleware — the class-based approach can swallow exceptions and interfere with streaming responses.

For job workers and CLI entrypoints, set correlation_id before executing the task -- either from a passed value or a freshly generated one.

2. Store correlation in contextvars

Correlation must live in a contextvars.ContextVar.

Never store it on request objects or pass it through every function argument.