temporal-parseable 0.1.0__py3-none-any.whl

temporal_parseable/__init__.py

@@ -0,0 +1,162 @@
+"""
+temporal-parseable
+==================
+
+Temporal plugin that ships workflow and activity execution events to Parseable
+as OpenTelemetry structured logs and traces.
+
+Quick start — same pattern as any Temporal plugin::
+
+    from temporalio.client import Client
+    from temporalio.worker import Worker
+    from temporal_parseable import ParseablePlugin, ParseableConfig
+
+    config = ParseableConfig(
+        service_name="my-worker",
+        endpoint="https://parseable.example.com",
+        username="admin",
+        password="secret",
+    )
+    plugin = ParseablePlugin(config)
+
+    # Add to client for span context propagation (links client → workflow traces)
+    client = await Client.connect("localhost:7233", plugins=[plugin])
+
+    # Add to worker for activity + workflow interception
+    # No SandboxedWorkflowRunner needed — the plugin handles it automatically
+    async with Worker(
+        client,
+        task_queue="my-queue",
+        workflows=[MyWorkflow],
+        activities=[my_activity],
+        plugins=[plugin],
+    ):
+        await asyncio.Event().wait()
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Type
+
+from temporalio.plugin import SimplePlugin
+from temporalio.worker import Interceptor, WorkflowInterceptorClassInput
+from temporalio.worker.workflow_sandbox import SandboxedWorkflowRunner, SandboxRestrictions
+
+from .config import ParseableConfig, LogsConfig, TracesConfig
+from .exporters import build_tracer_provider, build_logger_provider
+from ._emitter import ParseableEmitter
+from .activity_interceptor import ParseableActivityInterceptor
+from .workflow_interceptor import (
+    ParseableWorkflowInboundInterceptor,
+    ParseableWorkflowOutboundInterceptor,
+)
+from . import workflow as _workflow_module
+from ._version import PLUGIN_VERSION
+
+__version__ = PLUGIN_VERSION
+__all__ = [
+    "ParseablePlugin",
+    "ParseableConfig",
+    "LogsConfig",
+    "TracesConfig",
+    "PLUGIN_VERSION",
+]
+
+
+def _build_sandbox() -> SandboxedWorkflowRunner:
+    """
+    Build a SandboxedWorkflowRunner with temporal_parseable marked as passthrough.
+
+    Without this, the Temporal workflow sandbox tries to import OTel/requests
+    inside the isolate and raises RestrictedWorkflowAccessError. Injecting the
+    runner via SimplePlugin means users never need to configure this themselves.
+    """
+    return SandboxedWorkflowRunner(
+        restrictions=SandboxRestrictions.default.with_passthrough_modules(
+            "temporal_parseable"
+        )
+    )
+
+
+class ParseablePlugin(SimplePlugin):
+    """
+    Temporal plugin that ships workflow and activity events to Parseable.
+
+    Pass a single instance to both Client.connect and Worker — the plugin
+    is safe to reuse across both::
+
+        plugin = ParseablePlugin(ParseableConfig())
+
+        client = await Client.connect("localhost:7233", plugins=[plugin])
+
+        async with Worker(client, task_queue="q", workflows=[W], plugins=[plugin]):
+            ...
+
+    The plugin automatically:
+    - Configures the workflow sandbox passthrough (no SandboxedWorkflowRunner needed)
+    - Wires activity and workflow interceptors
+    - Sets up OTel log and trace pipelines to Parseable
+    """
+
+    def __init__(self, config: Optional[ParseableConfig] = None) -> None:
+        self._config = config or ParseableConfig()
+
+        # Build OTel providers
+        self._tracer_provider = build_tracer_provider(self._config)
+        self._logger_provider = build_logger_provider(self._config)
+
+        # Shared emitter used by all interceptors
+        self._emitter = ParseableEmitter(
+            logger_provider=self._logger_provider,
+            service_name=self._config.service_name,
+        )
+
+        # Make the emitter available to workflow_event()
+        _workflow_module._set_emitter(self._emitter)
+
+        worker_interceptor = _ParseableWorkerInterceptor(self._emitter)
+
+        super().__init__(
+            name="parseable.temporal",
+            interceptors=[worker_interceptor],
+            # Inject sandbox passthrough automatically — users don't need to
+            # configure SandboxedWorkflowRunner manually.
+            workflow_runner=_build_sandbox(),
+        )
+
+    @property
+    def config(self) -> ParseableConfig:
+        return self._config
+
+    def shutdown(self) -> None:
+        """Flush and shut down OTel providers. Call on clean worker exit."""
+        if self._tracer_provider:
+            self._tracer_provider.shutdown()
+        if self._logger_provider:
+            self._logger_provider.shutdown()
+
+
+class _ParseableWorkerInterceptor(Interceptor):
+    """
+    Worker-level interceptor that wires activity and workflow interceptors.
+    One instance lives on the worker per plugin instance.
+    """
+
+    def __init__(self, emitter: ParseableEmitter) -> None:
+        self._emitter = emitter
+
+    def intercept_activity(self, next):  # type: ignore[override]
+        return ParseableActivityInterceptor(next, self._emitter)
+
+    def workflow_interceptor_class(
+        self, input: WorkflowInterceptorClassInput
+    ) -> Type[ParseableWorkflowInboundInterceptor]:
+        emitter = self._emitter
+
+        class _Injected(ParseableWorkflowInboundInterceptor):
+            # emitter is set in init() AFTER _outbound is created, not in __init__
+            def init(self, outbound):  # type: ignore[override]
+                super().init(outbound)
+                self._set_emitter(emitter)
+
+        return _Injected

temporal_parseable/_emitter.py

@@ -0,0 +1,83 @@
+"""
+Internal log record emitter.
+
+All interceptors share a single ParseableEmitter instance (held on the
+ParseablePlugin) which serialises ParseableEventRecord dicts and forwards
+them to the OTel LoggerProvider.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry._logs.severity import SeverityNumber
+
+from .types import ParseableEventRecord
+from ._version import PLUGIN_VERSION
+
+
+class ParseableEmitter:
+    """
+    Thread-safe (asyncio-safe) emitter for structured Parseable log records.
+
+    Usage::
+
+        emitter = ParseableEmitter(logger_provider, service_name="my-worker")
+        emitter.emit({"type": "workflow", "status": "started", ...})
+    """
+
+    def __init__(
+        self,
+        logger_provider: Optional[LoggerProvider],
+        service_name: str,
+    ) -> None:
+        self._service_name = service_name
+        self._plugin_version = PLUGIN_VERSION
+        if logger_provider is not None:
+            self._logger = logger_provider.get_logger(
+                "temporal_parseable",
+                schema_url="https://parseable.com/temporal/schema/v1",
+            )
+        else:
+            self._logger = None
+
+    def emit(self, record: ParseableEventRecord) -> None:
+        """
+        Emit a single record to Parseable.
+
+        Adds service_name, timestamp, and plugin_version if not already
+        present, then serialises to JSON and sends via the OTel logger.
+        Silently no-ops when logs are disabled (logger is None).
+        """
+        if self._logger is None:
+            return
+
+        record.setdefault("service_name", self._service_name)  # type: ignore[misc]
+        record.setdefault("timestamp", _now_iso())             # type: ignore[misc]
+        record.setdefault("plugin_version", self._plugin_version)  # type: ignore[misc]
+
+        body = json.dumps(record, default=str)
+
+        self._logger.emit(
+            timestamp=_now_ns(),
+            observed_timestamp=_now_ns(),
+            severity_number=SeverityNumber.INFO,
+            severity_text="INFO",
+            body=body,
+            attributes={"parseable.stream": "temporal-logs"},
+        )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _now_ns() -> int:
+    """Current time as nanoseconds since epoch (required by OTel APIs)."""
+    return time.time_ns()

