Metadata-Version: 2.4
Name: fastapi-observer
Version: 1.3.2
Summary: Zero-glue FastAPI observability with security presets and runtime controls
Author-email: Vitaee <opensource@vitaee.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Vitaee/FastapiObserver
Project-URL: Documentation, https://github.com/Vitaee/FastapiObserver#readme
Project-URL: Repository, https://github.com/Vitaee/FastapiObserver.git
Project-URL: Issues, https://github.com/Vitaee/FastapiObserver/issues
Project-URL: Funding, https://buymeacoffee.com/FYbPCSu
Keywords: fastapi,observability,logging,metrics,opentelemetry
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: FastAPI
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.129.0
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: starlette>=0.52.1
Provides-Extra: fast-json
Requires-Dist: orjson>=3.11.7; extra == "fast-json"
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.24.1; extra == "prometheus"
Provides-Extra: loguru
Requires-Dist: loguru>=0.7.2; extra == "loguru"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.39.1; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.39.1; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.39.1; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b1; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-logging>=0.60b1; extra == "otel"
Provides-Extra: otel-httpx
Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "otel-httpx"
Provides-Extra: otel-requests
Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; extra == "otel-requests"
Provides-Extra: audit
Requires-Dist: cryptography>=46.0.5; extra == "audit"
Provides-Extra: otel-sqlalchemy
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.60b1; extra == "otel-sqlalchemy"
Provides-Extra: all
Requires-Dist: orjson>=3.11.7; extra == "all"
Requires-Dist: prometheus-client>=0.24.1; extra == "all"
Requires-Dist: loguru>=0.7.2; extra == "all"
Requires-Dist: opentelemetry-api>=1.39.1; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.39.1; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.39.1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-logging>=0.60b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.60b1; extra == "all"
Requires-Dist: cryptography>=46.0.5; extra == "all"
Provides-Extra: dev
Requires-Dist: httpx>=0.28.1; extra == "dev"
Requires-Dist: loguru>=0.7.2; extra == "dev"
Requires-Dist: mypy>=1.19.1; extra == "dev"
Requires-Dist: pip-audit>=2.10.0; extra == "dev"
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-randomly>=3.16.0; extra == "dev"
Requires-Dist: ruff>=0.15.1; extra == "dev"
Requires-Dist: cyclonedx-bom>=7.2.1; extra == "dev"
Requires-Dist: uvicorn>=0.30.0; extra == "dev"
Dynamic: license-file

# fastapi-observer

