iii-observability 0.13.0.dev1__tar.gz

iii_observability-0.13.0.dev1/.gitignore

@@ -0,0 +1,92 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~

iii_observability-0.13.0.dev1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: iii-observability
+Version: 0.13.0.dev1
+Summary: OpenTelemetry and logging primitives shared across iii SDKs.
+Project-URL: Homepage, https://github.com/iii-hq/iii
+Project-URL: Repository, https://github.com/iii-hq/iii
+Author: III
+License: Apache-2.0
+Keywords: iii,logger,observability,opentelemetry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: opentelemetry-sdk>=1.25
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# iii-observability
+
+OpenTelemetry + Logger primitives shared across the iii SDKs.
+
+See https://github.com/iii-hq/iii for the full project.

iii_observability-0.13.0.dev1/README.md

@@ -0,0 +1,5 @@
+# iii-observability
+
+OpenTelemetry + Logger primitives shared across the iii SDKs.
+
+See https://github.com/iii-hq/iii for the full project.

iii_observability-0.13.0.dev1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iii-observability"
+version = "0.13.0.dev1"
+description = "OpenTelemetry and logging primitives shared across iii SDKs."
+authors = [{ name = "III" }]
+license = { text = "Apache-2.0" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["iii", "observability", "opentelemetry", "logger"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "opentelemetry-api>=1.25",
+    "opentelemetry-sdk>=1.25",
+    "httpx>=0.27",
+    "websockets>=12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/iii-hq/iii"
+Repository = "https://github.com/iii-hq/iii"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=6.0",
+    "pytest-httpx>=0.30",
+    "mypy>=1.8",
+    "ruff>=0.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iii_observability"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=src/iii_observability --cov-branch --cov-report=term-missing"
+testpaths = ["tests"]
+asyncio_mode = "auto"

iii_observability-0.13.0.dev1/src/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-0.13.0.dev1/src/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-0.13.0.dev1/src/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-0.13.0.dev1/src/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-0.13.0.dev1/src/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