logbrew-fastapi 0.1.1__tar.gz → 0.1.2__tar.gz

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logbrew-fastapi
-Version: 0.1.1
+Version: 0.1.2
 Summary: FastAPI integration for capturing LogBrew request spans and exceptions.
 Author: LogBrew
 License-Expression: MIT
@@ -23,6 +23,10 @@ Requires-Dist: logbrew-sdk<0.2.0,>=0.1.1
 
 # logbrew-fastapi
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-espresso-bg-512.png" alt="LogBrew logo" width="96" height="96">
+</p>
+
 FastAPI integration for capturing LogBrew request spans and exceptions with the public Python SDK.
 
 ## Install
@@ -64,6 +68,19 @@ def health() -> dict[str, bool]:
 
 When an incoming request has a valid W3C `traceparent` header, request capture continues that trace by using the incoming `traceId` and parent span id while creating a fresh child span id. Missing or malformed `traceparent` headers keep the existing synthetic request span behavior so bad client headers do not break the app. Automatic metadata uses the request path without query text.
 
+Request duration metrics are opt-in. Set `capture_request_metrics=True` to emit an explicit `http.server.duration` histogram for completed requests:
+
+```python
+add_logbrew_middleware(
+    app,
+    client=client,
+    transport=transport,
+    capture_request_metrics=True,
+)
+```
+
+The metric includes primitive, low-cardinality metadata: `framework`, `method`, `routeTemplate`, `statusCode`, and `statusCodeClass`. Query strings and URL hashes are omitted. Set `capture_successful_requests=False` with `capture_request_metrics=True` when you only want duration metrics and not successful request spans. Avoid user IDs, request payloads, headers, or free-form text in custom metric metadata.
+
 By default, transport failures do not break the FastAPI response path. Set `raise_flush_errors=True` only when your app wants delivery failures to surface as request errors.
 
 Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples.

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/README.md

@@ -1,5 +1,9 @@
 # logbrew-fastapi
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-espresso-bg-512.png" alt="LogBrew logo" width="96" height="96">
+</p>
+
 FastAPI integration for capturing LogBrew request spans and exceptions with the public Python SDK.
 
 ## Install
@@ -41,6 +45,19 @@ def health() -> dict[str, bool]:
 
 When an incoming request has a valid W3C `traceparent` header, request capture continues that trace by using the incoming `traceId` and parent span id while creating a fresh child span id. Missing or malformed `traceparent` headers keep the existing synthetic request span behavior so bad client headers do not break the app. Automatic metadata uses the request path without query text.
 
+Request duration metrics are opt-in. Set `capture_request_metrics=True` to emit an explicit `http.server.duration` histogram for completed requests:
+
+```python
+add_logbrew_middleware(
+    app,
+    client=client,
+    transport=transport,
+    capture_request_metrics=True,
+)
+```
+
+The metric includes primitive, low-cardinality metadata: `framework`, `method`, `routeTemplate`, `statusCode`, and `statusCodeClass`. Query strings and URL hashes are omitted. Set `capture_successful_requests=False` with `capture_request_metrics=True` when you only want duration metrics and not successful request spans. Avoid user IDs, request payloads, headers, or free-form text in custom metric metadata.
+
 By default, transport failures do not break the FastAPI response path. Set `raise_flush_errors=True` only when your app wants delivery failures to surface as request errors.
 
 Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples.

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logbrew-fastapi"
-version = "0.1.1"
+version = "0.1.2"
 description = "FastAPI integration for capturing LogBrew request spans and exceptions."
 readme = "README.md"
 license = "MIT"

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/src/logbrew_fastapi/__init__.py

