fastapi-observer 1.11.0__tar.gz → 1.12.0__tar.gz

{fastapi_observer-1.11.0/src/fastapi_observer.egg-info → fastapi_observer-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.11.0
+Version: 1.12.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.11.0
+Version: 1.12.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/src/fastapi_observer.egg-info/SOURCES.txt

@@ -50,6 +50,7 @@ src/fastapiobserver/otel/exclusions.py
 src/fastapiobserver/otel/lifecycle.py
 src/fastapiobserver/otel/logs.py
 src/fastapiobserver/otel/metrics.py
+src/fastapiobserver/otel/native.py
 src/fastapiobserver/otel/resource.py
 src/fastapiobserver/otel/settings.py
 src/fastapiobserver/otel/tracing.py
@@ -87,6 +88,7 @@ tests/test_loop_watchdog.py
 tests/test_metrics_contracts.py
 tests/test_metrics_optional_dependency.py
 tests/test_middleware.py
+tests/test_native_telemetry.py
 tests/test_negotiate_content_type.py
 tests/test_otel_integration.py
 tests/test_otel_lifecycle.py

fastapi_observer-1.12.0/src/fastapiobserver/_version.py

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

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/src/fastapiobserver/fastapi.py

@@ -34,6 +34,7 @@ from .otel import (
     install_otel_logs,
     install_otel_metrics,
 )
+from .otel.native import keep_native_logs_out
 from .propagation import install_request_id_propagation
 from .security import SecurityPolicy, TrustedProxyPolicy
 
@@ -217,6 +218,8 @@ def _setup_structured_logging(
             otel_settings=otel_settings,
             security_policy=security_policy,
         )
+        if otel_log_handler is not None:
+            keep_native_logs_out(app)
         if logs_mode == "otlp" and otel_log_handler is None:
             raise RuntimeError(
                 "OTLP log mode requires a configured OTLP log handler. "

fastapi_observer-1.12.0/src/fastapiobserver/otel/exclusions.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, MutableMapping
+from typing import TYPE_CHECKING, Any
+
+from .native import native_telemetry_config
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+class NativeExclusions:
+    """FastAPI's native ``exclude`` hook, with the URL patterns OpenTelemetry's
+    instrumentation uses: *csv*, or its environment variables when *csv* is None.
+    """
+
+    def __init__(self, csv: str | None) -> None:
+        from opentelemetry.util.http import get_excluded_urls, parse_excluded_urls
+
+        self.excluded_urls = (
+            parse_excluded_urls(csv) if csv is not None else get_excluded_urls("FASTAPI")
+        )
+
+    def __call__(self, scope: MutableMapping[str, Any]) -> bool:
+        return bool(self.excluded_urls.url_disabled(scope.get("path", "")))
+
+
+def update_otel_middleware_exclusions(
+    app: FastAPI, new_exclusions: frozenset[str] | set[str]
+) -> None:
+    """Merge ``new_exclusions`` into the excluded URLs of whichever tracing is active.
+
+    Both FastAPI's native tracing and ``FastAPIInstrumentor.instrument_app()`` take
+    exclusions up front, but routes are usually added after
+    ``install_observability()``, so this updates them in place.
+    """
+    native_exclude = (native_telemetry_config(app) or {}).get("exclude")
+    if isinstance(native_exclude, NativeExclusions):
+        native_exclude.excluded_urls = _merged(native_exclude.excluded_urls, new_exclusions)
+
+    current = getattr(app, "middleware_stack", None)
+    while current is not None:
+        # Match by name so apps without OTel never import the ASGI instrumentation.
+        if type(current).__name__ == "OpenTelemetryMiddleware":
+            current.excluded_urls = _merged(current.excluded_urls, new_exclusions)
+            return
+        current = getattr(current, "app", None)
+
+
+def _merged(excluded_urls: Any, new_exclusions: Iterable[str]) -> Any:
+    from opentelemetry.util.http import parse_excluded_urls
+
+    existing = getattr(excluded_urls, "_excluded_urls", None) or ()
+    return parse_excluded_urls(",".join(sorted({*existing, *new_exclusions})))

fastapi_observer-1.12.0/src/fastapiobserver/otel/native.py

@@ -0,0 +1,44 @@
+"""FastAPI's native OpenTelemetry (FastAPI 0.142+), set up to fit fastapi-observer.
+
+FastAPI takes these settings only as ``FastAPI(telemetry=...)`` and keeps them in
+``app._telemetry``, which it reads on every request. That attribute isn't public
+API. Without it, as before 0.142, nothing here changes anything, and tracing
+falls back to OpenTelemetry's FastAPI instrumentation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+
+def native_telemetry_config(app: Any) -> MutableMapping[str, Any] | None:
+    config = getattr(app, "_telemetry", None)
+    return config if isinstance(config, MutableMapping) else None
+
+
+def trace_natively(app: Any, excluded_urls_csv: str | None) -> bool:
+    """Let FastAPI trace requests itself, skipping the excluded URLs.
+
+    False when it can't: FastAPI before 0.142, or tracing turned off in
+    ``FastAPI(telemetry=...)``.
+    """
+    config = native_telemetry_config(app)
+    if config is None or not config.get("tracing", True):
+        return False
+    from .exclusions import NativeExclusions
+
+    config["exclude"] = NativeExclusions(excluded_urls_csv)
+    return True
+
+
+def keep_native_logs_out(app: Any) -> None:
+    """Stop FastAPI exporting its own logs around fastapi-observer's redaction.
+
+    FastAPI writes validation failures and unhandled exceptions, with messages
+    and stack traces, straight to the global logger provider, the one OTLP log
+    export sets up. fastapi-observer already logs both, redacted.
+    """
+    config = native_telemetry_config(app)
+    if config is not None:
+        config["logs"] = False

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/src/fastapiobserver/otel/tracing.py

@@ -11,6 +11,7 @@ from fastapi import FastAPI
 from ..config import ObservabilitySettings
 from ..request_context import get_request_state
 from .lifecycle import close_on_app_shutdown
+from .native import trace_natively
 from .resource import (
     build_excluded_urls_csv,
     build_otlp_exporter,
@@ -39,9 +40,6 @@ def install_otel(
     trace_sdk = import_otel_module("opentelemetry.sdk.trace")
     trace_export = import_otel_module("opentelemetry.sdk.trace.export")
     sampling = import_otel_module("opentelemetry.sdk.trace.sampling")
-    fastapi_instrumentor_module = import_otel_module(
-        "opentelemetry.instrumentation.fastapi"
-    )
 
     set_trace_sampling_ratio(otel_settings.trace_sampling_ratio)
     tracer_provider = trace_api.get_tracer_provider()
@@ -100,17 +98,16 @@ def install_otel(
         tracer_provider.add_span_processor(_request_call_totals(trace_api, trace_sdk))
         _CALL_TOTALS_PROVIDERS.add(tracer_provider)
 
-    # --- Wire excluded URLs for noise control ---
+    # FastAPI 0.142+ traces requests itself, with spans for dependencies, the
+    # endpoint and serialization; older versions need OpenTelemetry's instrumentation.
     excluded_urls_str = build_excluded_urls_csv(settings)
-    instrument_kwargs: dict[str, Any] = {
-        "tracer_provider": tracer_provider,
-    }
-    if excluded_urls_str is not None:
-        instrument_kwargs["excluded_urls"] = excluded_urls_str
-
-    fastapi_instrumentor_module.FastAPIInstrumentor.instrument_app(
-        app, **instrument_kwargs
-    )
+    if not trace_natively(app, excluded_urls_str):
+        instrument_kwargs: dict[str, Any] = {"tracer_provider": tracer_provider}
+        if excluded_urls_str is not None:
+            instrument_kwargs["excluded_urls"] = excluded_urls_str
+        import_otel_module(
+            "opentelemetry.instrumentation.fastapi"
+        ).FastAPIInstrumentor.instrument_app(app, **instrument_kwargs)
 
     if provider_owned:
         close_on_app_shutdown(app, tracer_provider, shutdown=True)

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/src/fastapiobserver/request_context.py

@@ -69,8 +69,17 @@ class RequestState:
 
 
 def route_template(scope: Mapping[str, Any]) -> str | None:
-    """The matched route's template, such as ``/users/{user_id}``, once routing has run."""
-    template = getattr(scope.get("route"), "path", None)
+    """The matched route's template, such as ``/users/{user_id}``, once routing has run.
+
+    Since FastAPI 0.137, ``scope["route"].path`` leaves out prefixes given to
+    ``include_router()`` and those of outer routers. FastAPI keeps the full
+    template in its effective route context, set for routes in included routers.
+    """
+    fastapi_scope = scope.get("fastapi")
+    context = (
+        fastapi_scope.get("effective_route_context") if isinstance(fastapi_scope, dict) else None
+    )
+    template = getattr(context, "path", None) or getattr(scope.get("route"), "path", None)
     return template if isinstance(template, str) and template else None
 
 

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/tests/test_excluded_url_precedence.py

@@ -72,7 +72,8 @@ def test_install_otel_passes_empty_excluded_urls(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Integration: install_otel actually passes excluded_urls='' to instrument_app
-    when otel_excluded_urls is explicitly set to empty."""
+    when otel_excluded_urls is explicitly set to empty. FastAPI's own tracing is
+    off, so the instrumentation is used, as on FastAPI before 0.142."""
     pytest.importorskip("opentelemetry.instrumentation.fastapi")
 
     from fastapi import FastAPI
@@ -87,7 +88,7 @@ def test_install_otel_passes_empty_excluded_urls(
 
     monkeypatch.setattr(FastAPIInstrumentor, "instrument_app", spy_instrument_app)
 
-    app = FastAPI()
+    app = FastAPI(telemetry={"tracing": False})
     settings = ObservabilitySettings(otel_excluded_urls="")  # type: ignore[arg-type]
     otel_settings = OTelSettings(enabled=True, service_name="test-svc")
 

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/tests/test_middleware.py

@@ -122,8 +122,18 @@ def test_middleware_classifies_unhandled_exception(caplog) -> None:
     assert request_logs[-1].event["http.response.status_code"] == 500
 
 
-def test_unhandled_exception_recorded_once_on_server_span(
+@pytest.mark.parametrize(
+    ("telemetry", "events", "error_type"),
+    [
+        ({}, [], "RuntimeError"),  # FastAPI's own tracing: no exception text in the trace
+        ({"tracing": False}, ["exception"], None),  # the instrumentation records it once
+    ],
+)
+def test_unhandled_exception_marks_the_server_span_once(
     monkeypatch: pytest.MonkeyPatch,
+    telemetry: dict[str, bool],
+    events: list[str],
+    error_type: str | None,
 ) -> None:
     in_memory = pytest.importorskip("opentelemetry.sdk.trace.export.in_memory_span_exporter")
     import fastapiobserver.otel.tracing as otel_tracing_module
@@ -132,7 +142,7 @@ def test_unhandled_exception_recorded_once_on_server_span(
     exporter = in_memory.InMemorySpanExporter()
     monkeypatch.setattr(otel_tracing_module, "build_otlp_exporter", lambda *_: exporter)
 
-    app = FastAPI()
+    app = FastAPI(telemetry=telemetry)  # type: ignore[arg-type]
 
     @app.get("/boom-span")
     def boom() -> None:
@@ -153,8 +163,9 @@ def test_unhandled_exception_recorded_once_on_server_span(
     [server_span] = [
         span for span in exporter.get_finished_spans() if span.kind.name == "SERVER"
     ]
-    assert [event.name for event in server_span.events] == ["exception"]
+    assert [event.name for event in server_span.events] == events
     assert server_span.status.status_code.name == "ERROR"
+    assert server_span.attributes.get("error.type") == error_type
 
 
 def test_extract_scope_client_ip_contract() -> None:

fastapi_observer-1.12.0/tests/test_native_telemetry.py

@@ -0,0 +1,130 @@
+"""FastAPI 0.142+ traces requests itself; fastapi-observer uses that and keeps
+FastAPI's own log export out of the way of redaction."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+from fastapiobserver import (
+    ObservabilitySettings,
+    OTelLogsSettings,
+    OTelSettings,
+    install_observability,
+)
+from fastapiobserver.logging import setup_logging, shutdown_logging
+import fastapiobserver.otel.logs as otel_logs_module
+import fastapiobserver.otel.tracing as otel_tracing_module
+
+pytest.importorskip("fastapi.telemetry")
+trace_api = pytest.importorskip("opentelemetry.trace")
+in_memory_spans = pytest.importorskip("opentelemetry.sdk.trace.export.in_memory_span_exporter")
+
+
+class _Collector(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.payloads: list[dict[str, Any]] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.payloads.append(json.loads(self.format(record)))
+
+
+def _server_spans(exporter: Any) -> list[Any]:
+    trace_api.get_tracer_provider().force_flush()
+    return [s for s in exporter.get_finished_spans() if s.kind == trace_api.SpanKind.SERVER]
+
+
+def test_requests_are_traced_by_fastapi_itself(monkeypatch: pytest.MonkeyPatch) -> None:
+    exporter = in_memory_spans.InMemorySpanExporter()
+    monkeypatch.setattr(otel_tracing_module, "build_otlp_exporter", lambda *_: exporter)
+    settings = ObservabilitySettings()
+    app = FastAPI()
+
+    @app.get("/orders/{order_id}")
+    def order(order_id: str) -> dict[str, str]:
+        return {}
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, str]:
+        return {}
+
+    @app.get("/internal", include_in_schema=False)
+    def internal() -> dict[str, str]:
+        return {}
+
+    install_observability(app, settings, otel_settings=OTelSettings(enabled=True))
+    collector = _Collector()
+    setup_logging(settings, logs_mode="otlp", extra_handlers=[collector])
+    with TestClient(app) as client:  # the lifespan adds hidden routes to the exclusions
+        for path in ("/orders/1", "/healthz", "/internal"):
+            client.get(path)
+    shutdown_logging()
+
+    [span] = _server_spans(exporter)  # excluded and hidden routes aren't traced
+    assert span.instrumentation_scope.name == "fastapi"
+    assert span.name == "GET /orders/{order_id}"
+    [completed] = [
+        p
+        for p in collector.payloads
+        if p["message"] == "request.completed" and p["event"]["path"] == "/orders/1"
+    ]
+    assert completed["trace_id"] == f"{span.context.trace_id:032x}"
+
+
+def test_instrumentation_traces_when_fastapi_tracing_is_off(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    exporter = in_memory_spans.InMemorySpanExporter()
+    monkeypatch.setattr(otel_tracing_module, "build_otlp_exporter", lambda *_: exporter)
+    app = FastAPI(telemetry={"tracing": False})  # as on FastAPI before 0.142
+
+    @app.get("/orders/{order_id}")
+    def order(order_id: str) -> dict[str, str]:
+        return {}
+
+    install_observability(app, ObservabilitySettings(), otel_settings=OTelSettings(enabled=True))
+    TestClient(app).get("/orders/1")
+    shutdown_logging()
+
+    [span] = _server_spans(exporter)
+    assert span.instrumentation_scope.name == "opentelemetry.instrumentation.fastapi"
+
+
+@pytest.mark.parametrize("tracing", [False, True])
+def test_fastapi_does_not_export_its_own_logs_past_redaction(
+    monkeypatch: pytest.MonkeyPatch, tracing: bool
+) -> None:
+    in_memory_logs = pytest.importorskip("opentelemetry.sdk._logs.export")
+    logs_api = pytest.importorskip("opentelemetry._logs")
+    exported = in_memory_logs.InMemoryLogRecordExporter()
+    monkeypatch.setattr(otel_logs_module, "build_otlp_exporter", lambda *_: exported)
+    monkeypatch.setattr(
+        otel_tracing_module,
+        "build_otlp_exporter",
+        lambda *_: in_memory_spans.InMemorySpanExporter(),
+    )
+    app = FastAPI()
+
+    @app.get("/boom")
+    def boom() -> dict[str, str]:
+        raise RuntimeError("upstream rejected token=sk_live_secret")
+
+    install_observability(
+        app,
+        ObservabilitySettings(),
+        otel_settings=OTelSettings(enabled=tracing),
+        otel_logs_settings=OTelLogsSettings(enabled=True, logs_mode="otlp"),
+    )
+    TestClient(app, raise_server_exceptions=False).get("/boom")
+    shutdown_logging()
+    logs_api.get_logger_provider().force_flush()
+
+    scopes = {record.instrumentation_scope.name for record in exported.get_finished_logs()}
+    assert "fastapiobserver.middleware" in scopes  # ours, redacted, still exported
+    assert "fastapi" not in scopes

{fastapi_observer-1.11.0 → fastapi_observer-1.12.0}/tests/test_route_template_cardinality.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import uuid
 
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 from fastapi.testclient import TestClient
 
 from fastapiobserver import ObservabilitySettings, install_observability
@@ -88,3 +88,38 @@ def test_scanner_404s_share_one_metrics_label() -> None:
     assert after_probes - before == 20
     assert unmatched_requests() == after_probes
     assert not any(path in client.get("/metrics").text for path in probes)
+
+
+def test_routers_included_with_a_prefix_keep_it_in_the_label() -> None:
+    # Since FastAPI 0.137, scope["route"].path leaves out prefixes given to
+    # include_router() and those of outer routers (fastapi/fastapi#16051).
+    app = FastAPI()
+    v1, v2, inner = APIRouter(), APIRouter(), APIRouter()
+
+    @v1.get("/items/{item_id}")
+    def v1_item(item_id: str) -> dict[str, str]:
+        return {}
+
+    @v2.get("/items/{item_id}")
+    def v2_item(item_id: str) -> dict[str, str]:
+        return {}
+
+    @inner.get("/ping")
+    def ping() -> dict[str, str]:
+        return {}
+
+    v2.include_router(inner, prefix="/admin")
+    app.include_router(v1, prefix="/v1")
+    app.include_router(v2, prefix="/v2")
+    install_observability(app, ObservabilitySettings(metrics_enabled=True))
+    client = TestClient(app)
+    for path in ("/v1/items/1", "/v2/items/1", "/v2/admin/ping"):
+        assert client.get(path).status_code == 200
+
+    labels = {
+        line.split('path="', 1)[1].split('"', 1)[0]
+        for line in client.get("/metrics").text.splitlines()
+        if line.startswith("http_requests_total{")
+    }
+    assert {"/v1/items/{item_id}", "/v2/items/{item_id}", "/v2/admin/ping"} <= labels
+    assert "/items/{item_id}" not in labels

fastapi_observer-1.11.0/src/fastapiobserver/_version.py

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

fastapi_observer-1.11.0/src/fastapiobserver/otel/exclusions.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from fastapi import FastAPI
-
-
-def update_otel_middleware_exclusions(
-    app: FastAPI, new_exclusions: frozenset[str] | set[str]
-) -> None:
-    """Merge ``new_exclusions`` into the built OTel middleware's excluded URLs.
-
-    ``FastAPIInstrumentor.instrument_app(excluded_urls=...)`` only takes
-    exclusions up front, but routes are usually added after
-    ``install_observability()`` and OTel offers no supported way to extend
-    them later, so this updates the middleware in place.
-    """
-    current = getattr(app, "middleware_stack", None)
-    while current is not None:
-        # Match by name so apps without OTel never import the ASGI instrumentation.
-        if type(current).__name__ == "OpenTelemetryMiddleware":
-            from opentelemetry.util.http import parse_excluded_urls
-
-            existing = getattr(current.excluded_urls, "_excluded_urls", None) or ()
-            merged = sorted({*existing, *new_exclusions})
-            current.excluded_urls = parse_excluded_urls(",".join(merged))
-            return
-        current = getattr(current, "app", None)