logbrew-fastapi 0.1.0__py3-none-any.whl

logbrew_fastapi/__init__.py

@@ -0,0 +1,258 @@
+"""FastAPI integration helpers for capturing LogBrew request spans and exceptions."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import FastAPI, Request, Response
+from logbrew_sdk import (
+    LogBrewClient,
+    RecordingTransport,
+    SdkError,
+    SpanAttributes,
+    TransportError,
+    parse_traceparent,
+    span_attributes_from_traceparent,
+)
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.types import ASGIApp
+
+
+@dataclass(slots=True)
+class LogBrewFastAPIConfig:
+    """Runtime options used by the LogBrew FastAPI middleware."""
+
+    client: LogBrewClient
+    transport: RecordingTransport | None = None
+    capture_successful_requests: bool = True
+    capture_exceptions: bool = True
+    flush_on_response: bool = True
+    raise_flush_errors: bool = False
+    service_name: str = "fastapi"
+    span_id_factory: Callable[[], str] | None = None
+
+
+def utc_timestamp() -> str:
+    """Return a LogBrew-compatible UTC timestamp."""
+
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def request_name(request: Request) -> str:
+    """Return the stable request name used for span and issue titles."""
+
+    return f"{request.method} {request.url.path}"
+
+
+def request_metadata(
+    request: Request,
+    *,
+    status_code: int | None = None,
+    duration_ms: float | None = None,
+) -> dict[str, Any]:
+    """Return metadata that is useful for request-level troubleshooting without including query strings."""
+
+    metadata: dict[str, Any] = {
+        "framework": "fastapi",
+        "method": request.method,
+        "path": request.url.path,
+    }
+    route = request.scope.get("route")
+    route_path = getattr(route, "path", None)
+    if isinstance(route_path, str):
+        metadata["route"] = route_path
+    if status_code is not None:
+        metadata["status_code"] = status_code
+    if duration_ms is not None:
+        metadata["duration_ms"] = round(duration_ms, 3)
+    return metadata
+
+
+def capture_request_span(
+    client: LogBrewClient,
+    request: Request,
+    *,
+    status_code: int,
+    duration_ms: float,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+    span_id_factory: Callable[[], str] | None = None,
+) -> str:
+    """Capture a FastAPI request as a LogBrew span event and return its event id."""
+
+    span_event_id = event_id or f"evt_fastapi_span_{uuid.uuid4().hex}"
+    span_seed = span_event_id.replace("-", "_")
+    traceparent = request.headers.get("traceparent")
+    attributes: SpanAttributes = {
+        "name": request_name(request),
+        "traceId": f"trace_{span_seed}",
+        "spanId": f"span_{span_seed}",
+        "status": "ok" if status_code < 500 else "error",
+        "durationMs": duration_ms,
+        "metadata": request_metadata(request, status_code=status_code, duration_ms=duration_ms),
+    }
+    if traceparent:
+        try:
+            parse_traceparent(traceparent)
+            attributes = span_attributes_from_traceparent(
+                traceparent,
+                name=request_name(request),
+                span_id=(span_id_factory or default_span_id_factory)(),
+                status="ok" if status_code < 500 else "error",
+                duration_ms=duration_ms,
+                metadata=request_metadata(request, status_code=status_code, duration_ms=duration_ms),
+            )
+        except SdkError:
+            pass
+    client.span(
+        span_event_id,
+        timestamp or utc_timestamp(),
+        attributes,
+    )
+    return span_event_id
+
+
+def capture_exception(
+    client: LogBrewClient,
+    request: Request,
+    exc: BaseException,
+    *,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+) -> str:
+    """Capture an exception raised while handling a FastAPI request and return its event id."""
+
+    issue_event_id = event_id or f"evt_fastapi_issue_{uuid.uuid4().hex}"
+    client.issue(
+        issue_event_id,
+        timestamp or utc_timestamp(),
+        {
+            "title": f"{request_name(request)} failed",
+            "level": "error",
+            "message": str(exc) or exc.__class__.__name__,
+            "metadata": {
+                **request_metadata(request, status_code=500),
+                "exception_type": exc.__class__.__name__,
+            },
+        },
+    )
+    return issue_event_id
+
+
+class LogBrewFastAPIMiddleware(BaseHTTPMiddleware):
+    """FastAPI middleware that records request spans and exception issues with LogBrew."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        client: LogBrewClient,
+        transport: RecordingTransport | None = None,
+        capture_successful_requests: bool = True,
+        capture_exceptions: bool = True,
+        flush_on_response: bool = True,
+        raise_flush_errors: bool = False,
+        service_name: str = "fastapi",
+        span_id_factory: Callable[[], str] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.config = LogBrewFastAPIConfig(
+            client=client,
+            transport=transport,
+            capture_successful_requests=capture_successful_requests,
+            capture_exceptions=capture_exceptions,
+            flush_on_response=flush_on_response,
+            raise_flush_errors=raise_flush_errors,
+            service_name=service_name,
+            span_id_factory=span_id_factory,
+        )
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        start = time.perf_counter()
+        try:
+            response = await call_next(request)
+        except Exception as exc:
+            duration_ms = (time.perf_counter() - start) * 1000
+            if self.config.capture_exceptions:
+                capture_exception(self.config.client, request, exc)
+                capture_request_span(
+                    self.config.client,
+                    request,
+                    status_code=500,
+                    duration_ms=duration_ms,
+                    span_id_factory=self.config.span_id_factory,
+                )
+                self._flush_if_configured()
+            raise
+
+        duration_ms = (time.perf_counter() - start) * 1000
+        if self.config.capture_successful_requests or response.status_code >= 500:
+            capture_request_span(
+                self.config.client,
+                request,
+                status_code=response.status_code,
+                duration_ms=duration_ms,
+                span_id_factory=self.config.span_id_factory,
+            )
+            self._flush_if_configured()
+        return response
+
+    def _flush_if_configured(self) -> None:
+        if not self.config.flush_on_response or self.config.transport is None:
+            return
+        try:
+            self.config.client.flush(self.config.transport)
+        except (SdkError, TransportError):
+            if self.config.raise_flush_errors:
+                raise
+
+
+def add_logbrew_middleware(
+    app: FastAPI,
+    *,
+    client: LogBrewClient,
+    transport: RecordingTransport | None = None,
+    capture_successful_requests: bool = True,
+    capture_exceptions: bool = True,
+    flush_on_response: bool = True,
+    raise_flush_errors: bool = False,
+    service_name: str = "fastapi",
+    span_id_factory: Callable[[], str] | None = None,
+) -> None:
+    """Install LogBrew request/exception capture middleware on a FastAPI app."""
+
+    app.add_middleware(
+        LogBrewFastAPIMiddleware,
+        client=client,
+        transport=transport,
+        capture_successful_requests=capture_successful_requests,
+        capture_exceptions=capture_exceptions,
+        flush_on_response=flush_on_response,
+        raise_flush_errors=raise_flush_errors,
+        service_name=service_name,
+        span_id_factory=span_id_factory,
+    )
+
+
+def default_span_id_factory() -> str:
+    """Return a fresh W3C-compatible child span id."""
+
+    span_id = uuid.uuid4().hex[:16]
+    return "0000000000000001" if span_id == "0000000000000000" else span_id
+
+
+__all__ = [
+    "LogBrewFastAPIConfig",
+    "LogBrewFastAPIMiddleware",
+    "add_logbrew_middleware",
+    "capture_exception",
+    "capture_request_span",
+    "request_metadata",
+    "request_name",
+    "utc_timestamp",
+]

