logbrew-sdk 0.1.0__py3-none-any.whl

logbrew_sdk/__init__.py

@@ -0,0 +1,758 @@
+"""Public Python client for building, validating, previewing, and flushing LogBrew event batches."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Annotated, Any, Protocol, TypeAlias, TypedDict
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+MetadataValue: TypeAlias = str | int | float | bool | None
+Metadata: TypeAlias = dict[str, MetadataValue]
+
+
+class ReleaseAttributes(TypedDict, total=False):
+    """Public release event attributes."""
+    version: str
+    commit: str
+    notes: str
+    metadata: Metadata
+
+
+class EnvironmentAttributes(TypedDict, total=False):
+    """Public environment event attributes."""
+    name: str
+    region: str
+    metadata: Metadata
+
+
+class IssueAttributes(TypedDict, total=False):
+    """Public issue event attributes."""
+    title: str
+    level: str
+    message: str
+    metadata: Metadata
+
+
+class LogAttributes(TypedDict, total=False):
+    """Public log event attributes."""
+    message: str
+    level: str
+    logger: str
+    metadata: Metadata
+
+
+class SpanAttributes(TypedDict, total=False):
+    """Public span event attributes."""
+    name: str
+    traceId: str
+    spanId: str
+    parentSpanId: str
+    status: str
+    durationMs: float
+    metadata: Metadata
+
+
+class ActionAttributes(TypedDict, total=False):
+    """Public action event attributes."""
+    name: str
+    status: str
+    metadata: Metadata
+
+
+class ScriptedTransportResponse(TypedDict):
+    status_code: int
+
+
+class Transport(Protocol):
+    """Public transport protocol used by client flush, shutdown, and logging helpers."""
+
+    def send(self, api_key: str, body: str) -> TransportResponse:
+        """Send an already serialized event batch body."""
+
+
+ISSUE_LEVELS = {"info", "warning", "error", "critical"}
+LOG_LEVELS = {"debug", "info", "warning", "error"}
+SPAN_STATUSES = {"ok", "error"}
+ACTION_STATUSES = {"queued", "running", "success", "failure"}
+DEFAULT_HTTP_ENDPOINT = "https://api.logbrew.com/v1/events"
+TRACEPARENT_PATTERN = re.compile(r"^([0-9a-fA-F]{2})-([0-9a-fA-F]{32})-([0-9a-fA-F]{16})-([0-9a-fA-F]{2})$")
+ZERO_TRACE_ID = "00000000000000000000000000000000"
+ZERO_SPAN_ID = "0000000000000000"
+
+LOG_RECORD_BUILTINS = frozenset(
+    logging.LogRecord(
+        name="logbrew",
+        level=logging.INFO,
+        pathname="logbrew.py",
+        lineno=1,
+        msg="",
+        args=(),
+        exc_info=None,
+    ).__dict__
+) | {"message", "asctime"}
+
+
+@dataclass(slots=True)
+class SdkError(Exception):
+    """Stable public SDK error with parseable code and message fields."""
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+
+@dataclass(slots=True)
+class TransportError(Exception):
+    """Transport failure with a stable public code and retry hint."""
+    code: str
+    message: str
+    retryable: bool = False
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+    @classmethod
+    def network(cls, message: str) -> TransportError:
+        """Create a retryable network failure that preserves queued events."""
+        return cls(code="network_failure", message=message, retryable=True)
+
+
+@dataclass(slots=True)
+class TransportResponse:
+    """Stable transport response returned from flush and shutdown operations."""
+    status_code: Annotated[int, "Final HTTP-like status returned by the transport."]
+    attempts: Annotated[int, "Number of transport attempts used for the flush."]
+
+
+@dataclass(frozen=True, slots=True)
+class TraceparentContext:
+    """Parsed W3C traceparent context."""
+
+    version: str
+    trace_id: str
+    parent_span_id: str
+    trace_flags: str
+    sampled: bool
+
+
+class RecordingTransport:
+    """Scripted transport for previewing, accepting, or failing queued event flushes."""
+
+    sent_bodies: Annotated[list[str], "Every request body sent through this transport instance."]
+
+    def __init__(
+        self,
+        scripted_responses: list[ScriptedTransportResponse | Exception] | None = None,
+    ) -> None:
+        self.scripted_responses = list(scripted_responses or [{"status_code": 202}])
+        self.sent_bodies: list[str] = []
+
+    @classmethod
+    def always_accept(cls) -> RecordingTransport:
+        """Create a transport that accepts queued flushes with a 202 response."""
+        return cls([{"status_code": 202}])
+
+    def last_body(self) -> str | None:
+        """Return the most recent request body sent through this transport."""
+        if not self.sent_bodies:
+            return None
+        return self.sent_bodies[-1]
+
+    def send(self, api_key: str, body: str) -> TransportResponse:
+        require_non_empty("api_key", api_key)
+        self.sent_bodies.append(body)
+
+        next_response = self.scripted_responses.pop(0) if self.scripted_responses else {"status_code": 202}
+        if isinstance(next_response, Exception):
+            raise next_response
+
+        return TransportResponse(status_code=int(next_response["status_code"]), attempts=1)
+
+
+class HttpTransport:
+    """Dependency-free HTTP transport for sending queued batches to LogBrew."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str = DEFAULT_HTTP_ENDPOINT,
+        headers: Mapping[str, str] | None = None,
+        timeout: float = 10.0,
+        open_url: Callable[..., Any] | None = None,
+    ) -> None:
+        require_non_empty("endpoint", endpoint)
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+            raise SdkError("configuration_error", "HttpTransport timeout must be positive")
+        self.endpoint = endpoint
+        self.headers = validate_headers(headers)
+        self.timeout = float(timeout)
+        self.open_url = open_url or urlopen
+
+    def send(self, api_key: str, body: str) -> TransportResponse:
+        """POST one serialized event batch and return the HTTP status."""
+        require_non_empty("api_key", api_key)
+        request = Request(
+            self.endpoint,
+            data=body.encode("utf-8"),
+            headers={
+                "content-type": "application/json",
+                "authorization": f"Bearer {api_key}",
+                **self.headers,
+            },
+            method="POST",
+        )
+        try:
+            response = self.open_url(request, timeout=self.timeout)
+            try:
+                status = getattr(response, "status", None)
+                if status is None:
+                    status = response.getcode()
+                return TransportResponse(status_code=int(status), attempts=1)
+            finally:
+                close_response = getattr(response, "close", None)
+                if callable(close_response):
+                    close_response()
+        except HTTPError as error:
+            return TransportResponse(status_code=int(error.code), attempts=1)
+        except OSError as error:
+            raise TransportError.network(f"http transport failed: {error}") from error
+
+
+class LogBrewClient:
+    """Buffered public client for validating, previewing, and flushing LogBrew events."""
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        api_key: str,
+        sdk_name: str,
+        sdk_version: str,
+        max_retries: int = 2,
+    ) -> LogBrewClient:
+        """Create a client from public SDK identity, retry, and API key settings."""
+        require_non_empty("api_key", api_key)
+        require_non_empty("sdk_name", sdk_name)
+        require_non_empty("sdk_version", sdk_version)
+        return cls(
+            api_key=api_key,
+            sdk={"name": sdk_name, "language": "python", "version": sdk_version},
+            max_retries=max_retries,
+        )
+
+    def __init__(self, *, api_key: str, sdk: dict[str, str], max_retries: int) -> None:
+        self.api_key = api_key
+        self.sdk = sdk
+        self.max_retries = max_retries
+        self.events: list[dict[str, Any]] = []
+        self.closed = False
+
+    def pending_events(self) -> int:
+        """Return the queued event count currently buffered in memory."""
+        return len(self.events)
+
+    def preview_json(self) -> str:
+        """Return the queued event batch as stable, pretty-printed JSON."""
+        return json.dumps({"sdk": self.sdk, "events": self.events}, indent=2)
+
+    def release(self, event_id: str, timestamp: str, attributes: ReleaseAttributes) -> None:
+        self._push_event("release", event_id, timestamp, validate_release(attributes))
+
+    def environment(self, event_id: str, timestamp: str, attributes: EnvironmentAttributes) -> None:
+        self._push_event("environment", event_id, timestamp, validate_environment(attributes))
+
+    def issue(self, event_id: str, timestamp: str, attributes: IssueAttributes) -> None:
+        self._push_event("issue", event_id, timestamp, validate_issue(attributes))
+
+    def log(self, event_id: str, timestamp: str, attributes: LogAttributes) -> None:
+        self._push_event("log", event_id, timestamp, validate_log(attributes))
+
+    def span(self, event_id: str, timestamp: str, attributes: SpanAttributes) -> None:
+        self._push_event("span", event_id, timestamp, validate_span(attributes))
+
+    def action(self, event_id: str, timestamp: str, attributes: ActionAttributes) -> None:
+        self._push_event("action", event_id, timestamp, validate_action(attributes))
+
+    def flush(self, transport: Transport) -> TransportResponse:
+        """Flush queued events through a transport while preserving retry semantics."""
+        if self.closed:
+            raise SdkError("shutdown_error", "client is already shut down")
+        return self._flush_internal(transport)
+
+    def shutdown(self, transport: Transport) -> TransportResponse:
+        """Flush queued events, then mark the client closed so later writes fail."""
+        if self.closed:
+            raise SdkError("shutdown_error", "client is already shut down")
+        response = self._flush_internal(transport)
+        self.closed = True
+        return response
+
+    def _push_event(
+        self,
+        event_type: str,
+        event_id: str,
+        timestamp: str,
+        attributes: dict[str, Any],
+    ) -> None:
+        if self.closed:
+            raise SdkError("shutdown_error", "client is already shut down")
+        require_non_empty("event id", event_id)
+        require_timestamp(timestamp)
+        self.events.append(
+            {
+                "type": event_type,
+                "id": event_id,
+                "timestamp": timestamp,
+                "attributes": attributes,
+            }
+        )
+
+    def _flush_internal(self, transport: Transport) -> TransportResponse:
+        if not self.events:
+            return TransportResponse(status_code=204, attempts=0)
+
+        body = self.preview_json()
+        max_attempts = self.max_retries + 1
+        attempts = 0
+        while attempts < max_attempts:
+            attempts += 1
+            try:
+                response = transport.send(self.api_key, body)
+                if response.status_code == 401:
+                    raise SdkError("unauthenticated", "transport rejected the API key")
+                if 200 <= response.status_code < 300:
+                    self.events.clear()
+                    return TransportResponse(status_code=response.status_code, attempts=attempts)
+                if response.status_code >= 500 and attempts < max_attempts:
+                    continue
+                raise SdkError(
+                    "transport_error",
+                    f"unexpected transport status {response.status_code}",
+                )
+            except SdkError:
+                raise
+            except TransportError as error:
+                if error.retryable and attempts < max_attempts:
+                    continue
+                raise SdkError(error.code, error.message) from error
+
+        raise SdkError("transport_error", "exhausted retries")
+
+
+class LogBrewLoggingHandler(logging.Handler):
+    """Standard-library logging handler that turns LogRecord objects into LogBrew log events."""
+
+    def __init__(
+        self,
+        client: LogBrewClient,
+        transport: Transport | None = None,
+        *,
+        flush_on_emit: bool = False,
+        include_exception_text: bool = False,
+        metadata: Metadata | None = None,
+        raise_flush_errors: bool = False,
+        level: int = logging.NOTSET,
+    ) -> None:
+        super().__init__(level=level)
+        self.client = client
+        self.transport = transport
+        self.flush_on_emit = flush_on_emit
+        self.include_exception_text = include_exception_text
+        self.metadata = dict(metadata or {})
+        self.raise_flush_errors = raise_flush_errors
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Queue one LogBrew log event from a standard-library log record."""
+        try:
+            event_id = default_log_record_event_id(record)
+            self.client.log(
+                event_id,
+                timestamp_from_log_record(record),
+                log_attributes_from_record(
+                    record,
+                    include_exception_text=self.include_exception_text,
+                    metadata=self.metadata,
+                ),
+            )
+            if self.flush_on_emit:
+                self._flush_transport()
+        except Exception:
+            self.handleError(record)
+
+    def flush(self) -> None:
+        """Flush queued records when a transport was provided to the handler."""
+        self.acquire()
+        try:
+            self._flush_transport()
+        finally:
+            self.release()
+
+    def _flush_transport(self) -> None:
+        if self.transport is None or self.client.closed or self.client.pending_events() == 0:
+            return
+        try:
+            self.client.flush(self.transport)
+        except Exception:
+            if self.raise_flush_errors:
+                raise
+
+
+def log_attributes_from_record(
+    record: logging.LogRecord,
+    *,
+    include_exception_text: bool = False,
+    metadata: Metadata | None = None,
+) -> LogAttributes:
+    """Convert a standard-library LogRecord into LogBrew log attributes."""
+    merged_metadata = {
+        **dict(metadata or {}),
+        **metadata_from_log_record(record, include_exception_text=include_exception_text),
+    }
+    return {
+        "message": record.getMessage(),
+        "level": logbrew_level(record.levelno),
+        "logger": record.name,
+        "metadata": merged_metadata,
+    }
+
+
+def metadata_from_log_record(
+    record: logging.LogRecord,
+    *,
+    include_exception_text: bool = False,
+) -> Metadata:
+    """Return privacy-conscious metadata from a standard-library LogRecord."""
+    metadata: Metadata = {
+        "fileName": record.filename,
+        "functionName": record.funcName,
+        "levelName": record.levelname,
+        "levelNumber": record.levelno,
+        "lineNumber": record.lineno,
+        "module": record.module,
+        "processName": record.processName,
+        "threadName": record.threadName,
+    }
+    metadata.update(extra_metadata_from_log_record(record))
+    if record.exc_info is not None:
+        exception = record.exc_info[1]
+        if exception is not None:
+            metadata["exceptionName"] = type(exception).__name__
+            metadata["exceptionMessage"] = str(exception)
+        if include_exception_text:
+            formatter = logging.Formatter()
+            metadata["exceptionText"] = formatter.formatException(record.exc_info)
+    return metadata
+
+
+def extra_metadata_from_log_record(record: logging.LogRecord) -> Metadata:
+    """Collect primitive values passed through logging's extra argument."""
+    metadata: Metadata = {}
+    for key, value in record.__dict__.items():
+        if key in LOG_RECORD_BUILTINS:
+            continue
+        if isinstance(value, str | int | float | bool) or value is None:
+            metadata[key] = value
+    return metadata
+
+
+def timestamp_from_log_record(record: logging.LogRecord) -> str:
+    """Return a UTC ISO-8601 timestamp for a standard-library log record."""
+    return datetime.fromtimestamp(record.created, tz=UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def default_log_record_event_id(record: logging.LogRecord) -> str:
+    """Return a stable event id for a standard-library log record."""
+    millis = int(record.created * 1000)
+    return f"evt_log_{slugify(record.name)}_{millis}_{record.lineno}"
+
+
+def logbrew_level(level_number: int) -> str:
+    """Map standard-library logging levels to LogBrew log levels."""
+    if level_number >= logging.ERROR:
+        return "error"
+    if level_number >= logging.WARNING:
+        return "warning"
+    if level_number >= logging.INFO:
+        return "info"
+    return "debug"
+
+
+def parse_traceparent(traceparent: str) -> TraceparentContext:
+    """Parse and validate a W3C traceparent header."""
+
+    require_non_empty("traceparent", traceparent)
+    match = TRACEPARENT_PATTERN.match(traceparent.strip())
+    if match is None:
+        raise SdkError(
+            "validation_error",
+            "traceparent must use W3C version-traceId-parentSpanId-traceFlags format",
+        )
+
+    version = match.group(1).lower()
+    trace_id = match.group(2).lower()
+    parent_span_id = match.group(3).lower()
+    trace_flags = match.group(4).lower()
+    if version == "ff":
+        raise SdkError("validation_error", "traceparent version ff is not allowed")
+    if trace_id == ZERO_TRACE_ID:
+        raise SdkError("validation_error", "traceparent traceId must not be all zeros")
+    if parent_span_id == ZERO_SPAN_ID:
+        raise SdkError("validation_error", "traceparent parentSpanId must not be all zeros")
+
+    return TraceparentContext(
+        version=version,
+        trace_id=trace_id,
+        parent_span_id=parent_span_id,
+        trace_flags=trace_flags,
+        sampled=(int(trace_flags, 16) & 1) == 1,
+    )
+
+
+def create_traceparent(*, trace_id: str, span_id: str, trace_flags: str = "01") -> str:
+    """Create a W3C traceparent header from explicit trace and span ids."""
+
+    require_trace_id(trace_id)
+    require_span_id("span_id", span_id)
+    require_trace_flags(trace_flags)
+    return f"00-{trace_id.lower()}-{span_id.lower()}-{trace_flags.lower()}"
+
+
+def span_attributes_from_traceparent(
+    traceparent: str,
+    *,
+    name: str,
+    span_id: str,
+    status: str,
+    duration_ms: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> SpanAttributes:
+    """Build LogBrew span attributes that continue an incoming W3C traceparent."""
+
+    context = parse_traceparent(traceparent)
+    require_non_empty("span name", name)
+    require_span_id("span_id", span_id)
+    require_allowed_value("span status", status, SPAN_STATUSES)
+    if duration_ms is not None and (
+        isinstance(duration_ms, bool) or not isinstance(duration_ms, (int, float)) or duration_ms < 0
+    ):
+        raise SdkError("validation_error", "span durationMs must be non-negative")
+
+    safe_metadata = compact_metadata(metadata)
+    return {
+        "name": name,
+        "traceId": context.trace_id,
+        "spanId": span_id.lower(),
+        "parentSpanId": context.parent_span_id,
+        "status": status,
+        **({"durationMs": duration_ms} if duration_ms is not None else {}),
+        **({"metadata": safe_metadata} if safe_metadata is not None else {}),
+    }
+
+
+def slugify(value: str) -> str:
+    normalized = "".join(character.lower() if character.isalnum() else "_" for character in value)
+    return normalized.strip("_") or "logger"
+
+
+def require_trace_id(trace_id: Any) -> None:
+    if not isinstance(trace_id, str) or re.fullmatch(r"[0-9a-fA-F]{32}", trace_id) is None:
+        raise SdkError("validation_error", "traceId must be 32 lowercase or uppercase hex characters")
+    if trace_id.lower() == ZERO_TRACE_ID:
+        raise SdkError("validation_error", "traceId must not be all zeros")
+
+
+def require_span_id(label: str, span_id: Any) -> None:
+    if not isinstance(span_id, str) or re.fullmatch(r"[0-9a-fA-F]{16}", span_id) is None:
+        raise SdkError("validation_error", f"{label} must be 16 lowercase or uppercase hex characters")
+    if span_id.lower() == ZERO_SPAN_ID:
+        raise SdkError("validation_error", f"{label} must not be all zeros")
+
+
+def require_trace_flags(trace_flags: Any) -> None:
+    if not isinstance(trace_flags, str) or re.fullmatch(r"[0-9a-fA-F]{2}", trace_flags) is None:
+        raise SdkError("validation_error", "traceFlags must be 2 lowercase or uppercase hex characters")
+
+
+def compact_metadata(metadata: Mapping[str, Any] | None) -> Metadata | None:
+    if metadata is None:
+        return None
+    if not isinstance(metadata, Mapping):
+        raise SdkError("validation_error", "metadata must be an object")
+    safe_metadata: Metadata = {}
+    for key, value in metadata.items():
+        if isinstance(key, str) and (isinstance(value, str | int | float | bool) or value is None):
+            safe_metadata[key] = value
+    return safe_metadata
+
+
+def validate_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    if headers is None:
+        return {}
+    safe_headers: dict[str, str] = {}
+    for name, value in headers.items():
+        require_non_empty("header name", name)
+        if not isinstance(value, str):
+            raise SdkError("configuration_error", "HttpTransport header values must be strings")
+        safe_headers[name] = value
+    return safe_headers
+
+
+def require_non_empty(label: str, value: Any) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise SdkError("validation_error", f"{label} must be non-empty")
+
+
+def require_allowed_value(label: str, value: Any, allowed_values: set[str]) -> None:
+    require_non_empty(label, value)
+    if value not in allowed_values:
+        allowed = ", ".join(sorted(allowed_values))
+        raise SdkError("validation_error", f"{label} must be one of: {allowed}")
+
+
+def require_timestamp(timestamp: Any) -> None:
+    require_non_empty("timestamp", timestamp)
+    if timestamp.endswith("Z"):
+        return
+    time_portion = timestamp.split("T")[1] if "T" in timestamp else ""
+    if "+" in time_portion:
+        return
+    if "-" in time_portion[1:]:
+        return
+    raise SdkError("validation_error", f"timestamp must include a timezone offset: {timestamp}")
+
+
+def clone_metadata(metadata: Any) -> dict[str, Any] | None:
+    if metadata is None:
+        return None
+    if not isinstance(metadata, dict):
+        raise SdkError("validation_error", "metadata must be an object")
+    return dict(metadata)
+
+
+def with_metadata(attributes: dict[str, Any], metadata: Any) -> dict[str, Any]:
+    safe_metadata = clone_metadata(metadata)
+    if safe_metadata is None:
+        return attributes
+    return {**attributes, "metadata": safe_metadata}
+
+
+def validate_release(attributes: ReleaseAttributes) -> dict[str, Any]:
+    require_non_empty("release version", attributes.get("version"))
+    commit = attributes.get("commit")
+    if commit is not None:
+        require_non_empty("release commit", commit)
+    return with_metadata(
+        {
+            "version": attributes["version"],
+            **({"commit": commit} if commit is not None else {}),
+            **({"notes": attributes["notes"]} if "notes" in attributes else {}),
+        },
+        attributes.get("metadata"),
+    )
+
+
+def validate_environment(attributes: EnvironmentAttributes) -> dict[str, Any]:
+    require_non_empty("environment name", attributes.get("name"))
+    return with_metadata(
+        {
+            "name": attributes["name"],
+            **({"region": attributes["region"]} if "region" in attributes else {}),
+        },
+        attributes.get("metadata"),
+    )
+
+
+def validate_issue(attributes: IssueAttributes) -> dict[str, Any]:
+    require_non_empty("issue title", attributes.get("title"))
+    require_allowed_value("issue level", attributes.get("level"), ISSUE_LEVELS)
+    return with_metadata(
+        {
+            "title": attributes["title"],
+            "level": attributes["level"],
+            **({"message": attributes["message"]} if "message" in attributes else {}),
+        },
+        attributes.get("metadata"),
+    )
+
+
+def validate_log(attributes: LogAttributes) -> dict[str, Any]:
+    require_non_empty("log message", attributes.get("message"))
+    require_allowed_value("log level", attributes.get("level"), LOG_LEVELS)
+    return with_metadata(
+        {
+            "message": attributes["message"],
+            "level": attributes["level"],
+            **({"logger": attributes["logger"]} if "logger" in attributes else {}),
+        },
+        attributes.get("metadata"),
+    )
+
+
+def validate_span(attributes: SpanAttributes) -> dict[str, Any]:
+    require_non_empty("span name", attributes.get("name"))
+    require_non_empty("span traceId", attributes.get("traceId"))
+    require_non_empty("span spanId", attributes.get("spanId"))
+    require_allowed_value("span status", attributes.get("status"), SPAN_STATUSES)
+    parent_span_id = attributes.get("parentSpanId")
+    if parent_span_id is not None:
+        require_non_empty("span parentSpanId", parent_span_id)
+    duration_ms = attributes.get("durationMs")
+    if duration_ms is not None and (
+        isinstance(duration_ms, bool) or not isinstance(duration_ms, (int, float)) or duration_ms < 0
+    ):
+        raise SdkError("validation_error", "span durationMs must be non-negative")
+    return with_metadata(
+        {
+            "name": attributes["name"],
+            "traceId": attributes["traceId"],
+            "spanId": attributes["spanId"],
+            "status": attributes["status"],
+            **({"parentSpanId": parent_span_id} if parent_span_id is not None else {}),
+            **({"durationMs": duration_ms} if duration_ms is not None else {}),
+        },
+        attributes.get("metadata"),
+    )
+
+
+def validate_action(attributes: ActionAttributes) -> dict[str, Any]:
+    require_non_empty("action name", attributes.get("name"))
+    require_allowed_value("action status", attributes.get("status"), ACTION_STATUSES)
+    return with_metadata(
+        {
+            "name": attributes["name"],
+            "status": attributes["status"],
+        },
+        attributes.get("metadata"),
+    )
+
+
+__all__ = [
+    "ActionAttributes",
+    "EnvironmentAttributes",
+    "HttpTransport",
+    "IssueAttributes",
+    "LogAttributes",
+    "LogBrewClient",
+    "LogBrewLoggingHandler",
+    "Metadata",
+    "MetadataValue",
+    "RecordingTransport",
+    "ReleaseAttributes",
+    "SdkError",
+    "SpanAttributes",
+    "TraceparentContext",
+    "Transport",
+    "TransportError",
+    "TransportResponse",
+    "create_traceparent",
+    "log_attributes_from_record",
+    "parse_traceparent",
+    "span_attributes_from_traceparent",
+]

logbrew_sdk/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable packaged examples for installed LogBrew SDK users."""

logbrew_sdk/examples/__main__.py

@@ -0,0 +1,68 @@
+"""Run packaged examples for installed SDK users."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+
+from . import readme_example, real_user_smoke
+
+
+def _example_runners() -> dict[str, Callable[[], int]]:
+    return {
+        "readme-example": readme_example.main,
+        "real-user-smoke": real_user_smoke.main,
+    }
+
+
+def _example_commands() -> dict[str, str]:
+    commands = {
+        name: f"python -m logbrew_sdk.examples {name}" for name in sorted(_example_runners())
+    }
+    commands["default (real-user-smoke)"] = "python -m logbrew_sdk.examples"
+    return commands
+
+
+def _help_epilog() -> str:
+    lines = ["Packaged examples:"]
+    lines.extend(
+        f"  {example} -> {command}" for example, command in _example_commands().items()
+    )
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run the packaged LogBrew SDK examples that ship with the installed Python package.",
+        epilog=_help_epilog(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "example",
+        nargs="?",
+        choices=sorted(_example_runners()),
+        default="real-user-smoke",
+        help="packaged example to run (default: real-user-smoke)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="print the available packaged example names and exit",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.list:
+        for example, command in _example_commands().items():
+            print(f"{example} -> {command}")
+        return 0
+
+    return _example_runners()[args.example]()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

logbrew_sdk/examples/readme_example.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+
+def main() -> int:
+    client = LogBrewClient.create(
+        api_key="LOGBREW_API_KEY",
+        sdk_name="logbrew-python",
+        sdk_version="0.1.0",
+    )
+
+    client.release(
+        "evt_release_001",
+        "2026-06-02T10:00:00Z",
+        {
+            "version": "1.2.3",
+            "commit": "abc123def456",
+            "notes": "Public release marker",
+        },
+    )
+    client.environment(
+        "evt_environment_001",
+        "2026-06-02T10:00:01Z",
+        {"name": "production", "region": "global"},
+    )
+    client.issue(
+        "evt_issue_001",
+        "2026-06-02T10:00:02Z",
+        {
+            "title": "Checkout timeout",
+            "level": "error",
+            "message": "Request timed out after retry budget",
+        },
+    )
+    client.log(
+        "evt_log_001",
+        "2026-06-02T10:00:03Z",
+        {"message": "worker started", "level": "info", "logger": "job-runner"},
+    )
+    client.span(
+        "evt_span_001",
+        "2026-06-02T10:00:04Z",
+        {
+            "name": "GET /health",
+            "traceId": "trace_001",
+            "spanId": "span_001",
+            "status": "ok",
+            "durationMs": 12.5,
+        },
+    )
+    client.action(
+        "evt_action_001",
+        "2026-06-02T10:00:05Z",
+        {"name": "deploy", "status": "success"},
+    )
+
+    print(client.preview_json())
+    transport = RecordingTransport.always_accept()
+    response = client.shutdown(transport)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "status": response.status_code,
+                "attempts": response.attempts,
+                "events": 6,
+            }
+        ),
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

logbrew_sdk/examples/real_user_smoke.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+
+def main() -> int:
+    client = LogBrewClient.create(
+        api_key="LOGBREW_API_KEY",
+        sdk_name="logbrew-python",
+        sdk_version="0.1.0",
+    )
+
+    client.release(
+        "evt_release_001",
+        "2026-06-02T10:00:00Z",
+        {
+            "version": "1.2.3",
+            "commit": "abc123def456",
+            "notes": "Public release marker",
+        },
+    )
+    client.environment(
+        "evt_environment_001",
+        "2026-06-02T10:00:01Z",
+        {"name": "production", "region": "global"},
+    )
+    client.issue(
+        "evt_issue_001",
+        "2026-06-02T10:00:02Z",
+        {
+            "title": "Checkout timeout",
+            "level": "error",
+            "message": "Request timed out after retry budget",
+        },
+    )
+    client.log(
+        "evt_log_001",
+        "2026-06-02T10:00:03Z",
+        {"message": "worker started", "level": "info", "logger": "job-runner"},
+    )
+    client.span(
+        "evt_span_001",
+        "2026-06-02T10:00:04Z",
+        {
+            "name": "GET /health",
+            "traceId": "trace_001",
+            "spanId": "span_001",
+            "status": "ok",
+            "durationMs": 12.5,
+        },
+    )
+    client.action(
+        "evt_action_001",
+        "2026-06-02T10:00:05Z",
+        {"name": "deploy", "status": "success"},
+    )
+
+    print(client.preview_json())
+    transport = RecordingTransport.always_accept()
+    response = client.shutdown(transport)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "status": response.status_code,
+                "attempts": response.attempts,
+                "events": 6,
+            }
+        ),
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

