fastapi-trace-middleware 1.0.2

FastAPI middleware for request tracing and logging

FastAPI Trace Middleware

A simple and effective middleware for FastAPI applications that automatically adds trace IDs to requests and integrates with Python logging.

Features

• 🔍 Automatic trace ID generation for each request
• 📝 Seamless integration with Python logging
• 🎛️ Configurable trace ID headers and generators
• 🔄 Context-aware trace ID access throughout your application
• 📦 Easy setup with sensible defaults

Installation

pip install fastapi-trace-middleware

Quick Start

from fastapi import FastAPI
from fastapi_trace import create_trace_middleware, setup_simple_trace_logging
import logging.config

# Setup logging with trace support
logging.config.dictConfig(setup_simple_trace_logging())

app = FastAPI()

# Add trace middleware
trace_middleware = create_trace_middleware()
app.middleware("http")(trace_middleware)

@app.get("/")
async def root():
    from fastapi_trace import get_trace_id
    logging.info("Processing request")  # Will include trace_id automatically
    return {"message": "Hello World", "trace_id": get_trace_id()}

Documentation

Basic Usage

The middleware automatically:

1. Extracts trace ID from request headers (default: X-Trace-ID)
2. Generates a new trace ID if none exists
3. Sets the trace ID in context for the entire request lifecycle
4. Adds trace ID to response headers
5. Makes trace ID available in logs

Configuration

from fastapi_trace import create_trace_middleware

# Custom configuration
trace_middleware = create_trace_middleware(
    trace_header="X-Custom-Trace-ID",  # Custom header name
    include_response_header=True,       # Include in response
    trace_id_generator=lambda: "custom-" + generate(size=10)  # Custom generator
)

Accessing Trace ID

from fastapi_trace import get_trace_id

async def my_function():
    trace_id = get_trace_id()
    print(f"Current trace ID: {trace_id}")

Integration with Existing Middleware

If you already have context middleware (e.g., for user authentication), you have several options to integrate trace functionality without conflicts:

Option 1: Using Hooks (Recommended)

from fastapi_trace import create_trace_middleware

async def custom_context_hook(request):
    # Your existing context setup logic (e.g., Azure user ID)
    if auth_header := request.headers.get("Authorization"):
        # Extract and set user context
        pass

# Create middleware with hooks
trace_middleware = create_trace_middleware(
    pre_process_hook=custom_context_hook,
    respect_existing_context=True  # Don't override existing trace context
)
app.middleware("http")(trace_middleware)

Option 2: Using Utility Functions

from fastapi_trace import setup_trace_context, add_trace_header_to_response

async def enhanced_context_middleware(request, call_next):
    # Set up trace context
    trace_id = await setup_trace_context(request)
    
    # Your existing context logic
    # ... (Azure user ID, etc.)
    
    response = await call_next(request)
    
    # Add trace header
    add_trace_header_to_response(response, trace_id)
    return response

app.middleware("http")(enhanced_context_middleware)

Option 3: Composable Middleware

from fastapi_trace.integration_examples import create_compatible_middleware

# Your existing middleware function
async def existing_context_middleware(request, call_next):
    # Your existing logic
    return await call_next(request)

# Create compatible middleware
middleware = create_compatible_middleware(existing_context_middleware)
app.middleware("http")(middleware)

Custom Logging Setup

from fastapi_trace import setup_trace_logging

# Custom formatters and handlers
config = setup_trace_logging(
    formatters={
        "custom": {
            "format": "%(asctime)s [%(trace_id)s] %(levelname)s: %(message)s"
        }
    }
)

import logging.config
logging.config.dictConfig(config)

Requirements

• Python 3.8+
• FastAPI 0.68.0+
• nanoid 2.0.0+

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.