fastapi-observer 0.2.2__tar.gz → 0.2.4__tar.gz

{fastapi_observer-0.2.2/src/fastapi_observer.egg-info → fastapi_observer-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.2.2
+Version: 0.2.4
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -32,6 +32,8 @@ 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"
@@ -45,6 +47,7 @@ Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; extra == "otel-re
 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"
@@ -54,6 +57,7 @@ Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "all"
 Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; 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"
@@ -64,6 +68,7 @@ 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.**
@@ -74,6 +79,20 @@ Dynamic: license-file
 
 ---
 
+## 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:
@@ -124,6 +143,9 @@ 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]"
 
@@ -391,6 +413,9 @@ Request arrives
     "method": "GET",
     "path": "/orders/42",
     "status_code": 200,
+    "http.request.method": "GET",
+    "url.path": "/orders/42",
+    "http.response.status_code": 200,
     "duration_ms": 3.456,
     "client_ip": "10.0.0.1",
     "error_type": "ok"
@@ -398,6 +423,18 @@ Request arrives
 }
 ```
 
+On exception logs, a structured `error` object is included for indexed queries:
+
+```json
+{
+  "error": {
+    "type": "RuntimeError",
+    "message": "boom",
+    "stacktrace": "Traceback (most recent call last): ..."
+  }
+}
+```
+
 ---
 
 ## Production Deployment Guide
@@ -546,6 +583,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
 
@@ -749,6 +787,20 @@ Breaker metrics exposed on `/metrics`:
 - `fastapiobserver_sink_circuit_breaker_half_open_total{sink}`
 - `fastapiobserver_sink_circuit_breaker_closes_total{sink}`
 
+### Loguru Coexistence
+
+If your service already uses `loguru`, forward those logs into
+`fastapi-observer` instead of maintaining two independent pipelines.
+
+```python
+from fastapiobserver import install_loguru_bridge
+
+# loguru -> stdlib -> fastapi-observer queue/sinks
+bridge_id = install_loguru_bridge()
+```
+
+Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
+
 ---
 
 ## Plugin Hooks
@@ -832,13 +884,22 @@ Repository integration tests include:
 
 ---
 
+## Benchmarking
+
+Reproducible benchmark harness and methodology:
+- Guide: [`benchmarks.md`](benchmarks.md)
+- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
+- Runner: `examples/benchmarks/run_local_benchmark.sh`
+
+---
+
 ## Release Tracks
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.1`
+Current release version: `0.2.4`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/README.md

@@ -1,5 +1,6 @@
 # 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.**
@@ -10,6 +11,20 @@
 
 ---
 
+## 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:
@@ -60,6 +75,9 @@ 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]"
 
@@ -327,6 +345,9 @@ Request arrives
     "method": "GET",
     "path": "/orders/42",
     "status_code": 200,
+    "http.request.method": "GET",
+    "url.path": "/orders/42",
+    "http.response.status_code": 200,
     "duration_ms": 3.456,
     "client_ip": "10.0.0.1",
     "error_type": "ok"
