threadify-sdk 0.2.0__py3-none-any.whl

threadify/otel_exporter.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk.trace import ReadableSpan
+
+    from threadify.connection import Connection
+
+logger = logging.getLogger("threadify.otel")
+
+# Span status codes (OpenTelemetry proto)
+_STATUS_UNSET = 0
+_STATUS_OK = 1
+_STATUS_ERROR = 2
+
+# Attempt to inherit from SpanExporter when OTel is installed.
+# This makes isinstance() checks in BatchSpanProcessor work correctly.
+try:
+    from opentelemetry.sdk.trace.export import SpanExporter as _SpanExporterBase
+except ImportError:
+    _SpanExporterBase = object  # type: ignore[misc, assignment]
+
+
+def _require_otel() -> None:
+    """Raise ImportError with a helpful message if OpenTelemetry is not installed."""
+    try:
+        import opentelemetry.sdk.trace.export  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "OpenTelemetry is required for ThreadifySpanExporter. "
+            "Install it: pip install opentelemetry-api opentelemetry-sdk"
+        ) from exc
+
+
+class ThreadifySpanExporter(_SpanExporterBase):
+    """OpenTelemetry SpanExporter that auto-translates Spans into Threadify Threads/Steps.
+
+    This hooks into the OpenTelemetry SDK and creates Threadify threads and steps
+    from span data, enabling zero-instrumentation observability for existing
+    OpenTelemetry-instrumented applications.
+
+    Usage::
+
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from threadify import Threadify
+
+        conn = await Threadify.connect("api-key", service_name="my-service", ...)
+        thread = await conn.start(contract_name="order_flow")
+
+        exporter = thread.create_span_exporter(options={"refs": ["orderId"]})
+
+        provider = TracerProvider()
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        trace.set_tracer_provider(provider)
+    """
+
+    def __init__(self, connection: Connection, options: dict[str, Any] | None = None):
+        _require_otel()
+        self._connection = connection
+        self._options = options or {}
+
+        # Normalise refs to a mapping {attribute_key: ref_key}
+        refs = self._options.get("refs", [])
+        if isinstance(refs, list):
+            self._refs_map: dict[str, str] = {k: k for k in refs}
+        elif isinstance(refs, dict):
+            self._refs_map = dict(refs)
+        else:
+            self._refs_map = {}
+
+        # trace_id -> asyncio.Future[ThreadInstance]
+        self._trace_threads: dict[str, asyncio.Future[Any]] = {}
+
+        # Capture the event loop so we can schedule coroutines from sync export().
+        try:
+            self._loop = asyncio.get_running_loop()
+        except RuntimeError:
+            self._loop = None
+
+    def export(
+        self, spans: list[ReadableSpan], timeout_millis: float = 30000
+    ) -> Any:
+        """Export a batch of spans.
+
+        Called by the OpenTelemetry ``BatchSpanProcessor`` (typically from a
+        worker thread). We schedule the async work on the captured event loop.
+        """
+        if not self._connection.is_connected:
+            return self._make_result(1, "Threadify connection is not open")
+
+        if self._loop is None or self._loop.is_closed():
+            return self._make_result(1, "No running event loop available")
+
+        asyncio.run_coroutine_threadsafe(self._process_all(spans), self._loop)
+        return self._make_result(0)
+
+    def force_flush(self, timeout_millis: float = 30000) -> bool:
+        """No-op — spans are sent immediately."""
+        return True
+
+    def shutdown(self) -> None:
+        """No-op — connection lifecycle is managed externally."""
+        return None
+
+    # --- internals ---
+
+    async def _process_all(self, spans: list[ReadableSpan]) -> None:
+        for span in spans:
+            await self._process_span(span)
+
+    async def _process_span(self, span: ReadableSpan) -> None:
+        try:
+            await self._do_process_span(span)
+        except Exception:
+            logger.exception("Failed to process span")
+
+    async def _do_process_span(self, span: ReadableSpan) -> None:
+        ctx = span.span_context
+        trace_id = format(ctx.trace_id, "032x")
+        span_id = format(ctx.span_id, "016x")
+        thread = await self._get_or_start_thread(span, trace_id)
+
+        # Step name
+        step_name = self._span_attr(span, "threadify.step_name") or span.name
+        service_name = self._span_attr(span, "threadify.service")
+        step = thread.step(step_name, service_name or self._connection.service_name)
+
+        # Separate attributes into context / refs
+        context: dict[str, str] = {}
+        refs: dict[str, str] = {
+            "otel_trace_id": trace_id,
+            "otel_span_id": span_id,
+        }
+
+        for key, value in span.attributes.items():
+            # Skip internal threadify directives
+            if key in {
+                "threadify.thread_id",
+                "threadify.contract",
+                "threadify.label",
+                "threadify.step_name",
+                "threadify.role",
+                "threadify.service",
+            }:
+                continue
+
+            str_value = str(value)
+            if key in self._refs_map or key.startswith("threadify.ref."):
+                ref_key = (
+                    key.replace("threadify.ref.", "")
+                    if key.startswith("threadify.ref.")
+                    else self._refs_map[key]
+                )
+                refs[ref_key] = str_value
+            elif key.startswith("threadify.context."):
+                context[key.replace("threadify.context.", "")] = str_value
+            else:
+                context[key] = str_value
+
+        if context:
+            step.add_context(context)
+        if refs:
+            step.add_refs(refs)
+
+        # Map timing (OTel uses nanoseconds since epoch)
+        start_time_ns = span.start_time
+        end_time_ns = span.end_time
+        if start_time_ns:
+            step._event["startedAt"] = _ns_to_iso(start_time_ns)
+        if end_time_ns:
+            step._event["finishedAt"] = _ns_to_iso(end_time_ns)
+
+        # Map span events to sub-steps
+        for event in span.events:
+            event_time_ns = event.timestamp
+            recorded_at = _ns_to_iso(event_time_ns) if event_time_ns else _now_iso()
+            payload: dict[str, Any] = {}
+            if event.attributes:
+                payload = dict(event.attributes)
+            step.sub_step(
+                name=event.name,
+                data=payload,
+                status="success",
+            )
+            # Update recordedAt on the last sub-step data
+            if step._sub_steps:
+                step._sub_steps[-1].recorded_at = recorded_at
+
+        # Map status
+        target_status = STATUS_SUCCESS
+        message = ""
+        if span.status:
+            message = span.status.description or ""
+            try:
+                from opentelemetry.trace.status import StatusCode
+
+                if span.status.status_code is StatusCode.ERROR:
+                    target_status = STATUS_FAILED
+            except Exception:
+                # Defensive: fallback to raw int if enum isn't available
+                if getattr(span.status.status_code, "value", 0) == _STATUS_ERROR:
+                    target_status = STATUS_FAILED
+
+        if target_status == STATUS_SUCCESS:
+            await step.success(message or "")
+        else:
+            await step.failed(message or "Span ended with error status")
+
+        # Root span auto-complete
+        parent_ctx = getattr(span, "parent", None)
+        parent_span_id = format(parent_ctx.span_id, "016x") if parent_ctx else None
+        if not parent_span_id:
+            if target_status == STATUS_SUCCESS:
+                await thread.complete("Root span completed successfully")
+            else:
+                await thread.close("Root span failed")
+            # Clean up the trace map since the trace is finished
+            self._trace_threads.pop(trace_id, None)
+
+    async def _get_or_start_thread(self, span: ReadableSpan, trace_id: str) -> Any:
+        """Get or create a ThreadInstance for this trace."""
+        from threadify.thread import ThreadInstance
+
+        if trace_id not in self._trace_threads:
+            fut: asyncio.Future[Any] = asyncio.get_event_loop().create_future()
+            self._trace_threads[trace_id] = fut
+
+            try:
+                existing_thread_id = self._span_attr(span, "threadify.thread_id")
+                if existing_thread_id:
+                    role = self._span_attr(span, "threadify.role") or "participant"
+                    thread = await self._connection.join(existing_thread_id, role)
+                else:
+                    contract_name = self._span_attr(span, "threadify.contract")
+                    label = self._span_attr(span, "threadify.label") or span.name
+                    service_name = (
+                        self._span_attr(span, "threadify.service")
+                        or self._connection.service_name
+                    )
+                    role = self._span_attr(span, "threadify.role") or "participant"
+
+                    # Try to find an existing thread via GraphQL
+                    try:
+                        archived = await self._connection.get_thread_by_ref(
+                            "otel_trace_id", trace_id
+                        )
+                        if archived:
+                            logger.debug(
+                                "Found existing thread %s via GraphQL, joining...",
+                                archived.id,
+                            )
+                            thread = await self._connection.join(archived.id, role)
+                            fut.set_result(thread)
+                            return thread
+                    except Exception:
+                        pass
+
+                    thread = await self._connection.start(
+                        label=label,
+                        contract_name=contract_name or "",
+                        service_name=service_name,
+                    )
+                fut.set_result(thread)
+            except Exception as exc:
+                fut.set_exception(exc)
+                raise
+
+            # Memory-leak safety: remove after 10 minutes
+            asyncio.get_event_loop().call_later(
+                600, self._trace_threads.pop, trace_id, None
+            )
+
+        return await self._trace_threads[trace_id]
+
+    @staticmethod
+    def _span_attr(span: ReadableSpan, key: str) -> str | None:
+        value = span.attributes.get(key)
+        return str(value) if value is not None else None
+
+    @staticmethod
+    def _make_result(code: int, error: str | None = None) -> Any:
+        """Build an OpenTelemetry ExportResult-compatible object."""
+        try:
+            from opentelemetry.sdk.trace.export import SpanExportResult
+
+            if code == 0:
+                return SpanExportResult.SUCCESS
+            return SpanExportResult.FAILURE
+        except Exception:
+            # Fallback for environments without OTel installed at runtime
+            return {"code": code, "error": error}
+
+
+# --- helpers ---
+
+STATUS_SUCCESS = "success"
+STATUS_FAILED = "failed"
+
+
+def _ns_to_iso(nanoseconds: int) -> str:
+    from datetime import datetime, timezone
+
+    seconds = nanoseconds // 1_000_000_000
+    ns = nanoseconds % 1_000_000_000
+    dt = datetime.fromtimestamp(seconds, tz=timezone.utc)
+    # ISO format with nanoseconds
+    return dt.strftime("%Y-%m-%dT%H:%M:%S") + f".{ns:09d}Z"
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).isoformat()

