logbrew-flask 0.1.1__py3-none-any.whl

logbrew_flask/__init__.py

@@ -0,0 +1,402 @@
+"""Flask 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 flask import Flask, Response, g, request
+from flask.signals import got_request_exception
+from logbrew_sdk import (
+    LogBrewClient,
+    LogBrewTraceContext,
+    MetricAttributes,
+    RecordingTransport,
+    SdkError,
+    SpanAttributes,
+    TransportError,
+    create_logbrew_trace_context,
+    get_active_logbrew_trace,
+    parse_traceparent,
+    span_attributes_from_trace_context,
+    trace_metadata,
+    use_logbrew_trace,
+)
+
+
+@dataclass(slots=True)
+class LogBrewFlaskConfig:
+    """Runtime options used by the LogBrew Flask 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 = "flask"
+    request_metric_name: str = "http.server.duration"
+    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() -> str:
+    """Return the stable request name used for span and issue titles."""
+
+    return f"{request.method} {request_route_template()}"
+
+
+def request_metadata(
+    *,
+    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."""
+
+    route_template = request_route_template()
+    metadata: dict[str, Any] = {
+        "framework": "flask",
+        "method": request.method,
+        "routeTemplate": route_template,
+    }
+    if route_template == request.path:
+        metadata["path"] = request.path
+    rule = getattr(request.url_rule, "rule", None)
+    endpoint = getattr(request.url_rule, "endpoint", None)
+    if isinstance(rule, str):
+        metadata["route"] = rule
+    if isinstance(endpoint, str):
+        metadata["endpoint"] = endpoint
+    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 request_route_template() -> str:
+    """Return a low-cardinality Flask route template without query strings."""
+
+    rule = getattr(request.url_rule, "rule", None)
+    template = rule if isinstance(rule, str) and rule else request.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(
+    *,
+    status_code: int,
+    duration_ms: float,
+    metric_name: str = "http.server.duration",
+) -> MetricAttributes:
+    """Create privacy-safe request duration metric attributes for a completed Flask 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": "flask",
+            "method": request.method,
+            "routeTemplate": request_route_template(),
+            "statusCode": status_code,
+            "statusCodeClass": status_code_class(status_code),
+        },
+    }
+
+
+def capture_request_metric(
+    client: LogBrewClient,
+    *,
+    status_code: int,
+    duration_ms: float,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+    metric_name: str = "http.server.duration",
+) -> str:
+    """Capture a Flask request duration metric and return its event id."""
+
+    metric_event_id = event_id or f"evt_flask_metric_{uuid.uuid4().hex}"
+    client.metric(
+        metric_event_id,
+        timestamp or utc_timestamp(),
+        create_request_metric_attributes(
+            status_code=status_code,
+            duration_ms=duration_ms,
+            metric_name=metric_name,
+        ),
+    )
+    return metric_event_id
+
+
+def capture_request_span(
+    client: LogBrewClient,
+    *,
+    status_code: int,
+    duration_ms: float,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+    span_id_factory: Callable[[], str] | None = None,
+    trace: LogBrewTraceContext | None = None,
+) -> str:
+    """Capture a Flask request as a LogBrew span event and return its event id."""
+
+    span_event_id = event_id or f"evt_flask_span_{uuid.uuid4().hex}"
+    trace_context = trace or request_logbrew_trace() or create_request_trace_context(
+        span_id_factory=span_id_factory,
+    )
+    attributes: SpanAttributes = span_attributes_from_trace_context(
+        trace_context,
+        name=request_name(),
+        status="ok" if status_code < 500 else "error",
+        duration_ms=duration_ms,
+        metadata=request_metadata(status_code=status_code, duration_ms=duration_ms),
+    )
+    client.span(
+        span_event_id,
+        timestamp or utc_timestamp(),
+        attributes,
+    )
+    return span_event_id
+
+
+def capture_exception(
+    client: LogBrewClient,
+    exc: BaseException,
+    *,
+    event_id: str | None = None,
+    timestamp: str | None = None,
+    trace: LogBrewTraceContext | None = None,
+) -> str:
+    """Capture an exception raised while handling a Flask request and return its event id."""
+
+    issue_event_id = event_id or f"evt_flask_issue_{uuid.uuid4().hex}"
+    trace_context = trace or request_logbrew_trace() or get_active_logbrew_trace()
+    client.issue(
+        issue_event_id,
+        timestamp or utc_timestamp(),
+        {
+            "title": f"{request_name()} failed",
+            "level": "error",
+            "message": str(exc) or exc.__class__.__name__,
+            "metadata": {
+                **request_metadata(status_code=500),
+                "exception_type": exc.__class__.__name__,
+                **trace_metadata(trace_context),
+            },
+        },
+    )
+    return issue_event_id
+
+
+def add_logbrew_middleware(
+    app: Flask,
+    *,
+    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 = "flask",
+    request_metric_name: str = "http.server.duration",
+    span_id_factory: Callable[[], str] | None = None,
+) -> LogBrewFlaskConfig:
+    """Install LogBrew request/exception capture hooks on a Flask app."""
+
+    config = LogBrewFlaskConfig(
+        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,
+    )
+
+    @app.before_request
+    def logbrew_before_request() -> None:
+        trace_context = create_request_trace_context(span_id_factory=config.span_id_factory)
+        g.logbrew_trace = trace_context
+        g.logbrew_started_at = time.perf_counter()
+        g.logbrew_exception_captured = False
+        g.logbrew_span_captured = False
+        activation = use_logbrew_trace(trace_context)
+        activation.__enter__()
+        g.logbrew_trace_activation = activation
+
+    @app.after_request
+    def logbrew_after_request(response: Response) -> Response:
+        duration_ms = request_duration_ms()
+        exception_captured = bool(getattr(g, "logbrew_exception_captured", False))
+        should_capture_request_span = (
+            not exception_captured and (config.capture_successful_requests or response.status_code >= 500)
+        )
+        if should_capture_request_span:
+            capture_request_span(
+                config.client,
+                status_code=response.status_code,
+                duration_ms=duration_ms,
+                span_id_factory=config.span_id_factory,
+                trace=request_logbrew_trace(),
+            )
+            g.logbrew_span_captured = True
+        if config.capture_request_metrics:
+            capture_request_metric(
+                config.client,
+                status_code=response.status_code,
+                duration_ms=duration_ms,
+                metric_name=config.request_metric_name,
+            )
+        if should_capture_request_span or config.capture_request_metrics:
+            flush_if_configured(config)
+        return response
+
+    @app.teardown_request
+    def logbrew_teardown_request(exc: BaseException | None) -> None:
+        if (
+            exc is not None
+            and not isinstance(exc, (SdkError, TransportError))
+            and config.capture_exceptions
+            and not bool(getattr(g, "logbrew_exception_captured", False))
+        ):
+            capture_exception_and_span(config, exc)
+        activation = getattr(g, "logbrew_trace_activation", None)
+        if activation is not None:
+            activation.__exit__(None, None, None)
+
+    def logbrew_got_request_exception(sender: Flask, exception: BaseException, **_: Any) -> None:
+        if (
+            sender is app
+            and not isinstance(exception, (SdkError, TransportError))
+            and config.capture_exceptions
+            and not bool(getattr(g, "logbrew_exception_captured", False))
+        ):
+            capture_exception_and_span(config, exception)
+
+    got_request_exception.connect(logbrew_got_request_exception, app, weak=False)
+    return config
+
+
+def capture_exception_and_span(config: LogBrewFlaskConfig, exc: BaseException) -> None:
+    """Capture an exception issue and matching error span for the active request."""
+
+    duration_ms = request_duration_ms()
+    trace_context = request_logbrew_trace()
+    capture_exception(config.client, exc, trace=trace_context)
+    capture_request_span(
+        config.client,
+        status_code=500,
+        duration_ms=duration_ms,
+        span_id_factory=config.span_id_factory,
+        trace=trace_context,
+    )
+    g.logbrew_exception_captured = True
+    g.logbrew_span_captured = True
+    if config.capture_request_metrics:
+        capture_request_metric(
+            config.client,
+            status_code=500,
+            duration_ms=duration_ms,
+            metric_name=config.request_metric_name,
+        )
+    flush_if_configured(config)
+
+
+def flush_if_configured(config: LogBrewFlaskConfig) -> None:
+    """Flush the configured client transport if response-path flushing is enabled."""
+
+    if not config.flush_on_response or config.transport is None:
+        return
+    try:
+        config.client.flush(config.transport)
+    except (SdkError, TransportError):
+        if config.raise_flush_errors:
+            raise
+
+
+def request_duration_ms() -> float:
+    """Return elapsed request duration in milliseconds."""
+
+    started_at = getattr(g, "logbrew_started_at", None)
+    if not isinstance(started_at, float):
+        return 0.0
+    return max(0.0, (time.perf_counter() - started_at) * 1000)
+
+
+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
+
+
+def create_request_trace_context(
+    *,
+    span_id_factory: Callable[[], str] | None = None,
+) -> LogBrewTraceContext:
+    """Return a privacy-safe request-local trace context for Flask telemetry."""
+
+    traceparent = request.headers.get("traceparent")
+    if traceparent:
+        try:
+            parse_traceparent(traceparent)
+            return create_logbrew_trace_context(traceparent, span_id_factory=span_id_factory)
+        except SdkError:
+            pass
+    return create_logbrew_trace_context(span_id_factory=span_id_factory)
+
+
+def request_logbrew_trace() -> LogBrewTraceContext | None:
+    """Return the trace context attached to the current Flask request, when present."""
+
+    trace = getattr(g, "logbrew_trace", None)
+    return trace if isinstance(trace, LogBrewTraceContext) else None
+
+
+__all__ = [
+    "LogBrewFlaskConfig",
+    "add_logbrew_middleware",
+    "capture_exception",
+    "capture_request_metric",
+    "capture_request_span",
+    "create_request_metric_attributes",
+    "create_request_trace_context",
+    "get_active_logbrew_trace",
+    "request_logbrew_trace",
+    "request_metadata",
+    "request_name",
+    "request_route_template",
+    "utc_timestamp",
+]

