Choosing a Logging Library for FastAPI

The exact problem this page solves: picking and wiring a logging library so a concurrent, async FastAPI service emits flat JSON with per-request context that never leaks between requests. It is written for backend engineers and SREs who already have a FastAPI service running and now need its logs to be queryable and correlatable in production. It is part of the comparison in structlog vs Loguru vs Standard Library Logging and the broader Modern Python Logging Libraries Deep Dive. FastAPI's async model raises the stakes for context isolation, so the right answer leans heavily on contextvars.

The decision matters more in FastAPI than in a synchronous WSGI app. Under asyncio, a single worker process interleaves many in-flight requests on one event loop, so any per-request state stored in a place that is shared across tasks, such as a module global or thread-local, will be observed by the wrong request. The libraries that scope cleanly here are the ones built on contextvars, because each task receives an isolated copy of the context at creation — the mechanism explained in using contextvars for request tracing. That single property is why this page recommends structlog's processor pipeline as the default for FastAPI, with Loguru's sink-based configuration as a reasonable alternative when its built-in rotation and rich tracebacks outweigh flat-output and context-composition concerns.

Prerequisites

Install FastAPI, an ASGI server, and both candidate libraries with pinned ranges so the examples reproduce.

pip install "fastapi>=0.110,<1.0" "uvicorn>=0.29,<1.0" \
            "structlog>=24.1.0,<26.0.0" "loguru>=0.7.0,<0.8.0"

Useful environment variables for switching renderers without code changes:

export LOG_LEVEL=INFO       # filtering threshold
export LOG_RENDERER=json    # "json" in prod, "console" for local dev

Python 3.10 or newer is assumed, mainly because contextvars propagation through asyncio.TaskGroup and third-party middleware is well settled there.

How each library scopes request context

Every other difference between the three candidates — output format, configuration style, traceback richness — is recoverable with a few lines of glue. Context scoping is not, so it should drive the decision.

The standard library has no concept of request scope at all. A LoggerAdapter carries fixed extras, and a custom Filter can inject fields into every record, but the value has to come from somewhere: if that somewhere is a threading.local, it is wrong under asyncio, because many tasks share one thread and therefore one thread-local. The correct standard-library pattern is a module-level ContextVar read by a filter, which works but leaves you owning the plumbing — the approach detailed in structured logging with the Python standard library and configuring logging with dictConfig.

structlog ships that plumbing as a first-class feature. structlog.contextvars.bind_contextvars writes into a contextvar-backed dict, and the merge_contextvars processor folds it into every event as flat keys. Because asyncio copies the context when a task is created, a value bound in middleware is visible to the handler, to its dependencies, and to any task those spawn, while remaining invisible to concurrently running requests. That composition — binding at several levels and merging once at render time — is covered in binding context variables in structlog.

Loguru offers logger.contextualize(**kwargs), a context manager that is also contextvar-backed, so it is genuinely async-safe. The difference is compositional rather than correctness-based: contextualized values land in the record's extra dict, which serializes as a nested record.extra object rather than flat top-level keys, and the context manager shape does not fit a middleware that binds incrementally as a request progresses. Loguru's real advantages lie elsewhere — file rotation and retention without extra handlers, and enqueue=True for non-blocking dispatch. In a containerized service that writes JSON to stdout, those advantages are largely neutralized by the platform, which is why the recommendation lands on structlog. If your service is a small worker writing files on a host, the trade runs the other way, as weighed in Loguru vs structlog for microservices.

Implementation

The recommended setup uses structlog because its contextvars integration aligns exactly with how asyncio scopes state per request. The walkthrough has four parts: configure once, bind in middleware, unify the server loggers, and keep the sink off the loop.

1. Configure structlog at import time. Run configuration in a module imported before the app starts. Choose the final renderer from an environment variable so production gets JSON and local development gets colorized console output. Setting a filtering bound logger here means sub-threshold calls are dropped before any processor runs, which matters on a hot request path; the level taxonomy behind that threshold is covered in log levels and severity mapping.

import logging
import os
import structlog

def configure_logging() -> None:
    level = getattr(logging, os.getenv("LOG_LEVEL", "INFO"))
    renderer = (
        structlog.processors.JSONRenderer()
        if os.getenv("LOG_RENDERER", "json") == "json"
        else structlog.dev.ConsoleRenderer()
    )
    structlog.configure(
        processors=[
            structlog.contextvars.merge_contextvars,   # pull in request context
            structlog.processors.add_log_level,
            structlog.processors.TimeStamper(fmt="iso"),
            structlog.processors.StackInfoRenderer(),
            structlog.processors.format_exc_info,       # render exceptions safely
            renderer,
        ],
        wrapper_class=structlog.make_filtering_bound_logger(level),
        cache_logger_on_first_use=True,                 # avoid per-call rebuild
    )

