fastapi-observer 1.8.0__tar.gz → 1.9.0__tar.gz

{fastapi_observer-1.8.0/src/fastapi_observer.egg-info → fastapi_observer-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.8.0
+Version: 1.9.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -149,7 +149,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
 - **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
-- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0}/README.md

@@ -73,7 +73,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
 - **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
-- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.8.0
+Version: 1.9.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -149,7 +149,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
 - **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
-- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 

fastapi_observer-1.9.0/src/fastapiobserver/_version.py

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

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/events.py

@@ -68,23 +68,28 @@ def _classify_error(status_code: int, error: Exception | None) -> str:
     return "ok"
 
 
-def _extract_route_template(scope: Scope, raw_path: str) -> str:
-    """Return the matched route template for bounded metric cardinality.
+UNMATCHED_ROUTE = "<unmatched>"
 
-    After Starlette's router runs, ``scope["route"]`` contains the matched
-    ``Route`` object whose ``.path`` is the template string
-    (e.g. ``/users/{user_id}``).
 
-    Falls back to *raw_path* when:
-    * No route matched (404 / unmatched sub-apps)
-    * ``scope["route"]`` is not a Starlette ``Route`` with a ``path`` attr
+def _extract_route_template(scope: Scope, raw_path: str, status_code: int) -> str:
+    """Return the metrics ``path`` label: the matched route template if known.
+
+    After routing, ``scope["route"]`` holds the matched route, whose ``.path``
+    is the template (e.g. ``/users/{user_id}``). Without one, a 404 means no
+    route matched, mostly scanners, so those share ``UNMATCHED_ROUTE`` instead
+    of adding a time series per URL. Other requests without a template keep
+    *raw_path*: FastAPI doesn't record plain Starlette routes, such as ones
+    added with ``app.add_route()``, in the scope.
     """
-    route = scope.get("route")
-    if route is not None:
-        template = getattr(route, "path", None)
-        if isinstance(template, str) and template:
-            return template
-    return raw_path
+    template = getattr(scope.get("route"), "path", None)
+    if isinstance(template, str) and template:
+        return template
+    return UNMATCHED_ROUTE if status_code == 404 else raw_path
 
-__all__ = ["_RequestEventBuilder", "_classify_error", "_extract_route_template", 
-           "_sanitize_exception_message"]
+__all__ = [
+    "UNMATCHED_ROUTE",
+    "_RequestEventBuilder",
+    "_classify_error",
+    "_extract_route_template",
+    "_sanitize_exception_message",
+]

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/metrics.py

@@ -38,12 +38,16 @@ class _MetricsRecorder:
         if scope and "app" in scope:
             app = scope["app"]
             state = getattr(app.state, "_observability_state", None)
-            if state is not None:
+            # Filled when the app starts; without a lifespan, keep the settings' list.
+            if state is not None and state.excluded_urls:
                 excluded_urls = state.excluded_urls
 
+        # Also check the request's own path: unmatched requests share one label.
+        raw_path = scope.get("path") if scope else None
         if (
             path in excluded_urls
             or collapsed_path in excluded_urls
+            or raw_path in excluded_urls
         ):
             return
         try:

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/request_logging.py

@@ -168,7 +168,7 @@ class RequestLoggingMiddleware:
             )
 
         # Prefer route template for bounded cardinality
-        route_template = _extract_route_template(scope, path)
+        route_template = _extract_route_template(scope, path, status_code)
 
         self.metrics_recorder.observe(
             method=method,

{fastapi_observer-1.8.0 → fastapi_observer-1.9.0}/tests/test_middleware.py

@@ -183,10 +183,11 @@ def test_resolve_request_id_contract() -> None:
 def test_extract_route_template_contract() -> None:
     from fastapiobserver.middleware import _extract_route_template
 
-    assert _extract_route_template({}, "/raw") == "/raw"
+    assert _extract_route_template({}, "/raw", 200) == "/raw"
+    assert _extract_route_template({}, "/raw", 404) == "<unmatched>"
 
     scope = {
         "endpoint": lambda: None,
         "route": type("Route", (), {"path": "/users/{user_id}"})(),
     }
-    assert _extract_route_template(scope, "/raw") == "/users/{user_id}"
+    assert _extract_route_template(scope, "/raw", 404) == "/users/{user_id}"

fastapi_observer-1.9.0/tests/test_route_template_cardinality.py

@@ -0,0 +1,90 @@
+"""Tests for route template extraction to prevent metric cardinality explosion."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from fastapiobserver import ObservabilitySettings, install_observability
+from fastapiobserver.middleware import _extract_route_template  # type: ignore[attr-defined]
+from fastapiobserver.middleware.events import UNMATCHED_ROUTE
+
+
+class _FakeRoute:
+    """Minimal route stub matching Starlette's Route interface."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+
+def test_route_template_preferred_over_raw_path() -> None:
+    """When scope has a matched route, use its template."""
+    scope = {"route": _FakeRoute("/users/{user_id}")}
+    result = _extract_route_template(scope, "/users/alice", 200)
+    assert result == "/users/{user_id}"
+
+
+def test_unmatched_404_gets_the_shared_label() -> None:
+    """No route matched: a 404 must not put its raw path in the label."""
+    scope: dict = {}  # no "route" key
+    assert _extract_route_template(scope, "/nonexistent/path", 404) == UNMATCHED_ROUTE
+
+
+def test_plain_route_without_template_keeps_raw_path() -> None:
+    """FastAPI records no route for plain Starlette routes, such as `/metrics`."""
+    scope: dict = {}
+    assert _extract_route_template(scope, "/metrics", 200) == "/metrics"
+
+
+def test_fallback_when_route_has_no_path_attr() -> None:
+    """Mounted sub-apps may have routes without .path attribute."""
+
+    class _MountedRoute:
+        pass
+
+    scope = {"route": _MountedRoute()}
+    assert _extract_route_template(scope, "/mounted/raw", 200) == "/mounted/raw"
+
+
+def test_route_is_none() -> None:
+    """scope["route"] explicitly set to None."""
+    scope = {"route": None}
+    assert _extract_route_template(scope, "/somewhere", 404) == UNMATCHED_ROUTE
+
+
+def test_nested_route_template() -> None:
+    """Deeply nested route with multiple parameters."""
+    scope = {"route": _FakeRoute("/orgs/{org_id}/teams/{team_id}/members")}
+    result = _extract_route_template(scope, "/orgs/acme-corp/teams/eng/members", 200)
+    assert result == "/orgs/{org_id}/teams/{team_id}/members"
+
+
+def test_scanner_404s_share_one_metrics_label() -> None:
+    app = FastAPI()
+
+    @app.get("/orders/{order_id}")
+    def order(order_id: int) -> dict[str, int]:
+        return {"order_id": order_id}
+
+    install_observability(app, ObservabilitySettings(metrics_enabled=True))
+    client = TestClient(app)  # no lifespan: exclusions must still apply
+
+    def unmatched_requests() -> float:
+        return sum(
+            float(line.rsplit(" ", 1)[1])
+            for line in client.get("/metrics").text.splitlines()
+            if line.startswith("http_requests_total{") and f'path="{UNMATCHED_ROUTE}"' in line
+        )
+
+    before = unmatched_requests()
+    probes = [f"/probe-{uuid.uuid4().hex[:8]}.php" for _ in range(20)]
+    for path in probes:
+        assert client.get(path).status_code == 404
+    after_probes = unmatched_requests()
+    client.get("/healthz")  # excluded by default, though no route serves it
+
+    assert after_probes - before == 20
+    assert unmatched_requests() == after_probes
+    assert not any(path in client.get("/metrics").text for path in probes)

fastapi_observer-1.8.0/src/fastapiobserver/_version.py

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

fastapi_observer-1.8.0/tests/test_route_template_cardinality.py

@@ -1,51 +0,0 @@
-"""Tests for route template extraction to prevent metric cardinality explosion."""
-
-from __future__ import annotations
-
-from fastapiobserver.middleware import _extract_route_template  # type: ignore[attr-defined]
-
-
-class _FakeRoute:
-    """Minimal route stub matching Starlette's Route interface."""
-
-    def __init__(self, path: str) -> None:
-        self.path = path
-
-
-def test_route_template_preferred_over_raw_path() -> None:
-    """When scope has a matched route, use its template."""
-    scope = {"route": _FakeRoute("/users/{user_id}")}
-    result = _extract_route_template(scope, "/users/alice")
-    assert result == "/users/{user_id}"
-
-
-def test_fallback_to_raw_path_when_no_route() -> None:
-    """404 / unmatched — no route in scope → raw path used."""
-    scope: dict = {}  # no "route" key
-    result = _extract_route_template(scope, "/nonexistent/path")
-    assert result == "/nonexistent/path"
-
-
-def test_fallback_when_route_has_no_path_attr() -> None:
-    """Mounted sub-apps may have routes without .path attribute."""
-
-    class _MountedRoute:
-        pass
-
-    scope = {"route": _MountedRoute()}
-    result = _extract_route_template(scope, "/mounted/raw")
-    assert result == "/mounted/raw"
-
-
-def test_route_is_none() -> None:
-    """scope["route"] explicitly set to None."""
-    scope = {"route": None}
-    result = _extract_route_template(scope, "/somewhere")
-    assert result == "/somewhere"
-
-
-def test_nested_route_template() -> None:
-    """Deeply nested route with multiple parameters."""
-    scope = {"route": _FakeRoute("/orgs/{org_id}/teams/{team_id}/members")}
-    result = _extract_route_template(scope, "/orgs/acme-corp/teams/eng/members")
-    assert result == "/orgs/{org_id}/teams/{team_id}/members"