fastapi-trace-middleware 1.0.1

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}")

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.