2. Bind request-scoped context in middleware. A single HTTP middleware clears any prior context, binds a request id and route, and lets it fall out of scope on the way out. Because bind_contextvars writes to a contextvar, each concurrent request sees only its own values. Echoing the id back on the response header lets a client or gateway correlate a failure report with the exact log lines.

import uuid
import structlog
from fastapi import FastAPI, Request

configure_logging()
app = FastAPI()
log = structlog.get_logger("app")

@app.middleware("http")
async def bind_request_context(request: Request, call_next):
    structlog.contextvars.clear_contextvars()
    request_id = request.headers.get("x-request-id", str(uuid.uuid4()))
    structlog.contextvars.bind_contextvars(
        request_id=request_id,
        method=request.method,
        path=request.url.path,
    )
    log.info("request_started")
    response = await call_next(request)
    log.info("request_finished", status_code=response.status_code)
    response.headers["x-request-id"] = request_id
    return response

@app.get("/orders/{order_id}")
async def get_order(order_id: str):
    # No need to pass request_id; it is already in the context.
    log.info("order_fetched", order_id=order_id)
    return {"order_id": order_id}

Use the route template (request.scope.get("route")) rather than the raw path if you plan to aggregate by endpoint — /orders/ORD-1 and /orders/ORD-2 are different paths but the same route, and unbounded path values behave like a high-cardinality label. If the service is also traced, bind the trace and span ids in the same middleware so logs join to spans, the correlation pattern described in adding trace IDs to log records and produced automatically when setting up OpenTelemetry in FastAPI.

3. Unify uvicorn and gunicorn loggers. uvicorn and gunicorn log through the standard library, so without this step you get two formats in one stream and a broken parse in your collector. Route those foreign records through the same renderer with structlog.stdlib.ProcessorFormatter, and start uvicorn with log_config=None so its default handlers do not double-format.

import logging
import structlog

def install_stdlib_bridge() -> None:
    formatter = structlog.stdlib.ProcessorFormatter(
        foreign_pre_chain=[
            structlog.contextvars.merge_contextvars,
            structlog.processors.add_log_level,
            structlog.processors.TimeStamper(fmt="iso"),
        ],
        processors=[
            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
            structlog.processors.JSONRenderer(),
        ],
    )
    handler = logging.StreamHandler()
    handler.setFormatter(formatter)
    root = logging.getLogger()
    root.handlers = [handler]
    root.setLevel(logging.INFO)
    # uvicorn loggers propagate to root once their own handlers are cleared.
    for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
        lg = logging.getLogger(name)
        lg.handlers = []
        lg.propagate = True

# Run with: uvicorn main:app --log-config=/dev/null
# or pass log_config=None when calling uvicorn.run(...)

foreign_pre_chain is the part teams miss: it applies to records that did not originate in structlog, which is exactly what uvicorn access logs and third-party library output are. Including merge_contextvars there means a database driver's warning emitted during a request still carries that request's request_id.

4. Keep the sink off the event loop. With stdout as the sink, a write is a fast syscall and the loop barely notices. A rotating file or a network sink is a different matter: the write runs inline on the loop thread and its latency is added to every request currently awaiting. Wrap the handler in a QueueHandler/QueueListener pair, as in non-blocking logging with QueueHandler, so the loop only pays for an in-memory put.

import atexit
import logging
import queue
from logging.handlers import QueueHandler, QueueListener

def install_queue_sink(target: logging.Handler) -> None:
    log_queue: queue.Queue = queue.Queue(-1)   # unbounded; watch depth in prod
    root = logging.getLogger()
    root.handlers = [QueueHandler(log_queue)]  # loop thread only enqueues
    listener = QueueListener(log_queue, target, respect_handler_level=True)
    listener.start()                           # writes happen on this thread
    atexit.register(listener.stop)             # drain before the process exits

If you prefer Loguru instead, the equivalent of step 2 is logger.contextualize(request_id=...) wrapped around call_next, the equivalent of step 3 is an InterceptHandler on the root logger, and step 4 collapses into logger.add(sys.stdout, serialize=True, enqueue=True). The trade-off favoring structlog for async FastAPI is that merge_contextvars composes naturally with the per-task context model and produces flat keys, whereas Loguru's strengths matter less when logs ship to stdout in a container.

