Metadata-Version: 2.4
Name: logs-fastapi
Version: 0.1.0
Author: Martin Cepeda
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: fastapi<1,>=0
Requires-Dist: orjson>=3
Requires-Dist: structlog>=26
Description-Content-Type: text/markdown

# logs-fastapi

Structured JSON request logging for FastAPI, built on structlog. One line of
JSON per request — method, path, request id, real status code, duration —
plus context-merged handler logs and a traceback line on unhandled exceptions.

## Install

```bash
uv add logs-fastapi
```

## Usage

```python
from fastapi import FastAPI
from logs_fastapi.middleware import install

app = FastAPI()
install(app)  # idempotent
```

Every request then emits `request.started` / `request.completed` as JSON, and
any structlog line inside a handler automatically carries the request context:

```json
{"request_id": "3f1a...", "method": "GET", "path": "/", "status_code": 200,
 "duration_ms": 1.2, "timestamp": "2026-08-09T12:00:00Z", "event": "request.completed"}
```

## Features

- **Request-scoped context** — `request_id`, `trace_id`/`span_id` (W3C
  `traceparent` aware), `method`, `path`, `query`, `client` merged into every
  log line via contextvars; nothing leaks between requests.
- **Real status codes** — captured from the ASGI `send`, streaming-safe;
  `499` on client disconnect (logged, cancellation semantics preserved).
- **Header redaction by default** — `authorization`, `cookie`, `set-cookie`
  log as `REDACTED`; extensible via `redact_headers` (trust boundary).
- **Custom 500 handler without losing logs** — own the failure response;
  `request.failed` with traceback is always logged first.
- **`on_completed` hooks** — react to every request outcome, e.g. Prometheus
  counters; a broken hook is logged, never fatal.
- **Zero config, still tunable** — JSON via orjson, `LOG_LEVEL` env var,
  request-body logging (on by default, off via `log_request=False`).

## Documentation

- [Getting started](docs/tutorials/getting-started.md)
- [Customize logging](docs/how-to/customize-logging.md)
- [API reference](docs/reference/api.md)
- [Design notes](docs/explanation/design.md)

## Development

```bash
uv sync
make ci   # full CI suite
```
