logbrew-fastapi 0.1.0__tar.gz

logbrew_fastapi-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,51 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "logbrew-fastapi"
+version = "0.1.0"
+description = "FastAPI integration for capturing LogBrew request spans and exceptions."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+  { name = "LogBrew" }
+]
+keywords = ["logbrew", "observability", "fastapi", "asgi", "logs"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+dependencies = [
+  "fastapi>=0.115",
+  "httpx2>=2.3",
+  "logbrew-sdk==0.1.0"
+]
+
+[project.urls]
+Repository = "https://github.com/LogBrewCo/sdk"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+logbrew_fastapi = ["py.typed"]

logbrew_fastapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

logbrew_fastapi-0.1.0/src/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-0.1.0/src/logbrew_fastapi/examples/__init__.py

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

logbrew_fastapi-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/logbrew_fastapi/py.typed

@@ -0,0 +1 @@
+

logbrew_fastapi-0.1.0/src/logbrew_fastapi.egg-info/PKG-INFO

@@ -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/src/logbrew_fastapi.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/logbrew_fastapi/__init__.py
+src/logbrew_fastapi/py.typed
+src/logbrew_fastapi.egg-info/PKG-INFO
+src/logbrew_fastapi.egg-info/SOURCES.txt
+src/logbrew_fastapi.egg-info/dependency_links.txt
+src/logbrew_fastapi.egg-info/requires.txt
+src/logbrew_fastapi.egg-info/top_level.txt
+src/logbrew_fastapi/examples/__init__.py
+src/logbrew_fastapi/examples/__main__.py
+src/logbrew_fastapi/examples/readme_example.py
+src/logbrew_fastapi/examples/real_user_smoke.py
+tests/test_fastapi_integration.py

logbrew_fastapi-0.1.0/src/logbrew_fastapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

logbrew_fastapi-0.1.0/src/logbrew_fastapi.egg-info/requires.txt

@@ -0,0 +1,3 @@
+fastapi>=0.115
+httpx2>=2.3
+logbrew-sdk==0.1.0

logbrew_fastapi-0.1.0/src/logbrew_fastapi.egg-info/top_level.txt

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

logbrew_fastapi-0.1.0/tests/test_fastapi_integration.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+import unittest
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from logbrew_fastapi import add_logbrew_middleware
+from logbrew_sdk import LogBrewClient, RecordingTransport, SdkError
+
+
+def make_client() -> LogBrewClient:
+    return LogBrewClient.create(
+        api_key="LOGBREW_API_KEY",
+        sdk_name="logbrew-fastapi",
+        sdk_version="0.1.0",
+    )
+
+
+class FastAPIIntegrationTests(unittest.TestCase):
+    def test_successful_request_captures_and_flushes_span(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport.always_accept()
+        app = FastAPI()
+        add_logbrew_middleware(app, client=sdk_client, transport=transport)
+
+        @app.get("/health")
+        def health() -> dict[str, bool]:
+            return {"ok": True}
+
+        with TestClient(app) as http:
+            response = http.get("/health")
+
+        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"]], ["span"])
+        attributes = payload["events"][0]["attributes"]
+        self.assertEqual(attributes["name"], "GET /health")
+        self.assertEqual(attributes["status"], "ok")
+        self.assertEqual(attributes["metadata"]["status_code"], 200)
+
+    def test_valid_traceparent_continues_request_span(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport.always_accept()
+        app = FastAPI()
+        add_logbrew_middleware(
+            app,
+            client=sdk_client,
+            transport=transport,
+            span_id_factory=lambda: "b7ad6b7169203331",
+        )
+
+        @app.get("/trace")
+        def trace() -> dict[str, bool]:
+            return {"ok": True}
+
+        with TestClient(app) as http:
+            response = http.get(
+                "/trace?debug=true",
+                headers={
+                    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+                },
+            )
+
+        self.assertEqual(response.status_code, 200)
+        payload = json.loads(transport.sent_bodies[0])
+        attributes = payload["events"][0]["attributes"]
+        self.assertEqual(attributes["name"], "GET /trace")
+        self.assertEqual(attributes["traceId"], "4bf92f3577b34da6a3ce929d0e0e4736")
+        self.assertEqual(attributes["parentSpanId"], "00f067aa0ba902b7")
+        self.assertEqual(attributes["spanId"], "b7ad6b7169203331")
+        self.assertEqual(attributes["metadata"]["path"], "/trace")
+
+    def test_malformed_traceparent_keeps_synthetic_span_without_span_id_factory(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport.always_accept()
+        span_id_calls = 0
+        app = FastAPI()
+
+        def span_id_factory() -> str:
+            nonlocal span_id_calls
+            span_id_calls += 1
+            return "b7ad6b7169203331"
+
+        add_logbrew_middleware(app, client=sdk_client, transport=transport, span_id_factory=span_id_factory)
+
+        @app.get("/bad")
+        def bad() -> dict[str, bool]:
+            return {"ok": True}
+
+        with TestClient(app) as http:
+            response = http.get("/bad?debug=true", headers={"traceparent": "not-a-valid-traceparent"})
+
+        self.assertEqual(response.status_code, 200)
+        payload = json.loads(transport.sent_bodies[0])
+        attributes = payload["events"][0]["attributes"]
+        self.assertNotIn("parentSpanId", attributes)
+        self.assertTrue(attributes["traceId"].startswith("trace_evt_fastapi_span_"))
+        self.assertEqual(attributes["metadata"]["path"], "/bad")
+        self.assertEqual(span_id_calls, 0)
+
+    def test_exception_captures_issue_and_error_span(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport.always_accept()
+        app = FastAPI()
+        add_logbrew_middleware(app, client=sdk_client, transport=transport)
+
+        @app.get("/boom")
+        def boom() -> dict[str, bool]:
+            raise RuntimeError("broken handler")
+
+        with TestClient(app, raise_server_exceptions=False) as http:
+            response = http.get("/boom")
+
+        self.assertEqual(response.status_code, 500)
+        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"]], ["issue", "span"])
+        issue = payload["events"][0]["attributes"]
+        span = payload["events"][1]["attributes"]
+        self.assertEqual(issue["title"], "GET /boom failed")
+        self.assertEqual(issue["message"], "broken handler")
+        self.assertEqual(issue["metadata"]["exception_type"], "RuntimeError")
+        self.assertEqual(span["status"], "error")
+        self.assertEqual(span["metadata"]["status_code"], 500)
+
+    def test_flush_errors_do_not_break_application_by_default(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport([{"status_code": 401}])
+        app = FastAPI()
+        add_logbrew_middleware(app, client=sdk_client, transport=transport)
+
+        @app.get("/health")
+        def health() -> dict[str, bool]:
+            return {"ok": True}
+
+        with TestClient(app) as http:
+            response = http.get("/health")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(sdk_client.pending_events(), 1)
+
+    def test_flush_errors_can_be_raised_for_test_environments(self) -> None:
+        sdk_client = make_client()
+        transport = RecordingTransport([{"status_code": 401}])
+        app = FastAPI()
+        add_logbrew_middleware(app, client=sdk_client, transport=transport, raise_flush_errors=True)
+
+        @app.get("/health")
+        def health() -> dict[str, bool]:
+            return {"ok": True}
+
+        with TestClient(app) as http, self.assertRaises(SdkError):
+            http.get("/health")
+
+
+if __name__ == "__main__":
+    unittest.main()