logbrew_fastapi/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable examples shipped with logbrew-fastapi."""

logbrew_fastapi/examples/__main__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import argparse
+import runpy
+
+EXAMPLES = {
+    "readme-example": "logbrew_fastapi.examples.readme_example",
+    "real-user-smoke": "logbrew_fastapi.examples.real_user_smoke",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run packaged logbrew-fastapi examples.")
+    parser.add_argument("example", nargs="?", choices=sorted(EXAMPLES), default="real-user-smoke")
+    parser.add_argument("--list", action="store_true", help="List packaged examples and commands.")
+    args = parser.parse_args()
+
+    if args.list:
+        print("readme-example -> python -m logbrew_fastapi.examples readme-example")
+        print("real-user-smoke -> python -m logbrew_fastapi.examples real-user-smoke")
+        print("default (real-user-smoke) -> python -m logbrew_fastapi.examples")
+        return 0
+
+    runpy.run_module(EXAMPLES[args.example], run_name="__main__")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

logbrew_fastapi/examples/readme_example.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+from logbrew_fastapi import add_logbrew_middleware
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-fastapi",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = FastAPI()
+add_logbrew_middleware(app, client=client, transport=transport)
+
+
+@app.get("/health")
+def health() -> dict[str, bool]:
+    return {"ok": True}
+
+
+with TestClient(app) as http:
+    response = http.get("/health")
+    print(json.dumps({"ok": response.status_code == 200, "status": response.status_code}), file=sys.stderr)
+
+print(transport.sent_bodies[-1])

logbrew_fastapi/examples/real_user_smoke.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+from logbrew_fastapi import add_logbrew_middleware
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-fastapi",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = FastAPI()
+add_logbrew_middleware(app, client=client, transport=transport, span_id_factory=lambda: "b7ad6b7169203331")
+
+
+@app.get("/health")
+def health() -> dict[str, bool]:
+    return {"ok": True}
+
+
+@app.get("/boom")
+def boom() -> dict[str, bool]:
+    raise RuntimeError("broken handler")
+
+
+with TestClient(app, raise_server_exceptions=False) as http:
+    health_response = http.get(
+        "/health?debug=true",
+        headers={"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+    )
+    boom_response = http.get("/boom")
+
+events = []
+for body in transport.sent_bodies:
+    events.extend(json.loads(body)["events"])
+first_span = events[0]["attributes"]
+
+print(json.dumps({"sdk": client.sdk, "events": events}, indent=2))
+print(
+    json.dumps(
+        {
+            "ok": health_response.status_code == 200 and boom_response.status_code == 500,
+            "requests": 2,
+            "sentBodies": len(transport.sent_bodies),
+            "events": len(events),
+            "pending": client.pending_events(),
+            "traceId": first_span["traceId"],
+            "parentSpanId": first_span["parentSpanId"],
+            "spanId": first_span["spanId"],
+            "path": first_span["metadata"]["path"],
+        }
+    ),
+    file=sys.stderr,
+)

logbrew_fastapi/py.typed

@@ -0,0 +1 @@
+

logbrew_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: logbrew-fastapi
+Version: 0.1.0
+Summary: FastAPI integration for capturing LogBrew request spans and exceptions.
+Author: LogBrew
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LogBrewCo/sdk
+Keywords: logbrew,observability,fastapi,asgi,logs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx2>=2.3
+Requires-Dist: logbrew-sdk==0.1.0
+
+# logbrew-fastapi
+
+FastAPI integration for capturing LogBrew request spans and exceptions with the public Python SDK.
+
+## Install
+
+```bash
+python3 -m pip install logbrew-sdk logbrew-fastapi
+python3 -m logbrew_fastapi.examples --help
+python3 -m logbrew_fastapi.examples --list
+python3 -m logbrew_fastapi.examples readme-example
+python3 -m logbrew_fastapi.examples real-user-smoke
+python3 -m logbrew_fastapi.examples
+```
+
+The package is typed, ships `py.typed`, depends on the core `logbrew-sdk`, and keeps FastAPI as a normal framework dependency instead of bundling or monkeypatching the user's app.
+
+## Example
+
+```python
+from fastapi import FastAPI
+from logbrew_fastapi import add_logbrew_middleware
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-fastapi",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = FastAPI()
+add_logbrew_middleware(
+    app,
+    client=client,
+    transport=transport,
+    span_id_factory=lambda: "b7ad6b7169203331",
+)
+
+
+@app.get("/health")
+def health() -> dict[str, bool]:
+    return {"ok": True}
+```
+
+`add_logbrew_middleware()` records successful requests as span events, records unhandled handler exceptions as issue plus error-span events, and flushes through the provided transport after each response. If no transport is provided, events stay queued on the core client so the app can flush them itself.
+
+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. Use `span_id_factory` only when tests need deterministic child span ids.
+
+By default, transport failures do not break the FastAPI response path. Set `raise_flush_errors=True` in test environments when you want misconfigured transport behavior to fail loudly.
+
+Use a clearly fake placeholder like `LOGBREW_API_KEY` in local examples and tests.

logbrew_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+logbrew_fastapi/__init__.py,sha256=3tO0gmO2QRxYJkO_9yhYuPlO7EJkveR9G40PnMLZwGU,8336
+logbrew_fastapi/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+logbrew_fastapi/examples/__init__.py,sha256=OuaLy8tnELi1k4lXd_zUZBrT-H4cFXC8nNdRV2noo5E,54
+logbrew_fastapi/examples/__main__.py,sha256=DgcI6MB9zsYud4FVYgydv91LRx42IiBrsSTKwdIsj9U,982
+logbrew_fastapi/examples/readme_example.py,sha256=3tf1fDoX0DNW8fEDRjsoJ1kEywlBwNVjH8IJ30qVrBs,777
+logbrew_fastapi/examples/real_user_smoke.py,sha256=c1IIZ8oExA4LqLjNdQrBkLelVLN54FDYsV39AZqyLd4,1690
+logbrew_fastapi-0.1.0.dist-info/METADATA,sha256=ko6f3shX-oRerGYxncAwUB-3emUjUFtN9lMKSdcPM6c,3043
+logbrew_fastapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+logbrew_fastapi-0.1.0.dist-info/top_level.txt,sha256=3pQ3XojprooNP-iW6HGBO5vnJC4ftBXpOKjAC-ZBTKM,16
+logbrew_fastapi-0.1.0.dist-info/RECORD,,

logbrew_fastapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logbrew_fastapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+logbrew_fastapi