temporal_parseable/_version.py

@@ -0,0 +1 @@
+PLUGIN_VERSION = "0.1.0"

temporal_parseable/activity_interceptor.py

@@ -0,0 +1,91 @@
+"""
+Activity interceptor.
+
+Wraps every activity execution and emits three possible records to Parseable:
+
+  started   — before the activity function runs
+  completed — after successful return
+  failed    — after an exception (including ApplicationError retries)
+
+Fields captured on every record:
+
+  type          = "activity"
+  activity_name — activity function name
+  activity_id   — unique ID assigned by Temporal
+  attempt       — 1-based retry attempt number
+  workflow_id   — parent workflow
+  run_id        — parent run
+  workflow_name — parent workflow type name
+  duration_ms   — wall-clock ms from started to completed/failed
+  error         — stringified exception on failed records
+
+Mirrors the TypeScript activity-interceptor.ts.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from temporalio import activity
+from temporalio.worker import ActivityInboundInterceptor, ExecuteActivityInput
+
+from ._emitter import ParseableEmitter, _now_iso
+
+
+class ParseableActivityInterceptor(ActivityInboundInterceptor):
+    """
+    Inbound activity interceptor that emits structured records to Parseable.
+
+    One instance is created per activity execution by
+    ``ParseableWorkerInterceptor.intercept_activity``.
+    """
+
+    def __init__(
+        self,
+        next: ActivityInboundInterceptor,
+        emitter: ParseableEmitter,
+    ) -> None:
+        super().__init__(next)
+        self._emitter = emitter
+
+    async def execute_activity(self, input: ExecuteActivityInput) -> Any:
+        info = activity.info()
+
+        base = {
+            "type": "activity",
+            "activity_name": info.activity_type,
+            "activity_id": info.activity_id,
+            "attempt": info.attempt,
+            "workflow_id": info.workflow_id,
+            "run_id": info.workflow_run_id,
+            "workflow_name": info.workflow_type,
+        }
+
+        # ── started ──────────────────────────────────────────────────────────
+        self._emitter.emit({**base, "status": "started", "timestamp": _now_iso()})  # type: ignore[arg-type]
+
+        start_ns = time.monotonic_ns()
+        try:
+            result = await self.next.execute_activity(input)
+        except Exception as exc:
+            duration_ms = (time.monotonic_ns() - start_ns) / 1_000_000
+            # ── failed ───────────────────────────────────────────────────────
+            self._emitter.emit({  # type: ignore[arg-type]
+                **base,
+                "status": "failed",
+                "timestamp": _now_iso(),
+                "duration_ms": round(duration_ms, 3),
+                "error": str(exc),
+            })
+            raise
+
+        duration_ms = (time.monotonic_ns() - start_ns) / 1_000_000
+        # ── completed ────────────────────────────────────────────────────────
+        self._emitter.emit({  # type: ignore[arg-type]
+            **base,
+            "status": "completed",
+            "timestamp": _now_iso(),
+            "duration_ms": round(duration_ms, 3),
+        })
+        return result

temporal_parseable/config.py

@@ -0,0 +1,116 @@
+"""
+Configuration for the Parseable Temporal plugin.
+
+All settings are readable from environment variables with the PARSEABLE_
+prefix, matching the TypeScript plugin's env-var convention.  Values passed
+directly to ParseableConfig take precedence over environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+def _env(key: str, default: str) -> str:
+    return os.environ.get(key, default)
+
+
+@dataclass
+class LogsConfig:
+    """Configuration for the structured-log pipeline."""
+
+    #: Parseable stream name for log records.
+    stream: str = field(default_factory=lambda: _env("PARSEABLE_LOGS_STREAM", "temporal-logs"))
+    enabled: bool = field(
+        default_factory=lambda: _env("PARSEABLE_ENABLE_LOGS", "true").lower() != "false"
+    )
+
+
+@dataclass
+class TracesConfig:
+    """Configuration for the OTel trace pipeline."""
+
+    #: Parseable stream name for trace spans.
+    stream: str = field(
+        default_factory=lambda: _env("PARSEABLE_TRACES_STREAM", "temporal-traces")
+    )
+    enabled: bool = field(
+        default_factory=lambda: _env("PARSEABLE_ENABLE_TRACES", "true").lower() != "false"
+    )
+
+
+@dataclass
+class ParseableConfig:
+    """
+    Full configuration for ParseablePlugin.
+
+    Usage::
+
+        config = ParseableConfig(
+            service_name="my-worker",
+            endpoint="https://parseable.example.com",
+            username="admin",
+            password="secret",
+        )
+
+    All arguments fall back to environment variables when omitted:
+
+    =====================  ===========================  =======================
+    Argument               Environment variable         Default
+    =====================  ===========================  =======================
+    endpoint               PARSEABLE_URL                http://localhost:8000
+    username               PARSEABLE_USERNAME           admin
+    password               PARSEABLE_PASSWORD           admin
+    service_name           PARSEABLE_SERVICE_NAME       temporal-worker
+    =====================  ===========================  =======================
+    """
+
+    #: Parseable base URL, e.g. ``http://parseable.example:8000``.
+    #: Logs are POSTed to ``{endpoint}/v1/logs``,
+    #: traces to ``{endpoint}/v1/traces``.
+    endpoint: str = field(
+        default_factory=lambda: _env("PARSEABLE_URL", "http://localhost:8000")
+    )
+
+    #: HTTP Basic auth username.
+    username: str = field(
+        default_factory=lambda: _env("PARSEABLE_USERNAME", "admin")
+    )
+
+    #: HTTP Basic auth password.
+    password: str = field(
+        default_factory=lambda: _env("PARSEABLE_PASSWORD", "admin")
+    )
+
+    #: Becomes the ``service.name`` OTel resource attribute and the
+    #: ``service_name`` field in every log record.
+    service_name: str = field(
+        default_factory=lambda: _env("PARSEABLE_SERVICE_NAME", "temporal-worker")
+    )
+
+    #: Structured-log pipeline config.  Pass ``logs=None`` to disable logs.
+    logs: Optional[LogsConfig] = field(default_factory=LogsConfig)
+
+    #: OTel trace pipeline config.  Pass ``traces=None`` to disable traces.
+    traces: Optional[TracesConfig] = field(default_factory=TracesConfig)
+
+    # ── Derived helpers ──────────────────────────────────────────────────────
+
+    @property
+    def logs_endpoint(self) -> str:
+        """Full OTLP/HTTP logs endpoint."""
+        return f"{self.endpoint.rstrip('/')}/v1/logs"
+
+    @property
+    def traces_endpoint(self) -> str:
+        """Full OTLP/HTTP traces endpoint."""
+        return f"{self.endpoint.rstrip('/')}/v1/traces"
+
+    @property
+    def auth_header(self) -> str:
+        """Base64-encoded HTTP Basic auth header value."""
+        import base64
+        token = base64.b64encode(f"{self.username}:{self.password}".encode()).decode()
+        return f"Basic {token}"

