fastapi-observer 1.0.0__tar.gz → 1.3.1__tar.gz

fastapi_observer-1.3.1/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: fastapi-observer
+Version: 1.3.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://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)

fastapi_observer-1.3.1/README.md

@@ -0,0 +1,172 @@
+# 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)

{fastapi_observer-1.0.0 → fastapi_observer-1.3.1}/pyproject.toml

@@ -65,6 +65,12 @@ otel-httpx = [
 otel-requests = [
     "opentelemetry-instrumentation-requests>=0.60b1",
 ]
+audit = [
+    "cryptography>=46.0.5",
+]
+otel-sqlalchemy = [
+    "opentelemetry-instrumentation-sqlalchemy>=0.60b1",
+]
 all = [
     "orjson>=3.11.7",
     "prometheus-client>=0.24.1",
@@ -76,6 +82,8 @@ all = [
     "opentelemetry-instrumentation-logging>=0.60b1",
     "opentelemetry-instrumentation-httpx>=0.60b1",
     "opentelemetry-instrumentation-requests>=0.60b1",
+    "opentelemetry-instrumentation-sqlalchemy>=0.60b1",
+    "cryptography>=46.0.5",
 ]
 dev = [
     "httpx>=0.28.1",
@@ -116,3 +124,8 @@ ignore_missing_imports = true
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.7.3",
+]

fastapi_observer-1.3.1/src/fastapi_observer.egg-info/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: fastapi-observer
+Version: 1.3.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://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)