threadify/step.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from threadify.thread import ThreadInstance
+
+from threadify.models import (
+    ACTION_RECORD_THREAD_EVENT,
+    FIELD_ACTION,
+    FIELD_CONTEXT,
+    FIELD_FINISHED_AT,
+    FIELD_IDEMPOTENCY_KEY,
+    FIELD_IS_DUPLICATE,
+    FIELD_MESSAGE,
+    FIELD_REFS,
+    FIELD_SERVICE_NAME,
+    FIELD_STARTED_AT,
+    FIELD_STATUS,
+    FIELD_STEP_NAME,
+    FIELD_SUB_STEPS,
+    FIELD_THREAD_ID,
+    FIELD_THREADIFY_METADATA,
+    STATUS_ERROR,
+    STATUS_FAILED,
+    STATUS_IN_PROGRESS,
+    STATUS_SUCCESS,
+    StepResult,
+    SubStepData,
+    first_non_empty,
+    now_iso,
+)
+
+
+class ThreadStep:
+    """Fluent builder for recording step events.
+
+    Usage::
+
+        step = thread.step("order_placed")
+        result = await (
+            step
+            .add_context({"orderId": "ORD-123", "amount": 99.99})
+            .add_refs({"stripe_id": "pi_abc"})
+            .success("Order placed!")
+        )
+    """
+
+    def __init__(
+        self,
+        step_name: str,
+        thread: ThreadInstance,
+        service_name: str,
+    ):
+        self._step_name = step_name
+        self._thread = thread
+        self._service_name = service_name
+
+        self._manual_idempotency_key: str = ""
+        self._sub_steps: list[SubStepData] = []
+        self._context: dict[str, str] = {}
+        self._refs: dict[str, str] = {}
+        self._metadata: dict[str, Any] | None = None
+        self._error: Exception | None = None
+
+        self._event: dict[str, Any] = {
+            FIELD_ACTION: ACTION_RECORD_THREAD_EVENT,
+            FIELD_THREAD_ID: thread.thread_id,
+            FIELD_STEP_NAME: step_name,
+            FIELD_STARTED_AT: now_iso(),
+            FIELD_FINISHED_AT: None,
+            FIELD_STATUS: STATUS_IN_PROGRESS,
+            FIELD_SERVICE_NAME: service_name,
+        }
+
+    # --- Fluent builder methods ---
+
+    def idempotency_key(self, key: str) -> ThreadStep:
+        """Set a manual idempotency key for deduplication."""
+        if self._error is not None:
+            return self
+        if not key or not key.strip():
+            self._error = ValueError("idempotency key must be a non-empty string")
+            return self
+        self._manual_idempotency_key = key
+        return self
+
+    def add_context(self, data: dict[str, Any] | None) -> ThreadStep:
+        """Add business context data to this step.
+
+        All values are converted to strings to match the server schema.
+        """
+        if self._error is not None:
+            return self
+        if data:
+            for k, v in data.items():
+                self._context[k] = str(v)
+        return self
+
+    def add_private_context(self, data: dict[str, Any] | None) -> ThreadStep:
+        """Add private context data (prefixed with 'private_')."""
+        if self._error is not None:
+            return self
+        if data:
+            for k, v in data.items():
+                s = str(v)
+                self._context[k] = s
+                self._context[f"private_{k}"] = s
+        return self
+
+    def add_refs(self, refs: dict[str, str] | None) -> ThreadStep:
+        """Add external system references."""
+        if self._error is not None:
+            return self
+        if refs:
+            self._refs.update(refs)
+        return self
+
+    def sub_step(
+        self,
+        name: str,
+        data: dict[str, Any] | None = None,
+        status: str = "success",
+    ) -> ThreadStep:
+        """Record a sub-step within this step.
+
+        Args:
+            name: Sub-step name.
+            data: Optional payload data.
+            status: Must be 'success' or 'failed'.
+        """
+        if self._error is not None:
+            return self
+        if not name or not name.strip():
+            self._error = ValueError("sub-step name must be a non-empty string")
+            return self
+        if status not in (STATUS_SUCCESS, STATUS_FAILED):
+            self._error = ValueError(
+                f'sub-step status must be either "{STATUS_SUCCESS}" or "{STATUS_FAILED}"'
+            )
+            return self
+
+        self._sub_steps.append(
+            SubStepData(
+                name=name,
+                status=status,
+                payload=data,
+            )
+        )
+        return self
+
+    # --- Status methods ---
+
+    async def stop(
+        self, status: str = STATUS_SUCCESS, message_or_data: str | dict | None = None
+    ) -> StepResult:
+        """Stop the step with an explicit status and optional message/data.
+
+        This is the generic status method; prefer :meth:`success`,
+        :meth:`failed`, or :meth:`error` for clarity.
+        """
+        return await self._stop(status, message_or_data)
+
+    async def success(self, message_or_data: str | dict | None = None) -> StepResult:
+        """Mark the step as successful and send it."""
+        return await self._stop(STATUS_SUCCESS, message_or_data)
+
+    async def failed(self, message_or_data: str | dict | None = None) -> StepResult:
+        """Mark the step as failed and send it."""
+        return await self._stop(STATUS_FAILED, message_or_data)
+
+    async def error(self, message_or_data: str | dict | None = None) -> StepResult:
+        """Mark the step as error and send it."""
+        return await self._stop(STATUS_ERROR, message_or_data)
+
+    async def _stop(self, status: str, message_or_data: str | dict | None = None) -> StepResult:
+        """Finalise the step and send the event."""
+        if self._error is not None:
+            raise self._error
+
+        self._event[FIELD_FINISHED_AT] = now_iso()
+        self._event[FIELD_STATUS] = status
+        self._event[FIELD_CONTEXT] = self._context
+        self._event[FIELD_REFS] = self._refs
+
+        # Handle optional message/data.
+        if message_or_data is not None:
+            if self._metadata is None:
+                self._metadata = {}
+            if isinstance(message_or_data, str) and message_or_data:
+                self._metadata[FIELD_MESSAGE] = message_or_data
+            elif isinstance(message_or_data, dict) and message_or_data:
+                self._metadata.update(message_or_data)
+
+        if self._metadata:
+            self._event[FIELD_THREADIFY_METADATA] = self._metadata
+
+        # Attach sub-steps.
+        if self._sub_steps:
+            self._event[FIELD_SUB_STEPS] = [
+                {
+                    "name": ss.name,
+                    "status": ss.status,
+                    "payload": ss.payload,
+                    "recordedAt": ss.recorded_at,
+                }
+                for ss in self._sub_steps
+            ]
+
+        # Generate idempotency key.
+        self._event[FIELD_IDEMPOTENCY_KEY] = self._generate_idempotency_key()
+
+        # Send event.
+        try:
+            await self._send_event()
+        except DuplicateStepError:
+            return StepResult(
+                step_name=self._step_name,
+                thread_id=self._thread.thread_id,
+                status=status,
+                idempotency_key=self._event.get(FIELD_IDEMPOTENCY_KEY, ""),
+                timestamp=first_non_empty(
+                    self._event.get(FIELD_FINISHED_AT, ""),
+                    self._event.get(FIELD_STARTED_AT, ""),
+                ),
+                duplicate=True,
+            )
+
+        return StepResult(
+            step_name=self._step_name,
+            thread_id=self._thread.thread_id,
+            status=status,
+            idempotency_key=self._event.get(FIELD_IDEMPOTENCY_KEY, ""),
+            timestamp=first_non_empty(
+                self._event.get(FIELD_FINISHED_AT, ""),
+                self._event.get(FIELD_STARTED_AT, ""),
+            ),
+        )
+
+    async def _send_event(self) -> dict[str, Any]:
+        """Transmit the event and wait for a response."""
+        if not self._thread.thread_id:
+            raise RuntimeError("Thread not started")
+
+        await self._thread._send(self._event)
+
+        resp = await self._thread._conn._wait_response(
+            lambda m: m.get(FIELD_ACTION) == ACTION_RECORD_THREAD_EVENT
+        )
+
+        if resp.get(FIELD_STATUS) != STATUS_SUCCESS:
+            msg = resp.get(FIELD_MESSAGE, "failed to record step event")
+            if resp.get(FIELD_IS_DUPLICATE):
+                raise DuplicateStepError(msg)
+            raise RuntimeError(msg)
+
+        return resp
+
+    def _generate_idempotency_key(self) -> str:
+        """Generate an FNV-1a idempotency key from step name + context."""
+        if self._manual_idempotency_key:
+            return self._manual_idempotency_key
+
+        # Build sorted JSON string of context.
+        sorted_items = sorted(self._context.items())
+        context_json = "{" + ",".join(f'"{k}":"{v}"' for k, v in sorted_items) + "}"
+
+        input_str = self._step_name + context_json
+        h = _fnv1a_32(input_str.encode("utf-8"))
+        return f"{h:08x}"
+
+    # --- Read-only accessors ---
+
+    @property
+    def step_name(self) -> str:
+        return self._step_name
+
+    @property
+    def status(self) -> str:
+        return self._event.get(FIELD_STATUS, STATUS_IN_PROGRESS)
+
+    @property
+    def context(self) -> dict[str, str]:
+        return dict(self._context)
+
+    @property
+    def metadata(self) -> dict[str, Any] | None:
+        """Return the current metadata dict (or None if unset)."""
+        return dict(self._metadata) if self._metadata is not None else None
+
+    def get_event_data(self) -> dict[str, Any]:
+        """Return a copy of the current event data (for debugging)."""
+        return dict(self._event)
+
+
+class DuplicateStepError(Exception):
+    """Raised when a duplicate step is detected."""
+
+    pass
+
+
+def is_duplicate_error(error: Exception) -> bool:
+    return isinstance(error, DuplicateStepError)
+
+
+def _fnv1a_32(data: bytes) -> int:
+    """FNV-1a 32-bit hash — matches the JS SDK implementation."""
+    h = 0x811C9DC5
+    for byte in data:
+        h ^= byte
+        h = (h * 0x01000193) & 0xFFFFFFFF
+    return h