iii-observability 0.13.0.dev1__py3-none-any.whl

iii_observability/__init__.py

@@ -0,0 +1,58 @@
+"""iii-observability: shared OTel + Logger primitives."""
+
+from .baggage_span_processor import DEFAULT_ALLOWLIST, BaggageSpanProcessor
+from .http_instrumentation import execute_traced_request
+from .logger import Logger
+from .payload import (
+    REDACTED_PLACEHOLDER,
+    redact,
+    redact_and_truncate,
+    resolve_max_bytes_from_env,
+)
+from .reconnection import ReconnectionConfig
+from .span_ops import (
+    current_span_is_recording,
+    record_span_event,
+    set_current_span_attribute,
+    set_current_span_error,
+)
+from .telemetry import (
+    current_span_id,
+    current_trace_id,
+    extract_baggage,
+    extract_traceparent,
+    flush_otel,
+    init_otel,
+    inject_baggage,
+    inject_traceparent,
+    shutdown_otel,
+    with_span,
+)
+from .telemetry_types import OtelConfig
+
+__all__ = [
+    "BaggageSpanProcessor",
+    "DEFAULT_ALLOWLIST",
+    "Logger",
+    "OtelConfig",
+    "REDACTED_PLACEHOLDER",
+    "ReconnectionConfig",
+    "current_span_id",
+    "current_span_is_recording",
+    "current_trace_id",
+    "execute_traced_request",
+    "extract_baggage",
+    "extract_traceparent",
+    "flush_otel",
+    "init_otel",
+    "inject_baggage",
+    "inject_traceparent",
+    "record_span_event",
+    "redact",
+    "redact_and_truncate",
+    "resolve_max_bytes_from_env",
+    "set_current_span_attribute",
+    "set_current_span_error",
+    "shutdown_otel",
+    "with_span",
+]

iii_observability/baggage_span_processor.py

