Metadata-Version: 2.4
Name: fastapi-observer
Version: 1.4.1
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://vitaee.github.io/FastapiObserver/
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: Programming Language :: Python :: 3.15
Classifier: Framework :: FastAPI
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: <3.16,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.133.0
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: starlette>=1.3.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.45.1; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.45.1; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.45.1; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.66b1; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-logging>=0.66b1; extra == "otel"
Provides-Extra: otel-httpx
Requires-Dist: opentelemetry-instrumentation-httpx>=0.66b1; extra == "otel-httpx"
Provides-Extra: otel-requests
Requires-Dist: opentelemetry-instrumentation-requests>=0.66b1; extra == "otel-requests"
Provides-Extra: audit
Requires-Dist: cryptography>=50.0.0; extra == "audit"
Provides-Extra: otel-sqlalchemy
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.66b1; 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.45.1; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.45.1; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.45.1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.66b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-logging>=0.66b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.66b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-requests>=0.66b1; extra == "all"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.66b1; extra == "all"
Requires-Dist: cryptography>=50.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: httpx>=0.28.1; python_version < "3.11" and extra == "dev"
Requires-Dist: httpx2>=2.16.0; python_version >= "3.11" and extra == "dev"
Requires-Dist: loguru>=0.7.3; extra == "dev"
Requires-Dist: mypy>=2.4.1; extra == "dev"
Requires-Dist: pip-audit>=2.10.1; extra == "dev"
Requires-Dist: pytest>=9.2.0; extra == "dev"
Requires-Dist: pytest-randomly>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.17.3; extra == "dev"
Requires-Dist: cyclonedx-bom>=7.6.0; extra == "dev"
Requires-Dist: uvicorn>=0.54.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.

**Documentation:** [vitaee.github.io/FastapiObserver](https://vitaee.github.io/FastapiObserver/)

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

---


## Compatibility Matrix

| Component | Supported / Tested |
|---|---|
| Python | `3.10` to `3.15` (CI matrix) |
| FastAPI | `>=0.133.0` |
| Starlette | `>=1.3.1` |
| pydantic-settings | `>=2.10.1` |
| Prometheus backend | `prometheus-client>=0.24.1` (optional extra) |
| OpenTelemetry | `opentelemetry-api/sdk/exporter>=1.45.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 ("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

Full documentation lives at [vitaee.github.io/FastapiObserver](https://vitaee.github.io/FastapiObserver/). Deep dives:
- [Security & Presets](https://vitaee.github.io/FastapiObserver/security/)
- [Environment Variables](https://vitaee.github.io/FastapiObserver/configuration/)
- [Runtime Control](https://vitaee.github.io/FastapiObserver/runtime-control/)
- [OpenTelemetry](https://vitaee.github.io/FastapiObserver/opentelemetry/)
- [Logtail Sink](https://vitaee.github.io/FastapiObserver/logtail-sink/)
- [Audit Logging](https://vitaee.github.io/FastapiObserver/audit-logging/)
- [Database Tracing](https://vitaee.github.io/FastapiObserver/db-tracing/)
- [GraphQL Support](https://vitaee.github.io/FastapiObserver/graphql/)
- [Architecture & Operations](https://vitaee.github.io/FastapiObserver/architecture/)
- [Production Deployment](https://vitaee.github.io/FastapiObserver/deployment/)
- [Performance Tuning](https://vitaee.github.io/FastapiObserver/tuning/)
- [Advanced Operations](https://vitaee.github.io/FastapiObserver/advanced/)
- [Maintenance & Contributing](https://vitaee.github.io/FastapiObserver/contributing/) (quality gates, release flow, runtime stress harness)