logbrew_flask/examples/__init__.py

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

logbrew_flask/examples/__main__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import argparse
+import runpy
+
+EXAMPLES = {
+    "readme-example": "logbrew_flask.examples.readme_example",
+    "real-user-smoke": "logbrew_flask.examples.real_user_smoke",
+    "outbound-http": "logbrew_flask.examples.outbound_http",
+    "dependency-spans": "logbrew_flask.examples.dependency_spans",
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run packaged logbrew-flask examples.")
+    parser.add_argument("example", nargs="?", default="real-user-smoke", choices=sorted(EXAMPLES))
+    parser.add_argument("--list", action="store_true", help="List available examples and exit.")
+    args = parser.parse_args()
+
+    if args.list:
+        print("readme-example -> python -m logbrew_flask.examples readme-example")
+        print("real-user-smoke -> python -m logbrew_flask.examples real-user-smoke")
+        print("outbound-http -> python -m logbrew_flask.examples outbound-http")
+        print("dependency-spans -> python -m logbrew_flask.examples dependency-spans")
+        print("default (real-user-smoke) -> python -m logbrew_flask.examples")
+        return
+
+    runpy.run_module(EXAMPLES[args.example], run_name="__main__")
+
+
+if __name__ == "__main__":
+    main()

logbrew_flask/examples/dependency_spans.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+from typing import Any, cast
+
+from flask import Flask
+from logbrew_sdk import (
+    LogBrewClient,
+    RecordingTransport,
+    cache_operation_with_logbrew_span,
+    database_operation_with_logbrew_span,
+    queue_operation_with_logbrew_span,
+)
+
+from logbrew_flask import add_logbrew_middleware, get_active_logbrew_trace
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-flask",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = Flask(__name__)
+add_logbrew_middleware(app, client=client, transport=transport, span_id_factory=lambda: "b7ad6b7169203331")
+
+database = sqlite3.connect(":memory:", check_same_thread=False)
+database.execute("CREATE TABLE inventory (sku TEXT PRIMARY KEY, quantity INTEGER NOT NULL)")
+database.execute("INSERT INTO inventory (sku, quantity) VALUES (?, ?)", ("sku_123", 4))
+database.commit()
+cache: dict[str, int] = {"sku_123": 4}
+queue: list[str] = []
+
+
+def select_inventory() -> sqlite3.Row | tuple[Any, ...] | None:
+    return cast(
+        sqlite3.Row | tuple[Any, ...] | None,
+        database.execute("SELECT quantity FROM inventory WHERE sku = ?", ("sku_123",)).fetchone(),
+    )
+
+
+def read_inventory_cache() -> int:
+    return cache["sku_123"]
+
+
+def publish_checkout_event() -> int:
+    queue.append("checkout.completed")
+    return len(queue)
+
+
+@app.post("/checkout/<order_id>")
+def checkout(order_id: str) -> dict[str, object]:
+    trace = get_active_logbrew_trace()
+    inventory_row = database_operation_with_logbrew_span(
+        "SELECT inventory",
+        client=client,
+        event_id="evt_flask_dependency_database",
+        operation=select_inventory,
+        system="sqlite",
+        db_name="checkout",
+        statement_template="SELECT inventory WHERE sku = ?",
+        row_count=1,
+        metadata={"dependency": "inventory"},
+        span_id_factory=lambda: "c8ad6b7169203332",
+    )
+    inventory_count = int(inventory_row[0]) if inventory_row else 0
+    cached_count = cache_operation_with_logbrew_span(
+        "GET inventory",
+        client=client,
+        event_id="evt_flask_dependency_cache",
+        operation=read_inventory_cache,
+        system="memory-cache",
+        cache_name="inventory-cache",
+        cache_hit=True,
+        item_count=1,
+        metadata={"dependency": "inventory-cache"},
+        span_id_factory=lambda: "d9ad6b7169203333",
+    )
+    published_count = queue_operation_with_logbrew_span(
+        "PUBLISH checkout.completed",
+        client=client,
+        event_id="evt_flask_dependency_queue",
+        operation=publish_checkout_event,
+        system="memory-queue",
+        operation_kind="publish",
+        queue_name="checkout-events",
+        task_name="checkout.completed",
+        message_count=1,
+        metadata={"dependency": "checkout-events"},
+        span_id_factory=lambda: "e0ad6b7169203334",
+    )
+    return {
+        "ok": inventory_count == cached_count and published_count == 1,
+        "orderId": order_id,
+        "traceId": trace.trace_id if trace else None,
+        "spanId": trace.span_id if trace else None,
+    }
+
+
+http = app.test_client()
+checkout_response = http.post(
+    "/checkout/order_123?debug=true",
+    headers={"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+)
+
+events: list[dict[str, Any]] = []
+for body in transport.sent_bodies:
+    payload = cast(dict[str, Any], json.loads(body))
+    events.extend(cast(list[dict[str, Any]], payload["events"]))
+spans = {
+    cast(str, event["attributes"]["name"]): cast(dict[str, Any], event["attributes"])
+    for event in events
+    if event["type"] == "span"
+}
+request_span = spans["POST /checkout/<order_id>"]
+database_span = spans["sqlite SELECT inventory"]
+cache_span = spans["memory-cache GET inventory"]
+queue_span = spans["memory-queue PUBLISH checkout.completed"]
+
+print(json.dumps({"sdk": client.sdk, "events": events}, indent=2))
+print(
+    json.dumps(
+        {
+            "checkoutStatus": checkout_response.status_code,
+            "events": len(events),
+            "requestSpanId": request_span["spanId"],
+            "databaseParentSpanId": database_span["parentSpanId"],
+            "databaseSpanId": database_span["spanId"],
+            "cacheParentSpanId": cache_span["parentSpanId"],
+            "cacheSpanId": cache_span["spanId"],
+            "queueParentSpanId": queue_span["parentSpanId"],
+            "queueSpanId": queue_span["spanId"],
+            "dependencySpanNames": [database_span["name"], cache_span["name"], queue_span["name"]],
+        },
+        indent=2,
+    ),
+    file=sys.stderr,
+)

logbrew_flask/examples/outbound_http.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from typing import Any, cast
+
+from flask import Flask
+from logbrew_sdk import (
+    LogBrewClient,
+    RecordingTransport,
+    requests_request_with_logbrew_span,
+)
+
+from logbrew_flask import add_logbrew_middleware, get_active_logbrew_trace
+
+
+@dataclass(slots=True)
+class FakePaymentResponse:
+    status_code: int
+
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-flask",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = Flask(__name__)
+add_logbrew_middleware(app, client=client, transport=transport, span_id_factory=lambda: "b7ad6b7169203331")
+captured_outbound_headers: dict[str, str] = {}
+
+
+def fake_payment_request(method: str, url: str, **kwargs: Any) -> FakePaymentResponse:
+    """Caller-owned request seam used by the example instead of making a network call."""
+
+    headers = kwargs.get("headers")
+    if isinstance(headers, dict):
+        captured_outbound_headers.update({str(name): str(value) for name, value in headers.items()})
+    return FakePaymentResponse(status_code=202)
+
+
+@app.post("/checkout/<order_id>")
+def checkout(order_id: str) -> dict[str, object]:
+    trace = get_active_logbrew_trace()
+    response = requests_request_with_logbrew_span(
+        "POST",
+        "https://payments.example.test/payments/authorize?debug_marker=drop",
+        client=client,
+        event_id="evt_flask_outbound_payment",
+        request=fake_payment_request,
+        route_template="/payments/authorize",
+        metadata={"dependency": "payments", "operation": "authorize"},
+        span_id_factory=lambda: "c8ad6b7169203332",
+    )
+    return {
+        "ok": True,
+        "orderId": order_id,
+        "traceId": trace.trace_id if trace else None,
+        "spanId": trace.span_id if trace else None,
+        "paymentStatus": response.status_code,
+        "outboundTraceparent": captured_outbound_headers.get("traceparent"),
+    }
+
+
+http = app.test_client()
+checkout_response = http.post(
+    "/checkout/order_123?debug=true",
+    headers={"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+)
+
+events: list[dict[str, Any]] = []
+for body in transport.sent_bodies:
+    payload = cast(dict[str, Any], json.loads(body))
+    events.extend(cast(list[dict[str, Any]], payload["events"]))
+checkout_payload = cast(dict[str, Any], checkout_response.get_json())
+spans = {
+    cast(str, event["attributes"]["name"]): cast(dict[str, Any], event["attributes"])
+    for event in events
+    if event["type"] == "span"
+}
+request_span = spans["POST /checkout/<order_id>"]
+outbound_span = spans["POST /payments/authorize"]
+outbound_metadata = cast(dict[str, Any], outbound_span["metadata"])
+
+print(json.dumps({"sdk": client.sdk, "events": events}, indent=2))
+print(
+    json.dumps(
+        {
+            "checkoutStatus": checkout_response.status_code,
+            "events": len(events),
+            "requestSpanId": request_span["spanId"],
+            "outboundParentSpanId": outbound_span["parentSpanId"],
+            "outboundSpanId": outbound_span["spanId"],
+            "outboundTraceparent": checkout_payload["outboundTraceparent"],
+            "outboundRoute": outbound_metadata["routeTemplate"],
+            "outboundSource": outbound_metadata["source"],
+        },
+        indent=2,
+    ),
+    file=sys.stderr,
+)

logbrew_flask/examples/readme_example.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from flask import Flask
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+from logbrew_flask import add_logbrew_middleware
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-flask",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+app = Flask(__name__)
+add_logbrew_middleware(app, client=client, transport=transport)
+
+
+@app.get("/health")
+def health() -> dict[str, bool]:
+    return {"ok": True}
+
+
+response = app.test_client().get("/health")
+print(json.dumps({"status": response.status_code, "events": client.pending_events()}), file=sys.stderr)
+print(transport.sent_bodies[-1])

logbrew_flask/examples/real_user_smoke.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any, cast
+
+from flask import Flask
+from logbrew_sdk import LogBrewClient, LogBrewLoggingHandler, RecordingTransport
+
+from logbrew_flask import add_logbrew_middleware, get_active_logbrew_trace
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-flask",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+logger = logging.getLogger("flask.checkout.example")
+logger.handlers = []
+logger.propagate = False
+logger.setLevel(logging.INFO)
+logger.addHandler(LogBrewLoggingHandler(client, metadata={"service": "checkout"}))
+app = Flask(__name__)
+add_logbrew_middleware(app, client=client, transport=transport, span_id_factory=lambda: "b7ad6b7169203331")
+
+
+@app.get("/health")
+def health() -> dict[str, object]:
+    trace = get_active_logbrew_trace()
+    logger.info("health request", extra={"route_template": "/health"})
+    return {
+        "ok": True,
+        "traceId": trace.trace_id if trace else None,
+        "spanId": trace.span_id if trace else None,
+    }
+
+
+@app.get("/boom")
+def boom() -> dict[str, bool]:
+    raise RuntimeError("broken handler")
+
+
+http = app.test_client()
+health_response = http.get(
+    "/health?debug=true",
+    headers={"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+)
+boom_response = http.get("/boom")
+
+events: list[dict[str, Any]] = []
+for body in transport.sent_bodies:
+    payload = cast(dict[str, Any], json.loads(body))
+    events.extend(cast(list[dict[str, Any]], payload["events"]))
+health_payload = cast(dict[str, Any], health_response.get_json())
+first_span_attributes = cast(dict[str, Any], events[1]["attributes"])
+first_span_metadata = cast(dict[str, Any], first_span_attributes["metadata"])
+
+print(json.dumps({"sdk": client.sdk, "events": events}, indent=2))
+print(
+    json.dumps(
+        {
+            "healthStatus": health_response.status_code,
+            "boomStatus": boom_response.status_code,
+            "events": len(events),
+            "traceId": health_payload["traceId"],
+            "spanId": health_payload["spanId"],
+            "parentSpanId": first_span_attributes["parentSpanId"],
+            "path": first_span_metadata["path"],
+        },
+        indent=2,
+    ),
+    file=sys.stderr,
+)

logbrew_flask/py.typed

@@ -0,0 +1 @@
+

logbrew_flask-0.1.1.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: logbrew-flask
+Version: 0.1.1
+Summary: Flask integration for capturing LogBrew request spans and exceptions.
+Author: LogBrew
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LogBrewCo/sdk
+Keywords: logbrew,observability,flask,wsgi,logs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+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: Flask>=3.1
+Requires-Dist: logbrew-sdk<0.2.0,>=0.1.1
+
+# logbrew-flask
+
+Flask integration for capturing LogBrew request spans and exceptions with the public Python SDK.
+
+This package is source-only until its first PyPI release. The pip command below requires the package to be available on PyPI; use a local checkout or local wheel when evaluating it before release.
+
+```bash
+python3 -m pip install logbrew-sdk logbrew-flask
+```
+
+The package is typed, ships `py.typed`, depends on the core `logbrew-sdk`, and keeps Flask as a normal framework dependency instead of monkeypatching Flask globally.
+
+Use a project-scoped server ingest key, for example `LOGBREW_SERVER_API_KEY`.
+
+```python
+import os
+
+from flask import Flask
+from logbrew_flask import add_logbrew_middleware
+from logbrew_sdk import LogBrewClient
+
+client = LogBrewClient.create(
+    api_key=os.environ["LOGBREW_SERVER_API_KEY"],
+    release=os.environ.get("LOGBREW_RELEASE"),
+    environment=os.environ.get("LOGBREW_ENVIRONMENT"),
+    sdk_name="checkout-api",
+    sdk_version="1.0.0",
+)
+
+app = Flask(__name__)
+add_logbrew_middleware(app, client=client)
+
+
+@app.get("/health")
+def health() -> dict[str, bool]:
+    return {"ok": True}
+```
+
+## What It Captures
+
+The middleware records one request span for each captured response. It can also record request duration metrics and exception issues.
+
+Request spans use the Flask route template, such as `GET /orders/<int:order_id>`, for low-noise grouping. Span metadata includes `routeTemplate`; concrete dynamic paths are not emitted when a route template is available. Valid inbound W3C `traceparent` headers are continued with a fresh child span id.
+
+Handlers can call `get_active_logbrew_trace()` or use `LogBrewLoggingHandler`; logs emitted during the request share the active request trace and span.
+
+```python
+from logbrew_flask import get_active_logbrew_trace
+
+
+@app.get("/orders/<int:order_id>")
+def order_detail(order_id: int) -> dict[str, str | None]:
+    trace = get_active_logbrew_trace()
+    return {"traceId": trace.trace_id if trace else None}
+```
+
+Set `capture_request_metrics=True` to emit an explicit `http.server.duration` histogram for each request. Apps can pass `span_id_factory` when deterministic child span ids are useful for controlled diagnostics; production apps usually let LogBrew generate span ids.
+
+## Outbound HTTP Child Spans
+
+When a handler calls another service, use the core Python HTTP helpers inside the Flask request. They automatically reuse the active Flask request trace, create a child span, and inject one W3C `traceparent` header whose span id matches the emitted outbound span.
+
+```python
+from logbrew_sdk import requests_request_with_logbrew_span
+
+
+@app.post("/checkout/<order_id>")
+def checkout(order_id: str) -> dict[str, bool]:
+    response = requests_request_with_logbrew_span(
+        "POST",
+        "https://payments.example.com/payments/authorize",
+        client=client,
+        event_id="evt_checkout_payment",
+        route_template="/payments/authorize",
+    )
+    return {"accepted": response.status_code == 202}
+```
+
+The helper does not patch `requests` globally. It records method, low-cardinality route template, status code, trace id, span id, and parent span id. It does not capture full URLs, query strings, request bodies, response bodies, arbitrary headers, cookies, baggage, or tracestate.
+
+## Database, Cache, And Queue Child Spans
+
+Use the core dependency helpers inside a Flask handler to connect database, cache, and queue work to the active request trace.
+
+```python
+from logbrew_sdk import (
+    cache_operation_with_logbrew_span,
+    database_operation_with_logbrew_span,
+    queue_operation_with_logbrew_span,
+)
+
+
+@app.post("/checkout/<order_id>")
+def checkout(order_id: str) -> dict[str, bool]:
+    inventory = database_operation_with_logbrew_span(
+        "SELECT inventory",
+        client=client,
+        operation=lambda: database.execute("SELECT quantity FROM inventory WHERE sku = ?", ("sku_123",)).fetchone(),
+        system="sqlite",
+        statement_template="SELECT inventory WHERE sku = ?",
+    )
+    cached_inventory = cache_operation_with_logbrew_span(
+        "GET inventory",
+        client=client,
+        operation=lambda: cache["sku_123"],
+        system="memory-cache",
+        cache_name="inventory-cache",
+        cache_hit=True,
+    )
+    published = queue_operation_with_logbrew_span(
+        "PUBLISH checkout.completed",
+        client=client,
+        operation=lambda: queue.append("checkout.completed") or len(queue),
+        system="memory-queue",
+        operation_kind="publish",
+        queue_name="checkout-events",
+        task_name="checkout.completed",
+    )
+    return {"ok": inventory is not None and cached_inventory > 0 and published == 1}
+```
+
+Run `python -m logbrew_flask.examples dependency-spans` to see a request span with database, cache, and queue child spans under the same trace. These helpers record operation names, systems, status, trace ids, span ids, parent span ids, and primitive metadata. They do not capture SQL bind values, result payloads, queue message payloads, cache values, arbitrary headers, baggage, or tracestate.
+
+## Privacy Defaults
+
+LogBrew does not capture request bodies, response bodies, cookies, arbitrary headers, query strings, raw `traceparent` values, baggage, or tracestate. Exception issues include the exception type and message but not stack frames.
+
+## Delivery Failures
+
+By default, transport failures do not break the Flask response path. Set `raise_flush_errors=True` only when your app wants delivery failures to surface as request errors in controlled diagnostics.
+
+## Tradeoff
+
+Sentry, Datadog, and OpenTelemetry provide broader automatic Flask, outbound HTTP, and dependency instrumentation, including global patching and deeper view/template/client hooks. LogBrew starts with explicit app-owned Flask and dependency helpers because that keeps setup reversible, simple to reason about, and safer for privacy-sensitive services.

logbrew_flask-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+logbrew_flask/__init__.py,sha256=TcVP7cKbXi_USN_t4aWA_SBSEIg40FRxEnBfUpj8WKo,13182
+logbrew_flask/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+logbrew_flask/examples/__init__.py,sha256=HIu2aAxwQQuMjNX1EMHiwgfLl1DeLSm1bqHhm_wfVXA,52
+logbrew_flask/examples/__main__.py,sha256=cJ6Heq5DXyvp7z5WbDdiaHuj2a3tNht2UugKEVx6WaE,1231
+logbrew_flask/examples/dependency_spans.py,sha256=dWyxWzyFeWPdQRrHg_Yg9QnTb9PP3FmQmELFj8ekSnU,4656
+logbrew_flask/examples/outbound_http.py,sha256=jw6lqMwuyEn6tQwy_9hD9adW3enDRjt7obs6JNpjDpQ,3398
+logbrew_flask/examples/readme_example.py,sha256=OKww66742SH0hFjg8EZDnmPryWqxK12p9HBDLszCcLs,707
+logbrew_flask/examples/real_user_smoke.py,sha256=dGIS6ktQ9iI8473OdJFewEOLgjq45G4bVuxeKApF6UU,2324
+logbrew_flask-0.1.1.dist-info/METADATA,sha256=TfQ-23GE4S74UkVN3Adl4TSXDhnalQxcTjQxhmwmtNk,6765
+logbrew_flask-0.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+logbrew_flask-0.1.1.dist-info/top_level.txt,sha256=Ipu3qZol4tpp1xzIgP4O3J1kJ6JyYIUj3ymHfvOgv8o,14
+logbrew_flask-0.1.1.dist-info/RECORD,,

logbrew_flask-0.1.1.dist-info/WHEEL

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

logbrew_flask-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+logbrew_flask