@@ -0,0 +1,42 @@
+"""Baggage -> span attribute processor."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from opentelemetry import baggage
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+#: DEFAULT_ALLOWLIST drift across languages would break worker chains;
+#: lockstep tests in each SDK pin this constant at CI time.
+DEFAULT_ALLOWLIST: tuple[str, ...] = (
+    "iii.session.id",
+    "iii.message.id",
+    "iii.function.id",
+)
+
+
+class BaggageSpanProcessor(SpanProcessor):
+
+    def __init__(self, allowlist: Sequence[str] = DEFAULT_ALLOWLIST) -> None:
+        self._allowlist: tuple[str, ...] = tuple(allowlist)
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        # NoOp guard: skip allocation when sampler drops the span.
+        if not span.is_recording():
+            return
+
+        for key in self._allowlist:
+            value = baggage.get_baggage(key, parent_context)
+            if value is not None:
+                span.set_attribute(key, str(value))
+
+    def on_end(self, span: ReadableSpan) -> None:  # noqa: ARG002
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:  # noqa: ARG002
+        return True

iii_observability/http_instrumentation.py

@@ -0,0 +1,102 @@
+"""HTTP client auto-instrumentation for the iii Python SDK.
+
+Mirrors the Rust execute_traced_request shape: wraps an httpx Request in an
+OTel CLIENT span with HTTP semantic-convention attributes, injects W3C
+traceparent into outgoing headers, and records exceptions on network errors.
+"""
+
+from __future__ import annotations
+
+import httpx
+from opentelemetry import trace
+from opentelemetry.propagate import inject
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+_SAFE_REQUEST_HEADERS = ("content-type", "accept")
+_SAFE_RESPONSE_HEADERS = ("content-type",)
+
+
+def _span_name(method: str, path: str | None) -> str:
+    return f"{method} {path}" if path else method
+
+
+async def execute_traced_request(
+    client: httpx.AsyncClient,
+    request: httpx.Request,
+) -> httpx.Response:
+    """Execute an httpx Request inside an OTel CLIENT span.
+
+    - Injects W3C traceparent into outgoing request headers.
+    - Records HTTP semantic-convention attributes on the span.
+    - Sets ERROR span status for responses with status >= 400.
+    - Records exceptions for network-level errors.
+    """
+    url = request.url
+    method = request.method.upper()
+    path = url.path or None
+    query = url.query
+    query_str: str | None
+    if isinstance(query, bytes):
+        query_str = query.decode() if query else None
+    else:
+        query_str = query or None
+
+    attributes: dict[str, str | int] = {
+        "http.request.method": method,
+        "url.full": str(url),
+    }
+    if url.host:
+        attributes["server.address"] = url.host
+    if url.scheme:
+        attributes["url.scheme"] = url.scheme
+        attributes["network.protocol.name"] = "http"
+    if path:
+        attributes["url.path"] = path
+    if url.port:
+        attributes["server.port"] = url.port
+    if query_str:
+        attributes["url.query"] = query_str
+
+    tracer = trace.get_tracer("iii-python-sdk")
+    name = _span_name(method, path)
+
+    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT, attributes=attributes) as span:
+        carrier: dict[str, str] = {}
+        inject(carrier)
+        for k, v in carrier.items():
+            request.headers[k] = v
+
+        for h in _SAFE_REQUEST_HEADERS:
+            v = request.headers.get(h)
+            if v:
+                span.set_attribute(f"http.request.header.{h}", v)
+        if request.content:
+            span.set_attribute("http.request.body.size", len(request.content))
+
+        try:
+            response = await client.send(request)
+        except httpx.HTTPError as err:
+            span.record_exception(err)
+            span.set_status(Status(StatusCode.ERROR, str(err)))
+            span.set_attribute("error.type", type(err).__name__)
+            raise
+
+        span.set_attribute("http.response.status_code", response.status_code)
+        cl = response.headers.get("content-length")
+        if cl:
+            try:
+                span.set_attribute("http.response.body.size", int(cl))
+            except ValueError:
+                pass
+        for h in _SAFE_RESPONSE_HEADERS:
+            v = response.headers.get(h)
+            if v:
+                span.set_attribute(f"http.response.header.{h}", v)
+
+        if response.status_code >= 400:
+            span.set_status(Status(StatusCode.ERROR, str(response.status_code)))
+            span.set_attribute("error.type", str(response.status_code))
+        else:
+            span.set_status(Status(StatusCode.OK))
+
+        return response

iii_observability/logger.py

@@ -0,0 +1,184 @@
+"""Logger implementation for the III SDK."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+log = logging.getLogger("iii.logger")
+
+_SEVERITY_MAP = {
+    "info": ("INFO", 9),  # SeverityNumber.INFO
+    "warn": ("WARN", 13),  # SeverityNumber.WARN
+    "error": ("ERROR", 17),  # SeverityNumber.ERROR
+    "debug": ("DEBUG", 5),  # SeverityNumber.DEBUG
+}
+
+
+def _is_initialized() -> bool:
+    """Internal: True if OTel has been initialized. Imported lazily to avoid a circular import."""
+    from .telemetry import _is_initialized as _check
+
+    return _check()
+
+
+class Logger:
+    """Structured logger that emits logs as OpenTelemetry LogRecords.
+
+    Every log call automatically captures the active trace and span context,
+    correlating your logs with distributed traces without any manual wiring.
+    When OTel is not initialized, Logger gracefully falls back to Python
+    ``logging``.
+
+    Pass structured data as the second argument to any log method. Using a
+    dict of key-value pairs (instead of string interpolation) lets you
+    filter, aggregate, and build dashboards in your observability backend.
+
+    Examples:
+        >>> from iii import Logger
+        >>> logger = Logger()
+        >>>
+        >>> # Basic logging — trace context is injected automatically
+        >>> logger.info('Worker connected')
+        >>>
+        >>> # Structured context for dashboards and alerting
+        >>> logger.info('Order processed', {'order_id': 'ord_123', 'amount': 49.99, 'currency': 'USD'})
+        >>> logger.warn('Retry attempt', {'attempt': 3, 'max_retries': 5, 'endpoint': '/api/charge'})
+        >>> logger.error('Payment failed', {'order_id': 'ord_123', 'gateway': 'stripe', 'error_code': 'card_declined'})
+    """
+
+    def __init__(
+        self,
+        trace_id: str | None = None,
+        service_name: str | None = None,
+        span_id: str | None = None,
+    ) -> None:
+        self._trace_id = trace_id
+        self._service_name = service_name or ""
+        self._span_id = span_id
+
+    def _emit_otel(self, level: str, message: str, data: Any = None) -> bool:
+        """Emit an OTel LogRecord. Returns True if emitted, False if OTel not active."""
+        if not _is_initialized():
+            return False
+        try:
+            from opentelemetry import _logs, trace
+            from opentelemetry._logs import LogRecord, SeverityNumber
+
+            severity_text, severity_num = _SEVERITY_MAP[level]
+            otel_logger = _logs.get_logger("iii.logger")
+            attrs: dict[str, Any] = {"service.name": self._service_name}
+            if data is not None:
+                attrs["log.data"] = data
+
+            span_ctx = trace.get_current_span().get_span_context()
+
+            if self._trace_id is not None:
+                trace_id = int(self._trace_id, 16)
+            elif span_ctx.is_valid:
+                trace_id = span_ctx.trace_id
+            else:
+                trace_id = 0
+
+            if self._span_id is not None:
+                span_id = int(self._span_id, 16)
+            elif span_ctx.is_valid:
+                span_id = span_ctx.span_id
+            else:
+                span_id = 0
+
+            trace_flags = span_ctx.trace_flags if span_ctx.is_valid else trace.TraceFlags(0)
+
+            record = LogRecord(
+                timestamp=time.time_ns(),
+                observed_timestamp=time.time_ns(),
+                severity_text=severity_text,
+                severity_number=SeverityNumber(severity_num),
+                body=message,
+                attributes=attrs,
+                trace_id=trace_id,
+                span_id=span_id,
+                trace_flags=trace_flags,
+            )
+            otel_logger.emit(record)
+            return True
+        except Exception:
+            return False
+
+    def _emit(self, level: str, message: str, data: Any = None) -> None:
+        """Emit a log message via OTel, or Python logging as fallback."""
+        if self._emit_otel(level, message, data):
+            return
+        _LOG_METHODS = {
+            "info": log.info,
+            "warn": log.warning,
+            "error": log.error,
+            "debug": log.debug,
+        }
+        log_fn = _LOG_METHODS.get(level, log.info)
+        log_fn("[%s] %s", self._service_name, message, extra={"data": data})
+
+    def info(self, message: str, data: Any = None) -> None:
+        """Log an info-level message.
+
+        Args:
+            message: Human-readable log message.
+            data: Structured context attached as OTel log attributes.
+                Use dicts of key-value pairs to enable filtering and
+                aggregation in your observability backend (e.g. Grafana,
+                Datadog, New Relic).
+
+        Examples:
+            >>> logger.info('Order processed', {'order_id': 'ord_123', 'status': 'completed'})
+        """
+        self._emit("info", message, data)
+
+    def warn(self, message: str, data: Any = None) -> None:
+        """Log a warning-level message.
+
+        Args:
+            message: Human-readable log message.
+            data: Structured context attached as OTel log attributes.
+                Use dicts of key-value pairs to enable filtering and
+                aggregation in your observability backend (e.g. Grafana,
+                Datadog, New Relic).
+
+        Examples:
+            >>> logger.warn('Retry attempt', {'attempt': 3, 'max_retries': 5, 'endpoint': '/api/charge'})
+        """
+        self._emit("warn", message, data)
+
+    def error(self, message: str, data: Any = None) -> None:
+        """Log an error-level message.
+
+        Args:
+            message: Human-readable log message.
+            data: Structured context attached as OTel log attributes.
+                Use dicts of key-value pairs to enable filtering and
+                aggregation in your observability backend (e.g. Grafana,
+                Datadog, New Relic).
+
+        Examples:
+            >>> logger.error('Payment failed', {
+            ...     'order_id': 'ord_123',
+            ...     'gateway': 'stripe',
+            ...     'error_code': 'card_declined',
+            ... })
+        """
+        self._emit("error", message, data)
+
+    def debug(self, message: str, data: Any = None) -> None:
+        """Log a debug-level message.
+
+        Args:
+            message: Human-readable log message.
+            data: Structured context attached as OTel log attributes.
+                Use dicts of key-value pairs to enable filtering and
+                aggregation in your observability backend (e.g. Grafana,
+                Datadog, New Relic).
+
+        Examples:
+            >>> logger.debug('Cache lookup', {'key': 'user:42', 'hit': False})
+        """
+        self._emit("debug", message, data)