@@ -12,6 +12,7 @@ from typing import Any
 from fastapi import FastAPI, Request, Response
 from logbrew_sdk import (
     LogBrewClient,
+    MetricAttributes,
     RecordingTransport,
     SdkError,
     SpanAttributes,
@@ -30,10 +31,12 @@ class LogBrewFastAPIConfig:
     client: LogBrewClient
     transport: RecordingTransport | None = None
     capture_successful_requests: bool = True
+    capture_request_metrics: bool = False
     capture_exceptions: bool = True
     flush_on_response: bool = True
     raise_flush_errors: bool = False
     service_name: str = "fastapi"
+    request_metric_name: str = "http.server.duration"
     span_id_factory: Callable[[], str] | None = None
 
 
@@ -73,6 +76,82 @@ def request_metadata(
     return metadata
 
 
+def request_route_template(request: Request) -> str:
+    """Return a low-cardinality FastAPI route template without query strings."""
+
+    route = request.scope.get("route")
+    route_path = getattr(route, "path", None)
+    template = route_path if isinstance(route_path, str) and route_path else request.url.path
+    return route_template_only(template)
+
+
+def route_template_only(value: str) -> str:
+    """Strip query/hash text from a route template and normalize empty values."""
+
+    route_template = value.split("?", 1)[0].split("#", 1)[0].strip()
+    return route_template or "/"
+
+
+def status_code_class(status_code: int) -> str:
+    """Return the coarse HTTP status code class used by request metrics."""
+
+    return f"{status_code // 100}xx" if 100 <= status_code <= 599 else "unknown"
+
+
+def create_request_metric_attributes(
+    request: Request,
+    *,
+    status_code: int,
+    duration_ms: float,
+    metric_name: str = "http.server.duration",
+) -> MetricAttributes:
+    """Create privacy-safe request duration metric attributes for a completed FastAPI request."""
+
+    duration_value = float(duration_ms)
+    if duration_value < 0:
+        duration_value = 0.0
+    return {
+        "name": metric_name,
+        "kind": "histogram",
+        "value": duration_value,
+        "unit": "ms",
+        "temporality": "delta",
+        "metadata": {
+            "framework": "fastapi",
+            "method": request.method,
+            "routeTemplate": request_route_template(request),
+            "statusCode": status_code,
+            "statusCodeClass": status_code_class(status_code),
+        },
+    }
+
+
+def capture_request_metric(
+    client: LogBrewClient,
+    request: Request,
+    *,
+    status_code: int,
+    duration_ms: float,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+    metric_name: str = "http.server.duration",
+) -> str:
+    """Capture a FastAPI request duration metric and return its event id."""
+
+    metric_event_id = event_id or f"evt_fastapi_metric_{uuid.uuid4().hex}"
+    client.metric(
+        metric_event_id,
+        timestamp or utc_timestamp(),
+        create_request_metric_attributes(
+            request,
+            status_code=status_code,
+            duration_ms=duration_ms,
+            metric_name=metric_name,
+        ),
+    )
+    return metric_event_id
+
+
 def capture_request_span(
     client: LogBrewClient,
     request: Request,
@@ -154,10 +233,12 @@ class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
         client: LogBrewClient,
         transport: RecordingTransport | None = None,
         capture_successful_requests: bool = True,
+        capture_request_metrics: bool = False,
         capture_exceptions: bool = True,
         flush_on_response: bool = True,
         raise_flush_errors: bool = False,
         service_name: str = "fastapi",
+        request_metric_name: str = "http.server.duration",
         span_id_factory: Callable[[], str] | None = None,
     ) -> None:
         super().__init__(app)
@@ -165,10 +246,12 @@ class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
             client=client,
             transport=transport,
             capture_successful_requests=capture_successful_requests,
+            capture_request_metrics=capture_request_metrics,
             capture_exceptions=capture_exceptions,
             flush_on_response=flush_on_response,
             raise_flush_errors=raise_flush_errors,
             service_name=service_name,
+            request_metric_name=request_metric_name,
             span_id_factory=span_id_factory,
         )
 
@@ -178,7 +261,8 @@ class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
             response = await call_next(request)
         except Exception as exc:
             duration_ms = (time.perf_counter() - start) * 1000
-            if self.config.capture_exceptions:
+            should_capture_exception = self.config.capture_exceptions
+            if should_capture_exception:
                 capture_exception(self.config.client, request, exc)
                 capture_request_span(
                     self.config.client,
@@ -187,11 +271,21 @@ class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
                     duration_ms=duration_ms,
                     span_id_factory=self.config.span_id_factory,
                 )
+            if self.config.capture_request_metrics:
+                capture_request_metric(
+                    self.config.client,
+                    request,
+                    status_code=500,
+                    duration_ms=duration_ms,
+                    metric_name=self.config.request_metric_name,
+                )
+            if should_capture_exception or self.config.capture_request_metrics:
                 self._flush_if_configured()
             raise
 
         duration_ms = (time.perf_counter() - start) * 1000
-        if self.config.capture_successful_requests or response.status_code >= 500:
+        should_capture_request_span = self.config.capture_successful_requests or response.status_code >= 500
+        if should_capture_request_span:
             capture_request_span(
                 self.config.client,
                 request,
@@ -199,6 +293,15 @@ class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
                 duration_ms=duration_ms,
                 span_id_factory=self.config.span_id_factory,
             )
+        if self.config.capture_request_metrics:
+            capture_request_metric(
+                self.config.client,
+                request,
+                status_code=response.status_code,
+                duration_ms=duration_ms,
+                metric_name=self.config.request_metric_name,
+            )
+        if should_capture_request_span or self.config.capture_request_metrics:
             self._flush_if_configured()
         return response
 
@@ -218,10 +321,12 @@ def add_logbrew_middleware(
     client: LogBrewClient,
     transport: RecordingTransport | None = None,
     capture_successful_requests: bool = True,
+    capture_request_metrics: bool = False,
     capture_exceptions: bool = True,
     flush_on_response: bool = True,
     raise_flush_errors: bool = False,
     service_name: str = "fastapi",
+    request_metric_name: str = "http.server.duration",
     span_id_factory: Callable[[], str] | None = None,
 ) -> None:
     """Install LogBrew request/exception capture middleware on a FastAPI app."""
@@ -231,10 +336,12 @@ def add_logbrew_middleware(
         client=client,
         transport=transport,
         capture_successful_requests=capture_successful_requests,
+        capture_request_metrics=capture_request_metrics,
         capture_exceptions=capture_exceptions,
         flush_on_response=flush_on_response,
         raise_flush_errors=raise_flush_errors,
         service_name=service_name,
+        request_metric_name=request_metric_name,
         span_id_factory=span_id_factory,
     )
 
@@ -251,8 +358,11 @@ __all__ = [
     "LogBrewFastAPIMiddleware",
     "add_logbrew_middleware",
     "capture_exception",
+    "capture_request_metric",
     "capture_request_span",
+    "create_request_metric_attributes",
     "request_metadata",
     "request_name",
+    "request_route_template",
     "utc_timestamp",
 ]

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/src/logbrew_fastapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logbrew-fastapi
-Version: 0.1.1
+Version: 0.1.2
 Summary: FastAPI integration for capturing LogBrew request spans and exceptions.
 Author: LogBrew
 License-Expression: MIT
@@ -23,6 +23,10 @@ Requires-Dist: logbrew-sdk<0.2.0,>=0.1.1
 
 # logbrew-fastapi
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-espresso-bg-512.png" alt="LogBrew logo" width="96" height="96">
+</p>
+
 FastAPI integration for capturing LogBrew request spans and exceptions with the public Python SDK.
 
 ## Install
@@ -64,6 +68,19 @@ def health() -> dict[str, bool]:
 
 When an incoming request has a valid W3C `traceparent` header, request capture continues that trace by using the incoming `traceId` and parent span id while creating a fresh child span id. Missing or malformed `traceparent` headers keep the existing synthetic request span behavior so bad client headers do not break the app. Automatic metadata uses the request path without query text.
 
+Request duration metrics are opt-in. Set `capture_request_metrics=True` to emit an explicit `http.server.duration` histogram for completed requests:
+
+```python
+add_logbrew_middleware(
+    app,
+    client=client,
+    transport=transport,
+    capture_request_metrics=True,
+)
+```
+
+The metric includes primitive, low-cardinality metadata: `framework`, `method`, `routeTemplate`, `statusCode`, and `statusCodeClass`. Query strings and URL hashes are omitted. Set `capture_successful_requests=False` with `capture_request_metrics=True` when you only want duration metrics and not successful request spans. Avoid user IDs, request payloads, headers, or free-form text in custom metric metadata.
+
 By default, transport failures do not break the FastAPI response path. Set `raise_flush_errors=True` only when your app wants delivery failures to surface as request errors.
 
 Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples.

{logbrew_fastapi-0.1.1 → logbrew_fastapi-0.1.2}/tests/test_fastapi_integration.py

@@ -41,6 +41,44 @@ class FastAPIIntegrationTests(unittest.TestCase):
         self.assertEqual(attributes["status"], "ok")
         self.assertEqual(attributes["metadata"]["status_code"], 200)
 
+    def test_request_metrics_can_be_captured_without_request_spans(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport.always_accept()
+        app = FastAPI()
+        add_logbrew_middleware(
+            app,
+            client=sdk_client,
+            transport=transport,
+            capture_successful_requests=False,
+            capture_request_metrics=True,
+        )
+
+        @app.get("/orders/{order_id}")
+        def order_detail(order_id: int) -> dict[str, int]:
+            return {"orderId": order_id}
+
+        with TestClient(app) as http:
+            response = http.get("/orders/42?debug=true#receipt")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(sdk_client.pending_events(), 0)
+        self.assertEqual(len(transport.sent_bodies), 1)
+        payload = json.loads(transport.sent_bodies[0])
+        self.assertEqual([event["type"] for event in payload["events"]], ["metric"])
+        metric = payload["events"][0]["attributes"]
+        self.assertEqual(metric["name"], "http.server.duration")
+        self.assertEqual(metric["kind"], "histogram")
+        self.assertGreaterEqual(metric["value"], 0)
+        self.assertEqual(metric["unit"], "ms")
+        self.assertEqual(metric["temporality"], "delta")
+        metadata = metric["metadata"]
+        self.assertEqual(metadata["framework"], "fastapi")
+        self.assertEqual(metadata["method"], "GET")
+        self.assertEqual(metadata["routeTemplate"], "/orders/{order_id}")
+        self.assertEqual(metadata["statusCode"], 200)
+        self.assertEqual(metadata["statusCodeClass"], "2xx")
+        self.assertNotIn("debug", json.dumps(metadata))
+
     def test_valid_traceparent_continues_request_span(self) -> None:
         sdk_client = make_client()
         transport = RecordingTransport.always_accept()