temporal_parseable/exporters.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from typing import Any, Dict, Optional, Sequence
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+
+from .config import ParseableConfig
+from ._version import PLUGIN_VERSION
+
+logger = logging.getLogger(__name__)
+
+_Primitive = (str, int, float, bool)
+
+
+def _sanitize_value(v: Any) -> Any:
+    if v is None:
+        return None
+    if isinstance(v, _Primitive):
+        return v
+    if isinstance(v, datetime):
+        return v.isoformat()
+    if isinstance(v, (list, tuple)):
+        sanitised = [_sanitize_value(item) for item in v]
+        cleaned = [item for item in sanitised if item is not None]
+        if all(isinstance(item, _Primitive) for item in cleaned):
+            return cleaned
+        return json.dumps(cleaned)
+    if isinstance(v, dict):
+        return json.dumps(v, default=str)
+    return str(v)
+
+
+def _sanitize_span(span: ReadableSpan) -> ReadableSpan:
+    if not span.attributes:
+        return span
+    clean: Dict[str, Any] = {}
+    for key, value in span.attributes.items():
+        sanitised = _sanitize_value(value)
+        if sanitised is not None:
+            clean[key] = sanitised
+    try:
+        object.__setattr__(span, "_attributes", clean)
+    except (AttributeError, TypeError):
+        pass
+    return span
+
+
+class SanitizingSpanExporter(SpanExporter):
+    def __init__(self, delegate: SpanExporter) -> None:
+        self._delegate = delegate
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        sanitised = [_sanitize_span(span) for span in spans]
+        return self._delegate.export(sanitised)
+
+    def shutdown(self) -> None:
+        self._delegate.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return self._delegate.force_flush(timeout_millis)
+
+
+def _resource(config: ParseableConfig) -> Resource:
+    return Resource.create({
+        SERVICE_NAME: config.service_name,
+        "parseable.plugin.version": PLUGIN_VERSION,
+    })
+
+
+def build_tracer_provider(config: ParseableConfig) -> Optional[TracerProvider]:
+    if config.traces is None or not config.traces.enabled:
+        return None
+
+    endpoint = config.traces_endpoint
+    stream = config.traces.stream
+    logger.info("Parseable traces endpoint: %s (stream=%s)", endpoint, stream)
+
+    otlp_exporter = OTLPSpanExporter(
+        endpoint=endpoint,
+        headers={
+            "Authorization": config.auth_header,
+            "X-P-Stream": stream,
+            "X-P-Log-Source": "otel-traces",  # tells Parseable this is OTLP traces
+        },
+    )
+    sanitizing_exporter = SanitizingSpanExporter(otlp_exporter)
+    provider = TracerProvider(resource=_resource(config))
+    provider.add_span_processor(BatchSpanProcessor(sanitizing_exporter))
+    return provider
+
+
+def build_logger_provider(config: ParseableConfig) -> Optional[LoggerProvider]:
+    if config.logs is None or not config.logs.enabled:
+        return None
+
+    endpoint = config.logs_endpoint
+    stream = config.logs.stream
+    logger.info("Parseable logs endpoint: %s (stream=%s)", endpoint, stream)
+
+    otlp_log_exporter = OTLPLogExporter(
+        endpoint=endpoint,
+        headers={
+            "Authorization": config.auth_header,
+            "X-P-Stream": stream,
+            "X-P-Log-Source": "otel-logs",   # tells Parseable this is OTLP logs
+        },
+    )
+    provider = LoggerProvider(resource=_resource(config))
+    provider.add_log_record_processor(BatchLogRecordProcessor(otlp_log_exporter))
+    return provider