iii_observability/payload.py

@@ -0,0 +1,92 @@
+"""Payload redaction + truncation for invocation event capture."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+REDACTED_PLACEHOLDER = "[REDACTED]"
+_TRUNCATION_MARKER = '..."[TRUNCATED]"'
+
+
+def resolve_max_bytes_from_env() -> Optional[int]:
+    raw = os.environ.get("III_TRACE_PAYLOAD_MAX_BYTES")
+    if raw is None:
+        return None
+    trimmed = raw.strip()
+    if not trimmed or trimmed.lower() == "unlimited":
+        return None
+    try:
+        parsed = int(trimmed)
+    except ValueError:
+        return None
+    if parsed <= 0:
+        return None
+    return parsed
+
+_SENSITIVE_FRAGMENTS = (
+    "api_key",
+    "apikey",
+    "api-key",
+    "password",
+    "secret",
+    "credential",
+    "authorization",
+    "auth_token",
+    "access_token",
+    "refresh_token",
+    "bearer",
+    "private_key",
+    "client_secret",
+)
+
+
+def _is_sensitive_key(key: str) -> bool:
+    lower = key.lower()
+    if any(fragment in lower for fragment in _SENSITIVE_FRAGMENTS):
+        return True
+    # ``token`` alone is too common a substring; require whole-key or suffix match.
+    return lower == "token" or lower.endswith("_token") or lower.endswith("-token")
+
+
+def redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            k: REDACTED_PLACEHOLDER if _is_sensitive_key(k) else redact(v)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(redact(item) for item in value)
+    return value
+
+
+def redact_and_truncate(
+    value: Any, max_bytes: Optional[int] = None
+) -> tuple[str, bool]:
+    redacted = redact(value)
+    try:
+        serialized = json.dumps(redacted, default=str, ensure_ascii=False)
+    except (TypeError, ValueError):
+        serialized = "null"
+
+    if max_bytes is None or max_bytes <= 0:
+        return serialized, False
+
+    encoded = serialized.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return serialized, False
+
+    marker_len = len(_TRUNCATION_MARKER.encode("utf-8"))
+    if max_bytes <= marker_len:
+        return _TRUNCATION_MARKER[:max_bytes], True
+
+    cap = max_bytes - marker_len
+    # Walk back to a UTF-8 boundary so we don't emit half-codepoints.
+    cut = cap
+    while cut > 0 and (encoded[cut] & 0xC0) == 0x80:
+        cut -= 1
+    truncated = encoded[:cut].decode("utf-8", errors="ignore") + _TRUNCATION_MARKER
+    return truncated, True

iii_observability/reconnection.py

@@ -0,0 +1,24 @@
+"""WebSocket reconnection configuration for iii observability connections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ReconnectionConfig:
+    """Configuration for WebSocket reconnection behavior.
+
+    Attributes:
+        initial_delay_ms: Starting delay in milliseconds. Default ``1000``.
+        max_delay_ms: Maximum delay cap in milliseconds. Default ``30000``.
+        backoff_multiplier: Exponential backoff multiplier. Default ``2.0``.
+        jitter_factor: Random jitter factor (0--1). Default ``0.3``.
+        max_retries: Maximum retry attempts. ``-1`` for infinite. Default ``-1``.
+    """
+
+    initial_delay_ms: int = 1000
+    max_delay_ms: int = 30000
+    backoff_multiplier: float = 2.0
+    jitter_factor: float = 0.3
+    max_retries: int = -1

iii_observability/span_ops.py

@@ -0,0 +1,38 @@
+"""High-level span operations so consumers don't need ``opentelemetry``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+
+
+def current_span_is_recording() -> bool:
+    """Returns ``False`` when there is no active span or the sampler dropped it."""
+    span = trace.get_current_span()
+    return bool(span and span.is_recording())
+
+
+def set_current_span_attribute(key: str, value: Any) -> None:
+    """No-op when the current span is not recording."""
+    span = trace.get_current_span()
+    if not span or not span.is_recording():
+        return
+    span.set_attribute(key, value)
+
+
+def set_current_span_error(message: str) -> None:
+    """No-op when there is no active span."""
+    span = trace.get_current_span()
+    if not span:
+        return
+    span.set_status(Status(StatusCode.ERROR, message))
+
+
+def record_span_event(name: str, attrs: dict[str, Any] | None = None) -> None:
+    """No-op when the current span is not recording."""
+    span = trace.get_current_span()
+    if not span or not span.is_recording():
+        return
+    span.add_event(name, attributes=attrs or {})