logbrew_sdk/py.typed

@@ -0,0 +1 @@
+

logbrew_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: logbrew-sdk
+Version: 0.1.0
+Summary: Public LogBrew Python SDK for building, validating, and flushing event batches.
+Author: LogBrew
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LogBrewCo/sdk
+Keywords: logbrew,observability,logs,traces,events
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# logbrew-sdk
+
+Public Python SDK for creating LogBrew event batches, validating them locally, and flushing them through a transport.
+
+## Install
+
+```bash
+python3 -m pip install logbrew-sdk
+python3 -m logbrew_sdk.examples --help
+python3 -m logbrew_sdk.examples --list
+python3 -m logbrew_sdk.examples readme-example
+python3 -m logbrew_sdk.examples real-user-smoke
+python3 -m logbrew_sdk.examples
+python3 -m logbrew_sdk.examples.readme_example
+python3 -m logbrew_sdk.examples.real_user_smoke
+```
+
+The built wheel should also carry `py.typed` and wheel metadata with the expected package description before install.
+Normal installs also expose standard package metadata like `pip show logbrew-sdk`, `pip show -f logbrew-sdk`, `pip list --format=json`, `pip freeze`, and `importlib.metadata.version("logbrew-sdk")`. The plain `pip show` summary should keep the expected package name, version, summary, author, license expression, and `site-packages` install location.
+The built source distribution should also carry `README.md`, `pyproject.toml`, `py.typed`, and the packaged `logbrew_sdk.examples.readme_example` plus `logbrew_sdk.examples.real_user_smoke` modules in the archive itself. Both wheel and source-distribution installs carry the expected `py.typed`, example modules, and dist-info metadata files in `site-packages`, and that installed metadata keeps the pip install command, fake `LOGBREW_API_KEY` placeholder, `preview_json()` guidance, and packaged examples entrypoint commands a user would expect from the package description. Those installs should also keep pip-written `INSTALLER`, `direct_url.json`, `--report`, `pip inspect`, plain `pip show` summary fields, `pip show -f` file listings, and `pip list --format=json` package listings plus the expected `pip freeze` file URL with sha256 provenance so tooling can confirm the package came from the expected wheel or source-distribution artifact, the installed environment should stay clean under `python -m pip check`, both the wheel and source-distribution paths should survive a clean `python -m pip uninstall -y logbrew-sdk` removal before reinstalling the same artifact, a small installed-user `python -m unittest` run should still succeed, the published README example should still run from the installed package on both the main install and the reinstall paths, and the packaged examples entrypoint should be discoverable and runnable through `python -m logbrew_sdk.examples --help`, `python -m logbrew_sdk.examples --list`, `python -m logbrew_sdk.examples readme-example`, `python -m logbrew_sdk.examples real-user-smoke`, `python -m logbrew_sdk.examples`, `python -m logbrew_sdk.examples.readme_example`, and `python -m logbrew_sdk.examples.real_user_smoke`, with both `--help` and `--list` printing copy-pasteable packaged-example commands, including explicit named README-example and real-user-smoke entrypoint commands plus the default no-argument `python -m logbrew_sdk.examples` path being called out explicitly as the `real-user-smoke` entrypoint, instead of only generic argument help or bare example names. A one-line direct requirements file derived from that freeze output should also reinstall cleanly under `python -m pip install --require-hashes -r ...` in a fresh virtual environment.
+The installed module, public payload shape types like `ReleaseAttributes`, `SpanAttributes`, and `TraceparentContext`, `LogBrewClient`, `HttpTransport`, `RecordingTransport`, `SdkError`, `TransportResponse`, `TransportError`, W3C trace helpers like `parse_traceparent()`, `create_traceparent()`, and `span_attributes_from_traceparent()`, and key lifecycle methods like `create()`, `preview_json()`, `flush()`, `shutdown()`, `pending_events()`, `always_accept()`, and `TransportError.network()` also expose stable docstrings that tools like `help(...)` can show after install. Installed wheel and sdist paths now both prove the field-level typing metadata for commonly inspected attributes like `TransportResponse.status_code`, `TransportResponse.attempts`, and `RecordingTransport.sent_bodies`, prove the typed consumer through a temp `pyproject.toml`-driven mypy config, and prove a consumer-owned `Makefile` that wraps the installed-user typecheck, unittest, README-example, packaged-example, packaged examples list, packaged examples help, packaged examples entrypoint, packaged real-user example, and happy-path smoke commands instead of relying only on loose raw commands, with plain `make` printing copy-pasteable `make smoke-...` commands and the shorter `make smoke-run` path labeled explicitly as the `real-user-smoke` flow.
+
+## Example
+
+```python
+import json
+import sys
+
+from logbrew_sdk import LogBrewClient, RecordingTransport
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-python",
+    sdk_version="0.1.0",
+)
+
+client.release(
+    "evt_release_001",
+    "2026-06-02T10:00:00Z",
+    {
+        "version": "1.2.3",
+        "commit": "abc123def456",
+        "notes": "Public release marker",
+    },
+)
+client.environment(
+    "evt_environment_001",
+    "2026-06-02T10:00:01Z",
+    {"name": "production", "region": "global"},
+)
+client.issue(
+    "evt_issue_001",
+    "2026-06-02T10:00:02Z",
+    {
+        "title": "Checkout timeout",
+        "level": "error",
+        "message": "Request timed out after retry budget",
+    },
+)
+client.log(
+    "evt_log_001",
+    "2026-06-02T10:00:03Z",
+    {"message": "worker started", "level": "info", "logger": "job-runner"},
+)
+client.span(
+    "evt_span_001",
+    "2026-06-02T10:00:04Z",
+    {
+        "name": "GET /health",
+        "traceId": "trace_001",
+        "spanId": "span_001",
+        "status": "ok",
+        "durationMs": 12.5,
+    },
+)
+client.action(
+    "evt_action_001",
+    "2026-06-02T10:00:05Z",
+    {"name": "deploy", "status": "success"},
+)
+
+print(client.preview_json())
+
+transport = RecordingTransport.always_accept()
+response = client.shutdown(transport)
+print(
+    json.dumps(
+        {"ok": True, "status": response.status_code, "attempts": response.attempts, "events": 6}
+    ),
+    file=sys.stderr,
+)
+```
+
+Use a clearly fake placeholder like `LOGBREW_API_KEY` in local examples and tests. Call `flush()` or `shutdown()` to send queued events through a transport, and use `preview_json()` when you want a stable local JSON preview without sending anything.
+
+## Trace Context
+
+Use the W3C helpers when a Python service needs to interoperate with distributed tracing headers:
+
+```python
+from logbrew_sdk import parse_traceparent, span_attributes_from_traceparent
+
+traceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+context = parse_traceparent(traceparent)
+attributes = span_attributes_from_traceparent(
+    traceparent,
+    name="GET /health",
+    span_id="b7ad6b7169203331",
+    status="ok",
+    duration_ms=12.5,
+    metadata={"service": "checkout"},
+)
+```
+
+`parse_traceparent()` validates W3C shape, rejects all-zero trace/span IDs, normalizes IDs to lowercase, and exposes the sampled flag. `span_attributes_from_traceparent()` returns LogBrew span attributes with `traceId` from the incoming trace and `parentSpanId` from the incoming parent span. FastAPI and Django integrations use these helpers automatically for valid inbound `traceparent` headers and start a fresh synthetic span when the header is missing or malformed.
+
+## HTTP Delivery
+
+Use `HttpTransport` for real outbound delivery from server-side Python apps:
+
+```python
+from logbrew_sdk import HttpTransport, LogBrewClient
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-python",
+    sdk_version="0.1.0",
+)
+transport = HttpTransport(
+    endpoint="https://api.logbrew.com/v1/events",
+    headers={"x-logbrew-source": "python-worker"},
+)
+
+client.log(
+    "evt_worker_started",
+    "2026-06-02T10:00:06Z",
+    {"message": "worker started", "level": "info", "logger": "worker"},
+)
+client.flush(transport)
+```
+
+`HttpTransport` uses Python's standard-library HTTP stack, posts JSON, passes the SDK key through the `authorization` header, supports custom endpoint/header/timeout settings, and maps connection failures into retryable `TransportError.network(...)` failures so `LogBrewClient.flush()` can preserve queued events and retry.
+
+## Standard Logging
+
+Use `LogBrewLoggingHandler` when an application already uses Python's standard `logging` module:
+
+```python
+import logging
+
+from logbrew_sdk import LogBrewClient, LogBrewLoggingHandler, RecordingTransport
+
+client = LogBrewClient.create(
+    api_key="LOGBREW_API_KEY",
+    sdk_name="logbrew-python",
+    sdk_version="0.1.0",
+)
+transport = RecordingTransport.always_accept()
+handler = LogBrewLoggingHandler(
+    client,
+    transport,
+    flush_on_emit=True,
+    metadata={"service": "checkout"},
+)
+
+logger = logging.getLogger("checkout.worker")
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+logger.info("worker started", extra={"order_id": "ord_123"})
+```
+
+The handler does not change global logging configuration. It maps standard logging levels into LogBrew log levels, keeps the logger name, captures primitive `extra={...}` values as metadata, and records source file name, function, line, thread, and process names without sending the full source path by default. Exception type and message are captured when `exc_info` is present; full exception text is opt-in with `include_exception_text=True`.