temporal_parseable/types.py

@@ -0,0 +1,70 @@
+"""
+Parseable event record schema.
+
+Mirrors the TypeScript ParseableEventRecord type from types.ts exactly.
+Every field that can appear in a log line sent to the temporal-logs stream
+is declared here. Optional fields are absent from the dict when not set —
+callers use TypedDict with total=False sections for optional keys.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+from typing_extensions import TypedDict, Required
+
+
+EventType = Literal[
+    "activity",
+    "workflow",
+    "user_event",
+    "signal",
+    "query",
+    "update",
+    "child_workflow",
+    "continue_as_new",
+]
+
+EventStatus = Literal["started", "completed", "failed"]
+EventDirection = Literal["inbound", "outbound"]
+
+
+class ParseableEventRecord(TypedDict, total=False):
+    """
+    Flat log record emitted to the Parseable temporal-logs stream.
+
+    Required fields are always present. Optional fields are included only when
+    relevant to the event type (e.g. activity_name is set for activity records,
+    event_name for user_event records, etc.).
+    """
+
+    # ── Required on every record ────────────────────────────────────────────
+    type: Required[EventType]
+    service_name: Required[str]
+    timestamp: Required[str]           # ISO 8601
+    workflow_id: Required[str]
+    run_id: Required[str]
+    workflow_name: Required[str]
+
+    # ── Present on all records except user_event ────────────────────────────
+    status: EventStatus
+
+    # ── Activity records only ───────────────────────────────────────────────
+    activity_name: str
+    activity_id: str
+    attempt: int                       # 1-based
+
+    # ── Completion / failure fields ─────────────────────────────────────────
+    duration_ms: float
+    error: str                         # failure message
+
+    # ── Message records (signal/query/update/child_workflow/continue_as_new) ─
+    direction: EventDirection
+    message_name: str                  # signal/query/update name or child type
+    target_workflow_id: str            # outbound signals/child workflows
+
+    # ── User-event records only ─────────────────────────────────────────────
+    event_name: str
+    event_data: Any                    # arbitrary JSON-serialisable payload
+
+    # ── Plugin metadata ─────────────────────────────────────────────────────
+    plugin_version: str