feat: initial release of temporal-parseable python plugin v0.1.0

Author: praveen5959

.github/workflows/ci.yaml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/temporal_parseable
+
+      - name: Test
+        run: pytest --tb=short -q
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Distribution
+dist/
+*.tar.gz

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `temporal-parseable` are documented here.
+
+## [0.1.0] - 2026-06-03
+
+### Added
+- `ParseablePlugin` — drop-in Temporal plugin wiring logs and traces to Parseable
+- `ParseableConfig` — dataclass config with full `PARSEABLE_*` env-var support
+- `ParseableActivityInterceptor` — emits `started / completed / failed` records per activity execution, including `attempt` and `duration_ms`
+- `ParseableWorkflowInboundInterceptor` — emits records for `execute_workflow`, `handle_signal`, `handle_query`, `handle_update`
+- `ParseableWorkflowOutboundInterceptor` — emits records for `start_child_workflow`, `signal_external_workflow`, `signal_child_workflow`, `continue_as_new`
+- `workflow_event()` — replay-safe helper for emitting custom domain events from workflow code
+- `SanitizingSpanExporter` — flattens non-primitive OTel span attributes to prevent Parseable `400` rejections
+- Correct `X-P-Log-Source` headers: `otel-logs` for logs pipeline, `otel-traces` for traces pipeline
+- Sandbox passthrough support — `temporal_parseable` marked as passthrough so the Temporal workflow sandbox does not attempt to import OTel/requests inside the isolate
+- Full `pyproject.toml` with hatchling build backend, pinned OTel 1.x deps, and `dev` extras
+- `examples/` with `worker.py`, `client.py`, `workflows.py` covering all interceptor paths
+- `tests/` with `test_config.py`, `test_sanitizing_exporter.py`, `test_interceptors.py`
+- `.github/workflows/ci.yml` — pytest on push/PR, auto-publish to PyPI on `v*` tag

README.md