Two operational details often bite teams here. First, gunicorn-managed uvicorn workers each import the application module, so configure_logging() runs once per worker, which is correct; do not try to share a single configured logger across workers. Second, when you scale to multiple workers, prefer logging to stdout and letting the platform aggregate, rather than each worker writing the same file, because concurrent file writes from separate processes interleave unpredictably unless every sink serializes through one writer. With stdout JSON and a collector, the multi-worker case needs no special handling at all, which is another reason the recommended setup renders to a stream rather than a file.

Configuration options

Verification

Send two concurrent requests with distinct request ids and confirm the context does not bleed. Each request should produce its own request_id on every line.

curl -H "x-request-id: req-aaa" localhost:8000/orders/ORD-1 &
curl -H "x-request-id: req-bbb" localhost:8000/orders/ORD-2 &
wait

Expected Output:

{"request_id": "req-aaa", "method": "GET", "path": "/orders/ORD-1", "event": "request_started", "level": "info", "timestamp": "2026-06-19T09:20:11.001Z"}
{"request_id": "req-bbb", "method": "GET", "path": "/orders/ORD-2", "event": "request_started", "level": "info", "timestamp": "2026-06-19T09:20:11.002Z"}
{"request_id": "req-aaa", "method": "GET", "path": "/orders/ORD-1", "order_id": "ORD-1", "event": "order_fetched", "level": "info", "timestamp": "2026-06-19T09:20:11.003Z"}
{"request_id": "req-bbb", "method": "GET", "path": "/orders/ORD-2", "order_id": "ORD-2", "event": "order_fetched", "level": "info", "timestamp": "2026-06-19T09:20:11.004Z"}

Every line carries the correct, isolated request_id, which is the definitive sign that contextvars scoping is working under concurrency. Two lines are visibly interleaved between requests, which is what proves the test actually exercised concurrency rather than running serially.

Make it a regression test so the property survives refactoring. FastAPI's TestClient is synchronous, so drive the app with an async client and assert on captured output:

import json
import httpx
import pytest
from main import app

@pytest.mark.asyncio
async def test_request_ids_do_not_leak(capsys):
    transport = httpx.ASGITransport(app=app)
    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
        await c.get("/orders/ORD-1", headers={"x-request-id": "req-aaa"})
        await c.get("/orders/ORD-2", headers={"x-request-id": "req-bbb"})

    lines = [json.loads(l) for l in capsys.readouterr().out.splitlines() if l]
    for line in lines:                       # each line's ids must agree
        assert line["request_id"] == f"req-{'aaa' if 'ORD-1' in line['path'] else 'bbb'}"

Expected Output:

1 passed in 0.34s

A final sanity check is that an access log line from uvicorn is valid JSON with the same keys as your application lines. If curl -s localhost:8000/orders/ORD-1 | head -1 yields JSON but the server's own access line does not, step 3 has not taken effect.

Common mistakes

Error signature: every log line shows the same request_id under load. Root cause: binding context to a module global or thread-local instead of a contextvar, or forgetting clear_contextvars at the start of the middleware. Remediation: call clear_contextvars() then bind_contextvars(...) at the top of an HTTP middleware so each task starts clean and isolated. The thread-local variant is subtle because it is correct in a synchronous WSGI app and only fails once tasks share a thread, as explained in context variables and thread safety.

Error signature: uvicorn access logs print as plain text alongside your JSON. Root cause: uvicorn's default logging config is still active. Remediation: start uvicorn with log_config=None (or --log-config=/dev/null), clear the uvicorn loggers' handlers, and set propagate = True so they reach your root handler.

Error signature: latency spikes and event-loop stalls during bursts. Root cause: a synchronous file or network sink runs on the event loop. Remediation: wrap the stdlib handler in QueueHandler/QueueListener, or use Loguru with enqueue=True, so serialization and I/O move to a background worker.

Error signature: context is present in the middleware but empty inside a background task. Root cause: the work was handed to a thread executor or a BackgroundTasks callback that ran after the middleware unwound and cleared the context. Remediation: capture the values you need before scheduling (structlog.contextvars.get_contextvars()), pass them explicitly, and re-bind them at the top of the background callable.

Related

• structlog vs Loguru vs Standard Library Logging — the full comparison this FastAPI decision is drawn from.
• Binding context variables in structlog — deeper treatment of the binding API used in the middleware above.
• Using contextvars for request tracing — the underlying mechanism, without any library on top.
• Async and non-blocking logging with Loguru enqueue — what the Loguru path looks like when the sink must stay off the loop.
• structlog JSON logging in Django — the same pipeline applied to a synchronous, middleware-driven framework.

Frequently Asked Questions