@@ -334,6 +355,18 @@ Request arrives
 }
 ```
 
+On exception logs, a structured `error` object is included for indexed queries:
+
+```json
+{
+  "error": {
+    "type": "RuntimeError",
+    "message": "boom",
+    "stacktrace": "Traceback (most recent call last): ..."
+  }
+}
+```
+
 ---
 
 ## Production Deployment Guide
@@ -482,6 +515,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
 
@@ -685,6 +719,20 @@ Breaker metrics exposed on `/metrics`:
 - `fastapiobserver_sink_circuit_breaker_half_open_total{sink}`
 - `fastapiobserver_sink_circuit_breaker_closes_total{sink}`
 
+### Loguru Coexistence
+
+If your service already uses `loguru`, forward those logs into
+`fastapi-observer` instead of maintaining two independent pipelines.
+
+```python
+from fastapiobserver import install_loguru_bridge
+
+# loguru -> stdlib -> fastapi-observer queue/sinks
+bridge_id = install_loguru_bridge()
+```
+
+Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
+
 ---
 
 ## Plugin Hooks
@@ -768,13 +816,22 @@ Repository integration tests include:
 
 ---
 
+## Benchmarking
+
+Reproducible benchmark harness and methodology:
+- Guide: [`benchmarks.md`](benchmarks.md)
+- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
+- Runner: `examples/benchmarks/run_local_benchmark.sh`
+
+---
+
 ## Release Tracks
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.1`
+Current release version: `0.2.4`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-observer"
-version = "0.2.2"
+version = "0.2.4"
 description = "Zero-glue FastAPI observability with security presets and runtime controls"
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
@@ -48,6 +48,9 @@ fast-json = [
 prometheus = [
     "prometheus-client>=0.24.1",
 ]
+loguru = [
+    "loguru>=0.7.2",
+]
 otel = [
     "opentelemetry-api>=1.39.1",
     "opentelemetry-sdk>=1.39.1",
@@ -64,6 +67,7 @@ otel-requests = [
 all = [
     "orjson>=3.11.7",
     "prometheus-client>=0.24.1",
+    "loguru>=0.7.2",
     "opentelemetry-api>=1.39.1",
     "opentelemetry-sdk>=1.39.1",
     "opentelemetry-exporter-otlp>=1.39.1",
@@ -74,6 +78,7 @@ all = [
 ]
 dev = [
     "httpx>=0.28.1",
+    "loguru>=0.7.2",
     "mypy>=1.19.1",
     "pip-audit>=2.10.0",
     "pytest>=9.0.2",

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.2.2
+Version: 0.2.4
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -32,6 +32,8 @@ 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"
@@ -45,6 +47,7 @@ Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; extra == "otel-re
 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"
@@ -54,6 +57,7 @@ Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "all"
 Requires-Dist: opentelemetry-instrumentation-requests>=0.60b1; 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"
@@ -64,6 +68,7 @@ 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.**
@@ -74,6 +79,20 @@ Dynamic: license-file
 
 ---
 
+## 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:
@@ -124,6 +143,9 @@ 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]"
 
@@ -391,6 +413,9 @@ Request arrives
     "method": "GET",
     "path": "/orders/42",
     "status_code": 200,
+    "http.request.method": "GET",
+    "url.path": "/orders/42",
+    "http.response.status_code": 200,
     "duration_ms": 3.456,
     "client_ip": "10.0.0.1",
     "error_type": "ok"
@@ -398,6 +423,18 @@ Request arrives
 }
 ```
 
+On exception logs, a structured `error` object is included for indexed queries:
+
+```json
+{
+  "error": {
+    "type": "RuntimeError",
+    "message": "boom",
+    "stacktrace": "Traceback (most recent call last): ..."
+  }
+}
+```
+
 ---
 
 ## Production Deployment Guide
@@ -546,6 +583,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
 
@@ -749,6 +787,20 @@ Breaker metrics exposed on `/metrics`:
 - `fastapiobserver_sink_circuit_breaker_half_open_total{sink}`
 - `fastapiobserver_sink_circuit_breaker_closes_total{sink}`
 
+### Loguru Coexistence
+
+If your service already uses `loguru`, forward those logs into
+`fastapi-observer` instead of maintaining two independent pipelines.
+
+```python
+from fastapiobserver import install_loguru_bridge
+
+# loguru -> stdlib -> fastapi-observer queue/sinks
+bridge_id = install_loguru_bridge()
+```
+
+Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
+
 ---
 
 ## Plugin Hooks
@@ -832,13 +884,22 @@ Repository integration tests include:
 
 ---
 
+## Benchmarking
+
+Reproducible benchmark harness and methodology:
+- Guide: [`benchmarks.md`](benchmarks.md)
+- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
+- Runner: `examples/benchmarks/run_local_benchmark.sh`
+
+---
+
 ## Release Tracks
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.1`
+Current release version: `0.2.4`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapi_observer.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/fastapiobserver/config.py
 src/fastapiobserver/control_plane.py
 src/fastapiobserver/fastapi.py
 src/fastapiobserver/logging.py
+src/fastapiobserver/loguru.py
 src/fastapiobserver/metrics.py
 src/fastapiobserver/middleware.py
 src/fastapiobserver/plugins.py
@@ -28,12 +29,14 @@ src/fastapiobserver/otel/metrics.py
 src/fastapiobserver/otel/resource.py
 src/fastapiobserver/otel/settings.py
 src/fastapiobserver/otel/tracing.py
+src/fastapiobserver/otel/types.py
 tests/test_body_media_allowlist.py
 tests/test_config_settings.py
 tests/test_excluded_url_precedence.py
 tests/test_fastapi_install.py
 tests/test_log_queue_controls.py
 tests/test_logging_schema_contract.py
+tests/test_loguru_bridge.py
 tests/test_metrics_optional_dependency.py
 tests/test_middleware.py
 tests/test_negotiate_content_type.py

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapi_observer.egg-info/requires.txt

@@ -5,6 +5,7 @@ starlette>=0.52.1
 [all]
 orjson>=3.11.7
 prometheus-client>=0.24.1
+loguru>=0.7.2
 opentelemetry-api>=1.39.1
 opentelemetry-sdk>=1.39.1
 opentelemetry-exporter-otlp>=1.39.1
@@ -15,6 +16,7 @@ opentelemetry-instrumentation-requests>=0.60b1
 
 [dev]
 httpx>=0.28.1
+loguru>=0.7.2
 mypy>=1.19.1
 pip-audit>=2.10.0
 pytest>=9.0.2
@@ -25,6 +27,9 @@ cyclonedx-bom>=7.2.1
 [fast-json]
 orjson>=3.11.7
 
+[loguru]
+loguru>=0.7.2
+
 [otel]
 opentelemetry-api>=1.39.1
 opentelemetry-sdk>=1.39.1

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapiobserver/__init__.py

@@ -12,6 +12,11 @@ from .logging import (
     get_sink_circuit_breaker_stats,
     setup_logging,
 )
+from .loguru import (
+    build_loguru_to_stdlib_sink,
+    install_loguru_bridge,
+    remove_loguru_bridge,
+)
 from .metrics import (
     build_metrics_backend,
     get_registered_metrics_backends,
@@ -96,6 +101,10 @@ __all__ = [
     "get_log_queue_stats",
     "get_sink_circuit_breaker_stats",
     "setup_logging",
+    # Loguru bridge
+    "build_loguru_to_stdlib_sink",
+    "install_loguru_bridge",
+    "remove_loguru_bridge",
     # Sinks
     "LogSink",
     "LogtailSink",

fastapi_observer-0.2.4/src/fastapiobserver/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.4"

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapiobserver/logging.py

@@ -28,6 +28,7 @@ _LOGGING_LOCK = threading.Lock()
 _QUEUE_LISTENER: logging.handlers.QueueListener | None = None
 _MANAGED_OUTPUT_HANDLERS: list[logging.Handler] = []
 _SINK_CIRCUIT_BREAKERS: list["SinkCircuitBreakerHandler"] = []
+_LOGGER = logging.getLogger("fastapiobserver.logging")
 LOG_SCHEMA_VERSION = "1.0.0"
 
 CircuitBreakerState = Literal["closed", "open", "half_open"]
@@ -431,7 +432,10 @@ class StructuredJsonFormatter(logging.Formatter):
             payload["event"] = event
 
         if record.exc_info:
-            payload["exc_info"] = self.formatException(record.exc_info)
+            error_payload = _build_structured_error(record, self)
+            payload["error"] = error_payload
+            # Backward-compatible field retained for existing dashboards.
+            payload["exc_info"] = error_payload["stacktrace"]
 
         if getattr(record, "_skip_enrichers", False):
             enriched_payload = payload
@@ -479,7 +483,11 @@ class TraceContextFilter(logging.Filter):
                 trace_id = f"{span_context.trace_id:032x}"
                 span_id = f"{span_context.span_id:016x}"
         except Exception:
-            pass
+            _LOGGER.debug(
+                "trace_context_filter.otel_lookup_failed",
+                exc_info=True,
+                extra={"_skip_enrichers": True},
+            )
 
         if trace_id:
             record.trace_id = trace_id  # type: ignore[attr-defined]
@@ -644,6 +652,32 @@ def _json_dumps(payload: dict[str, Any]) -> str:
     return json.dumps(payload, ensure_ascii=True, default=str)
 
 
+def _build_structured_error(
+    record: logging.LogRecord,
+    formatter: logging.Formatter,
+) -> dict[str, str]:
+    exc_info = record.exc_info
+    if not exc_info:
+        return {"type": "", "message": "", "stacktrace": ""}
+
+    if not isinstance(exc_info, tuple) or len(exc_info) != 3:
+        return {
+            "type": "Exception",
+            "message": "",
+            "stacktrace": "",
+        }
+
+    exc_type, exc_value, _exc_tb = exc_info
+    error_type = exc_type.__name__ if exc_type is not None else "Exception"
+    error_message = str(exc_value) if exc_value is not None else ""
+    stacktrace = formatter.formatException(exc_info)
+    return {
+        "type": error_type,
+        "message": error_message,
+        "stacktrace": stacktrace,
+    }
+
+
 def _wrap_sink_handlers(
     handlers: list[logging.Handler],
     *,

fastapi_observer-0.2.4/src/fastapiobserver/loguru.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any, Callable
+
+from .utils import lazy_import
+
+_LOGGER = logging.getLogger("fastapiobserver.loguru")
+_BRIDGE_MARKER = "_fastapiobserver_loguru_bridge"
+_STANDARD_LOG_RECORD_ATTRS = frozenset(logging.makeLogRecord({}).__dict__)
+
+
+def build_loguru_to_stdlib_sink(
+    *,
+    stdlib_logger_name: str | None = None,
+    include_extra: bool = True,
+) -> Callable[[Any], None]:
+    """Build a Loguru sink that forwards records into stdlib logging.
+
+    This lets existing Loguru users keep ``logger.bind(...).info(...)`` calls
+    while routing output through fastapi-observer's queue/sanitization pipeline.
+    """
+
+    def _sink(message: Any) -> None:
+        record = getattr(message, "record", None)
+        if not isinstance(record, dict):
+            return
+
+        raw_extra = record.get("extra")
+        extra: dict[str, Any]
+        if isinstance(raw_extra, dict):
+            extra = dict(raw_extra)
+        else:
+            extra = {}
+
+        # Guard against accidental recursive bridges in mixed logging setups.
+        if bool(extra.get(_BRIDGE_MARKER)):
+            return
+
+        record_logger_name = str(record.get("name") or "")
+        logger_name = _resolve_logger_name(stdlib_logger_name, record_logger_name)
+        stdlib_logger = logging.getLogger(logger_name)
+        stdlib_extra = _build_stdlib_extra(extra, include_extra=include_extra)
+        exc_info = _extract_exc_info(record.get("exception"))
+        level = _extract_level_number(record.get("level"))
+        message_text = str(record.get("message") or "")
+
+        stdlib_logger.log(
+            level,
+            message_text,
+            exc_info=exc_info,
+            extra=stdlib_extra,
+        )
+
+    return _sink
+
+
+def install_loguru_bridge(
+    *,
+    stdlib_logger_name: str | None = None,
+    level: str | int = 0,
+    include_extra: bool = True,
+    enqueue: bool = False,
+    catch: bool = True,
+) -> int:
+    """Install a Loguru -> stdlib bridge and return the Loguru handler id."""
+    loguru_logger = lazy_import(
+        "loguru",
+        "logger",
+        package_hint="fastapi-observer[loguru]",
+    )
+    sink = build_loguru_to_stdlib_sink(
+        stdlib_logger_name=stdlib_logger_name,
+        include_extra=include_extra,
+    )
+    handler_id = int(
+        loguru_logger.add(
+            sink,
+            level=level,
+            enqueue=enqueue,
+            catch=catch,
+        )
+    )
+    _LOGGER.info(
+        "loguru.bridge.installed",
+        extra={
+            "event": {
+                "handler_id": handler_id,
+                "target_logger": stdlib_logger_name or "<record.name>",
+                "include_extra": include_extra,
+                "enqueue": enqueue,
+            },
+            "_skip_enrichers": True,
+        },
+    )
+    return handler_id
+
+
+def remove_loguru_bridge(handler_id: int) -> None:
+    """Remove a previously installed Loguru bridge handler."""
+    loguru_logger = lazy_import(
+        "loguru",
+        "logger",
+        package_hint="fastapi-observer[loguru]",
+    )
+    loguru_logger.remove(int(handler_id))
+
+
+def _resolve_logger_name(configured_name: str | None, record_name: str) -> str:
+    if configured_name is not None:
+        candidate = configured_name.strip()
+        if candidate:
+            return candidate
+    candidate = record_name.strip()
+    if candidate:
+        return candidate
+    return "loguru"
+
+
+def _build_stdlib_extra(
+    extra: dict[str, Any],
+    *,
+    include_extra: bool,
+) -> dict[str, Any]:
+    forwarded_extra: dict[str, Any] = {_BRIDGE_MARKER: True}
+    if not include_extra:
+        return forwarded_extra
+
+    for key, value in extra.items():
+        normalized_key = str(key)
+        if normalized_key == _BRIDGE_MARKER:
+            continue
+        if normalized_key in _STANDARD_LOG_RECORD_ATTRS:
+            continue
+        forwarded_extra[normalized_key] = value
+    return forwarded_extra
+
+
+def _extract_level_number(level: Any) -> int:
+    level_number = getattr(level, "no", None)
+    if isinstance(level_number, int):
+        return level_number
+    return logging.INFO
+
+
+def _extract_exc_info(
+    exception: Any,
+) -> tuple[type[BaseException], BaseException, TracebackType | None] | None:
+    if exception is None:
+        return None
+
+    exc_type = getattr(exception, "type", None)
+    exc_value = getattr(exception, "value", None)
+    exc_traceback = getattr(exception, "traceback", None)
+    if not isinstance(exc_type, type):
+        return None
+    if not issubclass(exc_type, BaseException):
+        return None
+    if not isinstance(exc_value, BaseException):
+        return None
+    if exc_traceback is not None and not isinstance(exc_traceback, TracebackType):
+        return None
+    return exc_type, exc_value, exc_traceback
+
+
+__all__ = [
+    "build_loguru_to_stdlib_sink",
+    "install_loguru_bridge",
+    "remove_loguru_bridge",
+]

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapiobserver/middleware.py

@@ -142,11 +142,7 @@ class RequestLoggingMiddleware:
                 request_body=request_body_capture.value,
                 response_body=response_body_capture.value,
                 error_type=error_type,
-                exception_class=(
-                    captured_error.__class__.__name__
-                    if captured_error is not None
-                    else None
-                ),
+                exception=captured_error,
             )
             if had_error:
                 self.logger.exception("request.failed", extra={"event": safe_event})
@@ -262,7 +258,7 @@ class _RequestEventBuilder:
         request_body: str | None,
         response_body: str | None,
         error_type: str,
-        exception_class: str | None,
+        exception: Exception | None,
     ) -> dict[str, Any]:
         event: dict[str, Any] = {
             "method": method,
@@ -271,13 +267,18 @@ class _RequestEventBuilder:
             "duration_ms": round(duration_seconds * 1000, 3),
             "client_ip": client_ip,
             "error_type": error_type,
+            # OpenTelemetry semantic-convention aliases for interoperability.
+            "http.request.method": method,
+            "url.path": path,
+            "http.response.status_code": status_code,
         }
         if request_body is not None:
             event["request_body"] = request_body
         if response_body is not None:
             event["response_body"] = response_body
-        if exception_class:
-            event["exception_class"] = exception_class
+        if exception is not None:
+            event["exception_class"] = exception.__class__.__name__
+            event["exception_message"] = str(exception)
         return sanitize_event(event, self.policy)
 
 

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapiobserver/otel/resource.py

@@ -4,17 +4,27 @@ from __future__ import annotations
 
 import logging
 import os
+from types import ModuleType
 from typing import Any, Literal
 from urllib.parse import urlparse, urlunparse
 
 from ..config import ObservabilitySettings
 from ..utils import lazy_import
 from .settings import OTelLogsSettings, OTelMetricsSettings, OTelSettings
+from .types import (
+    LogExporterLike,
+    MetricExporterLike,
+    OTelResourceLike,
+    SpanExporterLike,
+)
 
 _LOGGER = logging.getLogger("fastapiobserver.otel")
 
 
-def create_otel_resource(settings: ObservabilitySettings, otel_settings: OTelSettings) -> Any:
+def create_otel_resource(
+    settings: ObservabilitySettings,
+    otel_settings: OTelSettings,
+) -> OTelResourceLike:
     resources_module = import_otel_module("opentelemetry.sdk.resources")
     resource_attrs = {
         "service.name": otel_settings.service_name or settings.service,
@@ -66,7 +76,7 @@ def build_excluded_urls_csv(settings: ObservabilitySettings) -> str | None:
 # ---------------------------------------------------------------------------
 
 
-def build_span_exporter(otel_settings: OTelSettings) -> Any:
+def build_span_exporter(otel_settings: OTelSettings) -> SpanExporterLike:
     endpoint = normalize_otlp_endpoint(
         otel_settings.otlp_endpoint,
         otel_settings.protocol,
@@ -91,7 +101,7 @@ def build_span_exporter(otel_settings: OTelSettings) -> Any:
 # ---------------------------------------------------------------------------
 
 
-def build_log_exporter(otel_logs_settings: OTelLogsSettings) -> Any:
+def build_log_exporter(otel_logs_settings: OTelLogsSettings) -> LogExporterLike:
     """Build the OTLP log exporter based on protocol."""
     endpoint = otel_logs_settings.otlp_endpoint
     if otel_logs_settings.protocol == "http/protobuf":
@@ -112,7 +122,9 @@ def build_log_exporter(otel_logs_settings: OTelLogsSettings) -> Any:
 # ---------------------------------------------------------------------------
 
 
-def build_metric_exporter(otel_metrics_settings: OTelMetricsSettings) -> Any:
+def build_metric_exporter(
+    otel_metrics_settings: OTelMetricsSettings,
+) -> MetricExporterLike:
     endpoint = normalize_otlp_metrics_endpoint(
         otel_metrics_settings.otlp_endpoint,
         otel_metrics_settings.protocol,
@@ -136,7 +148,7 @@ def build_metric_exporter(otel_metrics_settings: OTelMetricsSettings) -> Any:
 # ---------------------------------------------------------------------------
 
 
-def import_otel_module(name: str) -> Any:
+def import_otel_module(name: str) -> ModuleType:
     try:
         return lazy_import(name, package_hint="fastapi-observer[otel]")
     except RuntimeError as exc:

fastapi_observer-0.2.4/src/fastapiobserver/otel/types.py

@@ -0,0 +1,49 @@
+"""Typing protocols for optional OpenTelemetry integrations.
+
+These protocols intentionally cover only the methods this package relies on,
+so we can provide useful typing without hard-importing OTel runtime classes.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Any, Protocol, Sequence
+
+
+class OTelResourceLike(Protocol):
+    """Minimal resource shape accepted by OTel SDK providers."""
+
+    attributes: Any
+
+
+class SpanExporterLike(Protocol):
+    """Minimal span exporter interface used by OTel processors."""
+
+    def export(self, spans: Sequence[Any]) -> Any: ...
+
+    def shutdown(self) -> None: ...
+
+
+class LogExporterLike(Protocol):
+    """Minimal log exporter interface used by OTel log processors."""
+
+    def export(self, batch: Sequence[Any]) -> Any: ...
+
+    def shutdown(self) -> None: ...
+
+
+class MetricExporterLike(Protocol):
+    """Minimal metric exporter interface used by OTel metric readers."""
+
+    def export(self, metrics_data: Any, timeout_millis: float = ...) -> Any: ...
+
+    def shutdown(self, timeout_millis: float = ...) -> None: ...
+
+
+__all__ = [
+    "ModuleType",
+    "OTelResourceLike",
+    "SpanExporterLike",
+    "LogExporterLike",
+    "MetricExporterLike",
+]

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/src/fastapiobserver/sinks.py

@@ -109,7 +109,11 @@ def discover_entry_point_sinks() -> None:
                     },
                 )
     except Exception:
-        pass
+        _LOGGER.debug(
+            "sinks.entry_point.discover_failed",
+            exc_info=True,
+            extra={"_skip_enrichers": True},
+        )
 
 
 # =====================================================================
@@ -285,7 +289,14 @@ class _LogtailHandler(logging.Handler):
                     self._error_count += 1
                     return  # Don't retry client errors
             except Exception:
-                pass
+                _LOGGER.debug(
+                    "logtail.send.retryable_error",
+                    exc_info=True,
+                    extra={
+                        "event": {"attempt": attempt + 1, "batch_size": len(batch)},
+                        "_skip_enrichers": True,
+                    },
+                )
 
             # Exponential backoff
             if attempt < self._max_retries - 1:

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/tests/test_logging_schema_contract.py

@@ -184,3 +184,34 @@ def test_setup_logging_applies_registered_log_filters() -> None:
 
     assert any(p.get("message") == "business event" for p in filtered)
     assert not any(p.get("message") == "health probe" for p in filtered)
+
+
+def test_structured_formatter_emits_structured_error_payload() -> None:
+    settings = ObservabilitySettings(
+        app_name="orders-api",
+        service="orders",
+        environment="test",
+        version="1.2.3",
+    )
+    formatter = StructuredJsonFormatter(settings, security_policy=SecurityPolicy())
+
+    try:
+        raise RuntimeError("boom")
+    except RuntimeError as error:
+        exc_info = (error.__class__, error, error.__traceback__)
+        record = logging.LogRecord(
+            name="tests.logger",
+            level=logging.ERROR,
+            pathname=__file__,
+            lineno=200,
+            msg="request.failed",
+            args=(),
+            exc_info=exc_info,
+        )
+
+    payload = json.loads(formatter.format(record))
+
+    assert payload["error"]["type"] == "RuntimeError"
+    assert payload["error"]["message"] == "boom"
+    assert "RuntimeError: boom" in payload["error"]["stacktrace"]
+    assert payload["exc_info"] == payload["error"]["stacktrace"]

fastapi_observer-0.2.4/tests/test_loguru_bridge.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from fastapiobserver.loguru import install_loguru_bridge, remove_loguru_bridge
+
+
+class _CaptureHandler(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.records: list[logging.LogRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.records.append(record)
+
+
+def _prepare_logger(name: str) -> tuple[logging.Logger, _CaptureHandler]:
+    logger = logging.getLogger(name)
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+    logger.propagate = False
+    logger.setLevel(logging.DEBUG)
+    capture = _CaptureHandler()
+    logger.addHandler(capture)
+    return logger, capture
+
+
+def test_loguru_bridge_forwards_message_and_extra_fields() -> None:
+    loguru = pytest.importorskip("loguru")
+    logger_name = "tests.loguru.bridge"
+    logger, capture = _prepare_logger(logger_name)
+    bridge_id = install_loguru_bridge(
+        stdlib_logger_name=logger_name,
+        include_extra=True,
+    )
+
+    try:
+        loguru.logger.bind(
+            request_id="req-123",
+            event={"kind": "bridge"},
+        ).info("hello from loguru")
+    finally:
+        remove_loguru_bridge(bridge_id)
+        logger.removeHandler(capture)
+
+    forwarded = [record for record in capture.records if record.getMessage() == "hello from loguru"]
+    assert forwarded
+    record = forwarded[-1]
+    assert getattr(record, "request_id", None) == "req-123"
+    assert getattr(record, "event", None) == {"kind": "bridge"}
+
+
+def test_loguru_bridge_forwards_exception_info() -> None:
+    loguru = pytest.importorskip("loguru")
+    logger_name = "tests.loguru.exception"
+    logger, capture = _prepare_logger(logger_name)
+    bridge_id = install_loguru_bridge(stdlib_logger_name=logger_name)
+
+    try:
+        try:
+            raise RuntimeError("boom")
+        except RuntimeError:
+            loguru.logger.exception("loguru failed")
+    finally:
+        remove_loguru_bridge(bridge_id)
+        logger.removeHandler(capture)
+
+    forwarded = [record for record in capture.records if record.getMessage() == "loguru failed"]
+    assert forwarded
+    record = forwarded[-1]
+    assert record.exc_info is not None
+    assert record.exc_info[0] is RuntimeError

{fastapi_observer-0.2.2 → fastapi_observer-0.2.4}/tests/test_middleware.py

@@ -56,6 +56,9 @@ def test_middleware_logs_path_without_query_string(caplog) -> None:
     ]
     assert request_logs
     assert request_logs[-1].event["path"] == "/search"
+    assert request_logs[-1].event["url.path"] == "/search"
+    assert request_logs[-1].event["http.request.method"] == "GET"
+    assert request_logs[-1].event["http.response.status_code"] == 200
 
 
 def test_middleware_classifies_server_error_response(caplog) -> None:
@@ -82,6 +85,9 @@ def test_middleware_classifies_server_error_response(caplog) -> None:
     ]
     assert request_logs
     assert request_logs[-1].event["error_type"] == "server_error"
+    assert request_logs[-1].event["http.request.method"] == "GET"
+    assert request_logs[-1].event["url.path"] == "/down"
+    assert request_logs[-1].event["http.response.status_code"] == 503
 
 
 def test_middleware_classifies_unhandled_exception(caplog) -> None:
@@ -110,6 +116,10 @@ def test_middleware_classifies_unhandled_exception(caplog) -> None:
     assert request_logs
     assert request_logs[-1].event["error_type"] == "unhandled_exception"
     assert request_logs[-1].event["exception_class"] == "RuntimeError"
+    assert request_logs[-1].event["exception_message"] == "boom"
+    assert request_logs[-1].event["http.request.method"] == "GET"
+    assert request_logs[-1].event["url.path"] == "/boom"
+    assert request_logs[-1].event["http.response.status_code"] == 500
 
 
 def test_middleware_records_exception_on_active_span(

fastapi_observer-0.2.2/src/fastapiobserver/_version.py

@@ -1 +0,0 @@
-__version__ = "0.2.2"