@@ -0,0 +1,148 @@
+# temporal-parseable
+
+Temporal plugin that ships workflow and activity execution events to [Parseable](https://parseable.com) as OpenTelemetry structured logs and traces.
+
+```
+┌──────────────┐    OTLP/HTTP     ┌──────────────┐
+│   Temporal   │ ──────────────── │   Parseable  │
+│   Worker     │  logs + traces   │              │
+│  + Plugin    │                  │  temporal-*  │
+└──────────────┘                  └──────────────┘
+```
+
+Two streams in Parseable:
+
+- **`temporal-logs`** — flat queryable records: workflow/activity start, complete, fail, retry, duration, signals, queries, updates, child workflows, continue-as-new, and custom domain events
+- **`temporal-traces`** — OTel waterfall traces across workflow and activity boundaries
+
+## Installation
+
+```bash
+pip install temporal-parseable
+```
+
+## Quick start
+
+```python
+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)
+
+client = await Client.connect("localhost:7233", plugins=[plugin])
+
+async with Worker(
+    client,
+    task_queue="my-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    plugins=[plugin],
+):
+    await asyncio.Event().wait()
+```
+
+## Configuration
+
+All settings fall back to environment variables with the `PARSEABLE_` prefix:
+
+| 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` |
+| `logs.stream` | `PARSEABLE_LOGS_STREAM` | `temporal-logs` |
+| `traces.stream` | `PARSEABLE_TRACES_STREAM` | `temporal-traces` |
+
+Pass `logs=None` or `traces=None` to disable either pipeline.
+
+## Custom domain events
+
+Emit replay-safe domain events from inside workflow code:
+
+```python
+from temporal_parseable.workflow import workflow_event
+
+@workflow.defn
+class AgentWorkflow:
+    @workflow.run
+    async def run(self, input: AgentInput) -> AgentResult:
+        workflow_event("agent.started", {"user_id": input.user_id})
+
+        plan = await workflow.execute_activity(plan_activity, input)
+        workflow_event("agent.plan.chosen", {"steps": len(plan.steps)})
+
+        for step in plan.steps:
+            workflow_event("agent.step.start", {"tool": step.tool})
+            await workflow.execute_activity(run_step, step)
+
+        return result
+```
+
+Each call emits a record with `type: "user_event"`, `event_name`, and `event_data`. Records are replay-safe — never duplicated during Temporal history replay.
+
+## Log schema
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | `activity` \| `workflow` \| `user_event` \| `signal` \| `query` \| `update` \| `child_workflow` \| `continue_as_new` | discriminator |
+| `status` | `started` \| `completed` \| `failed` | not on `user_event` |
+| `service_name` | string | from plugin config |
+| `timestamp` | ISO 8601 | event time |
+| `workflow_id` | string | |
+| `run_id` | string | |
+| `workflow_name` | string | |
+| `activity_name` | string | activity records only |
+| `activity_id` | string | activity records only |
+| `attempt` | int | activity records only (1-based) |
+| `duration_ms` | float | on completion/fail |
+| `error` | string | on fail |
+| `direction` | `inbound` \| `outbound` | message records |
+| `message_name` | string | signal/query/update name |
+| `target_workflow_id` | string | outbound signals/child workflows |
+| `event_name` | string | user events only |
+| `event_data` | object | user events only |
+
+## Replay safety
+
+All workflow-side emission is replay-safe. The plugin guards every emit with `workflow.unsafe.is_replaying()`, so records are never duplicated when Temporal replays workflow history (worker crash, cache eviction, manual replay).
+
+## Example queries in Parseable
+
+```sql
+-- Recent workflow failures
+SELECT workflow_id, workflow_name, error, p_timestamp
+FROM "temporal-logs"
+WHERE type = 'workflow' AND status = 'failed'
+ORDER BY p_timestamp DESC LIMIT 20;
+
+-- Activity retry hotspots
+SELECT activity_name, COUNT(*) as failures
+FROM "temporal-logs"
+WHERE type = 'activity' AND status = 'failed'
+GROUP BY activity_name ORDER BY failures DESC;
+
+-- P95 activity duration
+SELECT activity_name, PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY duration_ms) as p95_ms
+FROM "temporal-logs"
+WHERE type = 'activity' AND status = 'completed'
+GROUP BY activity_name;
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+Apache-2.0

examples/client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+import os
+import uuid
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from temporalio.client import Client
+from workflows import (
+    ExampleWorkflow, FailingWorkflow, UserEventWorkflow, ParentWorkflow
+)
+
+TASK_QUEUE = "temporal-parseable-demo"
+
+def uid(name: str) -> str:
+    return f"{name}-{uuid.uuid4().hex[:8]}"
+
+
+async def main() -> None:
+    client = await Client.connect("localhost:7233")
+
+    print("→ Running happy-path workflow...")
+    result = await client.execute_workflow(
+        ExampleWorkflow.run, "World",
+        id=uid("example"), task_queue=TASK_QUEUE,
+    )
+    print(f"  Result: {result}")
+
+    print("→ Running user-event workflow...")
+    result = await client.execute_workflow(
+        UserEventWorkflow.run, "Alice",
+        id=uid("user-event"), task_queue=TASK_QUEUE,
+    )
+    print(f"  Result: {result}")
+
+    print("→ Running parent/child workflow...")
+    result = await client.execute_workflow(
+        ParentWorkflow.run, "Bob",
+        id=uid("parent"), task_queue=TASK_QUEUE,
+    )
+    print(f"  Result: {result}")
+
+    print("→ Running failing workflow (will fail after retries)...")
+    try:
+        await client.execute_workflow(
+            FailingWorkflow.run,
+            id=uid("failing"), task_queue=TASK_QUEUE,
+        )
+    except Exception as e:
+        print(f"  Expected failure: {e}")
+
+    print("\nDone. Check Parseable for records in temporal-logs.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())