Metadata-Version: 2.4
Name: fastapi-trace-middleware
Version: 1.0.1
Summary: FastAPI middleware for request tracing and logging
Author-email: nelson <nnluk1010@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nnluk1010/fastapi-trace-middleware
Project-URL: Bug Reports, https://github.com/nnluk1010/fastapi-trace-middleware/issues
Project-URL: Source, https://github.com/nnluk1010/fastapi-trace-middleware
Keywords: fastapi,middleware,tracing,logging,request-id
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.68.0
Requires-Dist: nanoid>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: httpx>=0.23.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install fastapi-trace-middleware
```

## Quick Start

```python
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

```python
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

```python
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

```python
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.