[![CI](https://github.com/Vitaee/FastapiObserver/actions/workflows/ci.yml/badge.svg)](https://github.com/Vitaee/FastapiObserver/actions/workflows/ci.yml)
[![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/FYbPCSu)

**Zero-glue observability for FastAPI.**

`fastapi-observer` gives you structured JSON logs, request correlation, Prometheus metrics, OpenTelemetry tracing, security redaction presets, and runtime controls in one install step and one function call.

**Supported Python versions:** `3.10` to `3.14`

---


## Compatibility Matrix

| Component | Supported / Tested |
|---|---|
| Python | `3.10` to `3.14` (CI matrix) |
| FastAPI | `>=0.129.0` |
| Starlette | `>=0.52.1` |
| pydantic-settings | `>=2.10.1` |
| Prometheus backend | `prometheus-client>=0.24.1` (optional extra) |
| OpenTelemetry | `opentelemetry-api/sdk/exporter>=1.39.1` (optional extra) |
| Loguru bridge | `loguru>=0.7.2` (optional extra) |

---

## Why This Package Exists

Most FastAPI services eventually need the same observability plumbing:
- Structured JSON logging
- Request and trace correlation
- Metrics for dashboards and alerts
- OpenTelemetry setup
- Redaction/sanitization for sensitive data
- Runtime controls for incident response

Teams usually implement this as custom glue code in every service. That costs engineering time and creates drift between services.

`fastapi-observer` replaces this repeated wiring with a consistent, secure-by-default setup.

---

## Sponsor

If this library saves you engineering time, you can support maintenance here:

[buymeacoffee.com/FYbPCSu](https://buymeacoffee.com/FYbPCSu)

---

## What You Get Immediately

After one call to `install_observability()`:

| Capability | Included | Default |
|---|---|---|
| Structured JSON logs | Yes | Enabled |
| Request ID correlation | Yes | Enabled |
| Trace/span IDs in logs | Yes (with OTel) | Off until OTel enabled |
| Prometheus `/metrics` | Yes | Off until `metrics_enabled=True` |
| Native FastAPI Lifespan | Yes | Explicit opt-in via `observability_lifespan` |
| Auto-discovery | Yes | Excluded routes (`/docs`, etc.) & DB engines |
| Sensitive-data redaction | Yes | Enabled |
| Security presets (`strict`, `pci`, `gdpr`) | Yes | Available |
| Runtime control endpoint | Yes | Off until enabled |
| Plugin hooks for enrichment/hooks | Yes | Available |

---

## Install

```bash
# Core (logging + metrics + security)
pip install fastapi-observer

# Prometheus metrics support
pip install "fastapi-observer[prometheus]"

# Loguru coexistence bridge support
pip install "fastapi-observer[loguru]"

# OpenTelemetry tracing/logs support
pip install "fastapi-observer[otel]"

# Everything
pip install "fastapi-observer[all]"
```

Import path:

```python
import fastapiobserver
```

---

## 5-Minute Quick Start

## 5-Minute Quick Start ("Zero-Glue")

You can configure the entire library via environment variables simply by calling `install_observability(app)`.

```bash
export APP_NAME="orders-api"
export SERVICE_NAME="orders"
export ENVIRONMENT="production"
export METRICS_ENABLED="true"

# Optional: Set a profile ("development" or "production") to auto-configure log levels, queues, and redaction strictness
export OBS_PROFILE="production"
```

```python
from fastapi import FastAPI
from fastapiobserver import install_observability

app = FastAPI()

# Wires up logging, metrics, OTel, and security automatically from env vars
install_observability(app)

@app.get("/orders/{order_id}")
def get_order(order_id: int) -> dict[str, int]:
    return {"order_id": order_id}

@app.get("/hidden", include_in_schema=False)
def hidden_endpoint():
    # This endpoint is automatically excluded from
    # Prometheus metrics and OTel tracing.
    return {"status": "ok"}
```

Run:

```bash
uvicorn main:app --reload
```

Now you have:
- Structured request logs on every request
- Request ID propagation
- Sanitized event payloads (enforced by the `production` profile)
- Prometheus metrics at `/metrics`

### Environment Profiles (`OBS_PROFILE`)

To dramatically reduce boilerplate, you can use the `OBS_PROFILE` environment variable to automatically set sensible defaults for your environment:

- **`OBS_PROFILE=development`**: Forces `LOG_LEVEL=DEBUG` and disables any OpenTelemetry network overhead to keep local development fast and noisy.
- **`OBS_PROFILE=production`**: Forces `LOG_LEVEL=INFO`, optimizes internal queues for massive throughput (`LOG_QUEUE_MAX_SIZE=20000`), and enforces the `strict` security redaction preset.

*(Explicit env vars or Python arguments will always override profile defaults).*

---

## Documentation Map

For deep-dive documentation, please explore the official documentation site (or read the `docs/` folder directly):
- [Security & Presets](security.md)
- [Environment Variables](configuration.md)
- [Runtime Control](runtime-control.md)
- [OpenTelemetry](opentelemetry.md)
- [Logtail Sink](logtail-sink.md)
- [Audit Logging](audit-logging.md)
- [Database Tracing](db-tracing.md)
- [GraphQL Support](graphql.md)
- [Architecture & Operations](architecture.md)
- [Production Deployment](deployment.md)
- [Performance Tuning](tuning.md)
- [Advanced Operations](advanced.md)
