fastapi-reqid

FastAPI Request ID is a middleware solution designed for request ID propagation and tracing across microservices within FastAPI applications. This tool enhances observability in microservice architectures by ensuring that each request is associated with a unique identifier, facilitating easier tracking and debugging.

Key Features

• Middleware Integration: Simple integration into FastAPI applications. Easily add middleware with default settings or customize options such as header name and ID generation logic.

from fastapi import FastAPI
from fastapi_reqid import RequestIDMiddleware

app = FastAPI()

# Add middleware with default settings
app.add_middleware(RequestIDMiddleware)

# Or customize it
app.add_middleware(
    RequestIDMiddleware,
    header_name="X-Correlation-ID",  # Custom header name
    generator=lambda: str(uuid.uuid4())  # Custom ID generator
)

• Accessing Request ID: Retrieve the generated request ID easily within route handlers, either through the request state or a convenient helper function.

from fastapi import Request
from fastapi_reqid import get_request_id

@app.get("/")
async def root(request: Request):
    # Access via request.state
    request_id = request.state.request_id

    # Or use the context helper
    request_id = get_request_id()

    return {"request_id": request_id}

• HTTP Client Decorators: Automatically attach request IDs to outgoing HTTP requests using decorators compatible with popular HTTP clients like httpx, aiohttp, and requests.

Example for httpx

from fastapi import Request
from fastapi_reqid import inject_httpx_requestid

@app.get("/external")
@inject_httpx_requestid
async def call_external(request: Request):
    client = request.state.httpx_client
    response = await client.get("https://api.example.com")
    return response.json()

• Manual Request ID Management: Capability to manually manage request IDs, allowing for advanced use cases where specific IDs need to be set or retrieved as needed.

from fastapi_reqid import get_request_id, set_request_id, request_id_context

# Get current request ID
request_id = get_request_id()

# Set request ID manually
token = set_request_id("custom-request-id")
try:
    # Do work with this request ID
    pass
finally:
    # Reset to previous value
    request_id_context.reset(token)

• Building and Publishing: Instructions for building the library using uv, and guidance on testing and publishing packages to TestPyPI and PyPI.

For more details on setting up a development environment, refer to the associated commands for virtual environments and testing.

This project enhances FastAPI applications by providing robust request tracing capabilities, which are essential for effective debugging and monitoring in distributed systems.