logbrew_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+logbrew_sdk/__init__.py,sha256=PT_2uoBFshaK-unOAv1CAfglkIKLeXR2v2mJveatZYA,26786
+logbrew_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+logbrew_sdk/examples/__init__.py,sha256=Vkg32KK8LKf_wS7UV-kIvkJGxj8GTraBtV_DNXHdH4c,66
+logbrew_sdk/examples/__main__.py,sha256=aVX8pj8_KtMaHh5sZVvjlRRfwwyR9HjgOnLiH-0JAPo,1857
+logbrew_sdk/examples/readme_example.py,sha256=aZ4QegRJVw3IDePBIAvUzQoIpuU3vIcSYf_c8PXcV6c,1888
+logbrew_sdk/examples/real_user_smoke.py,sha256=aZ4QegRJVw3IDePBIAvUzQoIpuU3vIcSYf_c8PXcV6c,1888
+logbrew_sdk-0.1.0.dist-info/METADATA,sha256=OQXwGaN0U4hjyRPwh6lKxovqfzEhx7D1NlGJq6vDwSI,10071
+logbrew_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+logbrew_sdk-0.1.0.dist-info/top_level.txt,sha256=1oEEYoCow7Aw4_SrnaeLpD_bc9zxLbqIeMdWkJd9HgQ,12
+logbrew_sdk-0.1.0.dist-info/RECORD,,

logbrew_sdk-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_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+logbrew_sdk