edda-framework 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

edda/app.py

@@ -238,7 +238,9 @@ class EddaApp:
         Register a default CloudEvent handler for a workflow.
 
         The default handler extracts the CloudEvent data and passes it
-        as kwargs to workflow.start().
+        as kwargs to workflow.start(). If the CloudEvent contains
+        traceparent/tracestate extension attributes (for distributed tracing),
+        they are automatically injected into _trace_context.
 
         Args:
             event_type: CloudEvent type (same as workflow name)
@@ -250,11 +252,24 @@ class EddaApp:
             # Extract data from CloudEvent
             data = event.get_data()
 
+            # Extract trace context from CloudEvent extension attributes
+            # (W3C Trace Context: traceparent, tracestate)
+            trace_context: dict[str, str] = {}
+            attrs = event.get_attributes()
+            if "traceparent" in attrs:
+                trace_context["traceparent"] = str(attrs["traceparent"])
+            if "tracestate" in attrs:
+                trace_context["tracestate"] = str(attrs["tracestate"])
+
             # Start workflow with data as kwargs
             if isinstance(data, dict):
+                # Inject trace context if present
+                if trace_context:
+                    data = {**data, "_trace_context": trace_context}
                 await wf.start(**data)
             else:
                 # If data is not a dict, start without arguments
+                # (trace context cannot be injected)
                 await wf.start()
 
         # Register the handler

edda/hooks.py

@@ -12,8 +12,8 @@ Example:
     ...     async def on_workflow_start(self, instance_id, workflow_name, input_data):
     ...         print(f"Workflow {workflow_name} started: {instance_id}")
     ...
-    ...     async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
-    ...         print(f"Activity {activity_name} completed (cache_hit={cache_hit})")
+    ...     async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
+    ...         print(f"Activity {activity_name} ({activity_id}) completed (cache_hit={cache_hit})")
     >>>
     >>> app = EddaApp(service_name="my-service", db_url="...", hooks=MyHooks())
 """
@@ -86,7 +86,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -95,7 +95,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             is_replaying: True if this is a replay (cached result)
         """
@@ -104,7 +104,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -114,7 +114,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             result: Return value from the activity
             cache_hit: True if result was retrieved from cache (replay)
@@ -124,7 +124,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None:
@@ -133,7 +133,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             error: Exception that caused the failure
         """
@@ -231,7 +231,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -240,7 +240,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -250,7 +250,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None:

edda/integrations/opentelemetry/__init__.py

@@ -0,0 +1,39 @@
+"""
+Edda OpenTelemetry Integration.
+
+Provides OpenTelemetry tracing and optional metrics for Edda workflows.
+
+Example:
+    ```python
+    from edda import EddaApp
+    from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+    hooks = OpenTelemetryHooks(
+        service_name="order-service",
+        otlp_endpoint="http://localhost:4317",  # Optional
+        enable_metrics=True,  # Optional
+    )
+
+    app = EddaApp(
+        service_name="order-service",
+        db_url="sqlite:///workflow.db",
+        hooks=hooks,
+    )
+    ```
+
+Installation:
+    ```bash
+    pip install edda-framework[opentelemetry]
+
+    # Or using uv
+    uv add edda-framework --extra opentelemetry
+    ```
+"""
+
+from edda.integrations.opentelemetry.hooks import (
+    OpenTelemetryHooks,
+    extract_trace_context,
+    inject_trace_context,
+)
+
+__all__ = ["OpenTelemetryHooks", "inject_trace_context", "extract_trace_context"]

edda/integrations/opentelemetry/hooks.py

@@ -0,0 +1,579 @@
+"""
+OpenTelemetry hooks implementation for Edda workflows.
+
+This module provides the OpenTelemetryHooks class that integrates OpenTelemetry
+tracing and optional metrics with Edda's workflow execution.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+from edda.hooks import HooksBase
+
+if TYPE_CHECKING:
+    from opentelemetry.context import Context
+    from opentelemetry.trace import Span, Tracer
+
+# Check if OpenTelemetry is available
+try:
+    from opentelemetry import trace
+    from opentelemetry.context import Context
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+    from opentelemetry.trace import Span, Status, StatusCode, Tracer
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+    _OPENTELEMETRY_AVAILABLE = True
+except ImportError:
+    _OPENTELEMETRY_AVAILABLE = False
+
+
+class OpenTelemetryHooks(HooksBase):
+    """
+    OpenTelemetry tracing and metrics integration for Edda workflows.
+
+    Creates distributed traces with:
+    - Workflow spans as parent spans
+    - Activity spans as child spans
+    - Error recording and status propagation
+    - Retry event tracking
+    - Optional metrics (counters, histograms)
+
+    Span Hierarchy::
+
+        workflow:order_workflow (parent)
+        ├── activity:reserve_inventory (child)
+        │   └── [event: retry] (if retry occurs)
+        ├── activity:process_payment (child)
+        └── activity:ship_order (child)
+            └── [event: event_received] (if wait_event used)
+
+    Example::
+
+        from edda import EddaApp
+        from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+        hooks = OpenTelemetryHooks(
+            service_name="order-service",
+            otlp_endpoint="http://localhost:4317",  # Optional
+            enable_metrics=True,  # Optional
+        )
+
+        app = EddaApp(
+            service_name="order-service",
+            db_url="sqlite:///workflow.db",
+            hooks=hooks,
+        )
+
+    Attributes:
+        service.name: Service name for resource identification
+        service.version: Service version (default: "1.0.0")
+        edda.framework: Always "true" to identify Edda workflows
+
+    Installation::
+
+        pip install edda-framework[opentelemetry]
+    """
+
+    def __init__(
+        self,
+        service_name: str = "edda",
+        otlp_endpoint: str | None = None,
+        enable_metrics: bool = False,
+    ) -> None:
+        """
+        Initialize OpenTelemetry hooks.
+
+        Args:
+            service_name: Service name for resource identification
+            otlp_endpoint: OTLP endpoint URL (e.g., "http://localhost:4317").
+                          If None, uses ConsoleSpanExporter for local development.
+            enable_metrics: Enable OpenTelemetry metrics (counters, histograms)
+
+        Raises:
+            ImportError: If OpenTelemetry packages are not installed
+        """
+        if not _OPENTELEMETRY_AVAILABLE:
+            raise ImportError(
+                "OpenTelemetry packages are not installed. "
+                "Install them with: pip install edda-framework[opentelemetry]"
+            )
+
+        self._tracer = self._setup_tracing(service_name, otlp_endpoint)
+        self._propagator = TraceContextTextMapPropagator()
+
+        # Span lifecycle management
+        self._workflow_spans: dict[str, Span] = {}
+        self._activity_spans: dict[str, Span] = {}
+        self._workflow_start_times: dict[str, float] = {}
+        self._activity_start_times: dict[str, float] = {}
+
+        # Optional metrics
+        self._enable_metrics = enable_metrics
+        if enable_metrics:
+            self._setup_metrics(service_name, otlp_endpoint)
+
+    def _setup_tracing(self, service_name: str, otlp_endpoint: str | None) -> Tracer:
+        """Configure OpenTelemetry tracing.
+
+        If a TracerProvider is already configured (e.g., by ASGI/WSGI middleware),
+        it will be reused instead of creating a new one. This enables trace context
+        propagation from external sources.
+        """
+        from opentelemetry.trace import NoOpTracerProvider
+
+        # Check if a TracerProvider is already configured
+        existing_provider = trace.get_tracer_provider()
+
+        # Only create new provider if none exists (NoOpTracerProvider is the default)
+        if isinstance(existing_provider, NoOpTracerProvider):
+            resource = Resource.create(
+                {
+                    "service.name": service_name,
+                    "service.version": "1.0.0",
+                    "edda.framework": "true",
+                }
+            )
+
+            provider = TracerProvider(resource=resource)
+
+            if otlp_endpoint:
+                # Production: OTLP exporter
+                try:
+                    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                        OTLPSpanExporter,
+                    )
+
+                    exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
+                    provider.add_span_processor(BatchSpanProcessor(exporter))
+                except ImportError:
+                    # Fallback to console if OTLP exporter not installed
+                    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+            else:
+                # Development: Console exporter
+                provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+            trace.set_tracer_provider(provider)
+
+        # Always get tracer from current provider (whether new or existing)
+        return trace.get_tracer("edda.opentelemetry", "1.0.0")
+
+    def _setup_metrics(self, service_name: str, otlp_endpoint: str | None) -> None:
+        """Configure OpenTelemetry metrics (optional)."""
+        try:
+            from opentelemetry import metrics
+            from opentelemetry.sdk.metrics import MeterProvider
+            from opentelemetry.sdk.metrics.export import (
+                ConsoleMetricExporter,
+                MetricExporter,
+                PeriodicExportingMetricReader,
+            )
+
+            exporter: MetricExporter
+            if otlp_endpoint:
+                try:
+                    from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+                        OTLPMetricExporter,
+                    )
+
+                    exporter = OTLPMetricExporter(endpoint=otlp_endpoint, insecure=True)
+                except ImportError:
+                    exporter = ConsoleMetricExporter()
+            else:
+                exporter = ConsoleMetricExporter()
+
+            reader = PeriodicExportingMetricReader(exporter, export_interval_millis=10000)
+            resource = Resource.create({"service.name": service_name})
+            provider = MeterProvider(resource=resource, metric_readers=[reader])
+            metrics.set_meter_provider(provider)
+
+            meter = metrics.get_meter("edda.opentelemetry", "1.0.0")
+
+            # Counters
+            self._workflow_started_counter = meter.create_counter(
+                "edda.workflow.started",
+                description="Number of workflows started",
+                unit="1",
+            )
+            self._workflow_completed_counter = meter.create_counter(
+                "edda.workflow.completed",
+                description="Number of workflows completed",
+                unit="1",
+            )
+            self._workflow_failed_counter = meter.create_counter(
+                "edda.workflow.failed",
+                description="Number of workflows failed",
+                unit="1",
+            )
+            self._activity_executed_counter = meter.create_counter(
+                "edda.activity.executed",
+                description="Number of activities executed (not cache hit)",
+                unit="1",
+            )
+            self._activity_cache_hit_counter = meter.create_counter(
+                "edda.activity.cache_hit",
+                description="Number of activity cache hits (replay)",
+                unit="1",
+            )
+
+            # Histograms
+            self._workflow_duration_histogram = meter.create_histogram(
+                "edda.workflow.duration",
+                description="Workflow execution duration",
+                unit="s",
+            )
+            self._activity_duration_histogram = meter.create_histogram(
+                "edda.activity.duration",
+                description="Activity execution duration",
+                unit="s",
+            )
+        except ImportError:
+            self._enable_metrics = False
+
+    # =========================================================================
+    # Workflow Hooks
+    # =========================================================================
+
+    async def on_workflow_start(
+        self, instance_id: str, workflow_name: str, input_data: dict[str, Any]
+    ) -> None:
+        """Start a workflow span (parent for all activities).
+
+        Trace context is inherited in the following priority:
+        1. Explicit _trace_context in input_data (e.g., from CloudEvents)
+        2. Current active span (e.g., from ASGI/WSGI middleware)
+        3. None (creates a new root span)
+        """
+        # Priority 1: Extract trace context from input_data (CloudEvents, manual)
+        parent_context = self._extract_trace_context(input_data)
+
+        # Priority 2: Inherit from current active span (ASGI/WSGI middleware)
+        if parent_context is None:
+            current_span = trace.get_current_span()
+            if current_span.is_recording():
+                parent_context = trace.set_span_in_context(current_span)
+
+        span = self._tracer.start_span(
+            name=f"workflow:{workflow_name}",
+            context=parent_context,
+            attributes={
+                "edda.workflow.instance_id": instance_id,
+                "edda.workflow.name": workflow_name,
+                "edda.workflow.input_keys": str(list(input_data.keys())),
+            },
+        )
+        self._workflow_spans[instance_id] = span
+        self._workflow_start_times[instance_id] = time.time()
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_started_counter.add(1, {"workflow_name": workflow_name})
+
+    async def on_workflow_complete(
+        self, instance_id: str, workflow_name: str, result: Any  # noqa: ARG002
+    ) -> None:
+        """End workflow span with success status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_status(Status(StatusCode.OK))
+            span.end()
+
+        # Always cleanup start time
+        start_time = self._workflow_start_times.pop(instance_id, None)
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_completed_counter.add(1, {"workflow_name": workflow_name})
+            if start_time:
+                duration = time.time() - start_time
+                self._workflow_duration_histogram.record(
+                    duration, {"workflow_name": workflow_name, "status": "completed"}
+                )
+
+    async def on_workflow_failed(
+        self, instance_id: str, workflow_name: str, error: Exception
+    ) -> None:
+        """End workflow span with error status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_status(Status(StatusCode.ERROR, str(error)))
+            span.record_exception(error)
+            span.end()
+
+        # Always cleanup start time
+        start_time = self._workflow_start_times.pop(instance_id, None)
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_failed_counter.add(
+                1,
+                {"workflow_name": workflow_name, "error_type": type(error).__name__},
+            )
+            if start_time:
+                duration = time.time() - start_time
+                self._workflow_duration_histogram.record(
+                    duration, {"workflow_name": workflow_name, "status": "failed"}
+                )
+
+    async def on_workflow_cancelled(
+        self, instance_id: str, workflow_name: str  # noqa: ARG002
+    ) -> None:
+        """End workflow span with cancelled status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_attribute("edda.workflow.cancelled", True)
+            span.set_status(Status(StatusCode.OK, "Cancelled"))
+            span.end()
+
+        self._workflow_start_times.pop(instance_id, None)
+
+    # =========================================================================
+    # Activity Hooks
+    # =========================================================================
+
+    async def on_activity_start(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,
+        is_replaying: bool,
+    ) -> None:
+        """Start an activity span as child of workflow span."""
+        parent_span = self._workflow_spans.get(instance_id)
+
+        # Create activity span with parent context
+        if parent_span:
+            ctx = trace.set_span_in_context(parent_span)
+            span = self._tracer.start_span(
+                name=f"activity:{activity_name}",
+                context=ctx,
+                attributes={
+                    "edda.activity.id": activity_id,
+                    "edda.activity.name": activity_name,
+                    "edda.activity.is_replaying": is_replaying,
+                    "edda.workflow.instance_id": instance_id,
+                },
+            )
+        else:
+            # No parent workflow span (edge case)
+            span = self._tracer.start_span(
+                name=f"activity:{activity_name}",
+                attributes={
+                    "edda.activity.id": activity_id,
+                    "edda.activity.name": activity_name,
+                    "edda.activity.is_replaying": is_replaying,
+                    "edda.workflow.instance_id": instance_id,
+                },
+            )
+
+        key = f"{instance_id}:{activity_id}"
+        self._activity_spans[key] = span
+        self._activity_start_times[key] = time.time()
+
+    async def on_activity_complete(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,
+        result: Any,  # noqa: ARG002
+        cache_hit: bool,
+    ) -> None:
+        """End activity span with success status."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.pop(key, None)
+        if span:
+            span.set_attribute("edda.activity.cache_hit", cache_hit)
+            span.set_status(Status(StatusCode.OK))
+            span.end()
+
+        # Metrics
+        if self._enable_metrics:
+            if cache_hit:
+                self._activity_cache_hit_counter.add(1, {"activity_name": activity_name})
+            else:
+                self._activity_executed_counter.add(1, {"activity_name": activity_name})
+                start_time = self._activity_start_times.pop(key, None)
+                if start_time:
+                    duration = time.time() - start_time
+                    self._activity_duration_histogram.record(
+                        duration, {"activity_name": activity_name}
+                    )
+
+    async def on_activity_failed(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,  # noqa: ARG002
+        error: Exception,
+    ) -> None:
+        """End activity span with error status."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.pop(key, None)
+        if span:
+            span.set_status(Status(StatusCode.ERROR, str(error)))
+            span.record_exception(error)
+            span.end()
+
+        self._activity_start_times.pop(key, None)
+
+    async def on_activity_retry(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,  # noqa: ARG002
+        error: Exception,
+        attempt: int,
+        delay: float,
+    ) -> None:
+        """Record retry event on current activity span."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.get(key)
+        if span:
+            span.add_event(
+                "retry",
+                attributes={
+                    "edda.retry.attempt": attempt,
+                    "edda.retry.delay_seconds": delay,
+                    "edda.retry.error": str(error),
+                    "edda.retry.error_type": type(error).__name__,
+                },
+            )
+
+    # =========================================================================
+    # Event Hooks
+    # =========================================================================
+
+    async def on_event_sent(
+        self,
+        event_type: str,
+        event_source: str,
+        event_data: dict[str, Any],  # noqa: ARG002
+    ) -> None:
+        """Record event sent as a short-lived span."""
+        with self._tracer.start_as_current_span(
+            name=f"event:send:{event_type}",
+            attributes={
+                "edda.event.type": event_type,
+                "edda.event.source": event_source,
+            },
+        ) as span:
+            span.set_status(Status(StatusCode.OK))
+
+    async def on_event_received(
+        self,
+        instance_id: str,
+        event_type: str,
+        event_data: dict[str, Any],  # noqa: ARG002
+    ) -> None:
+        """Record event received as an event on workflow span."""
+        parent_span = self._workflow_spans.get(instance_id)
+        if parent_span:
+            parent_span.add_event(
+                "event_received",
+                attributes={
+                    "edda.event.type": event_type,
+                },
+            )
+
+    # =========================================================================
+    # Trace Context Propagation
+    # =========================================================================
+
+    def _extract_trace_context(self, data: dict[str, Any]) -> Context | None:
+        """Extract W3C Trace Context from data dict."""
+        carrier: dict[str, str] = {}
+
+        # Check _trace_context nested dict (recommended)
+        if "_trace_context" in data:
+            tc = data["_trace_context"]
+            if isinstance(tc, dict):
+                carrier.update({k: v for k, v in tc.items() if k in ("traceparent", "tracestate")})
+
+        # Also check top-level keys
+        if "traceparent" in data:
+            carrier["traceparent"] = str(data["traceparent"])
+        if "tracestate" in data:
+            carrier["tracestate"] = str(data["tracestate"])
+
+        return self._propagator.extract(carrier) if carrier else None
+
+    def get_trace_context(self, instance_id: str) -> dict[str, str]:
+        """
+        Get W3C Trace Context for a workflow instance.
+
+        Use this to propagate trace context to external services or CloudEvents.
+
+        Args:
+            instance_id: Workflow instance ID
+
+        Returns:
+            dict with 'traceparent' and optionally 'tracestate' keys
+        """
+        carrier: dict[str, str] = {}
+        span = self._workflow_spans.get(instance_id)
+        if span:
+            ctx = trace.set_span_in_context(span)
+            self._propagator.inject(carrier, context=ctx)
+        return carrier
+
+
+# =============================================================================
+# Trace Context Propagation Helpers
+# =============================================================================
+
+
+def inject_trace_context(
+    hooks: OpenTelemetryHooks, instance_id: str, event_data: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Inject W3C Trace Context into event data for CloudEvents propagation.
+
+    Use this before calling send_event_transactional() to propagate trace
+    context across service boundaries.
+
+    Example::
+
+        from edda.integrations.opentelemetry import inject_trace_context
+        from edda.outbox.transactional import send_event_transactional
+
+        event_data = {"order_id": "ORD-123", "amount": 99.99}
+        event_data = inject_trace_context(hooks, ctx.instance_id, event_data)
+        await send_event_transactional(ctx, "payment.completed", "payment-service", event_data)
+
+    Args:
+        hooks: OpenTelemetryHooks instance
+        instance_id: Workflow instance ID
+        event_data: Event data dict to inject trace context into
+
+    Returns:
+        Updated event_data with _trace_context key
+    """
+    trace_context = hooks.get_trace_context(instance_id)
+    if trace_context:
+        event_data["_trace_context"] = trace_context
+    return event_data
+
+
+def extract_trace_context(event_data: dict[str, Any]) -> Context | None:
+    """
+    Extract W3C Trace Context from event data.
+
+    This is called automatically by OpenTelemetryHooks.on_workflow_start(),
+    but can also be used manually if needed.
+
+    Args:
+        event_data: Event data dict containing _trace_context
+
+    Returns:
+        OpenTelemetry Context or None if no trace context found
+    """
+    if not _OPENTELEMETRY_AVAILABLE:
+        return None
+
+    if "_trace_context" in event_data:
+        propagator = TraceContextTextMapPropagator()
+        return propagator.extract(event_data["_trace_context"])
+    return None

{edda_framework-0.4.0.dist-info → edda_framework-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.4.0
+Version: 0.5.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -42,6 +42,10 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'opentelemetry'
 Provides-Extra: postgresql
 Requires-Dist: asyncpg>=0.30.0; extra == 'postgresql'
 Provides-Extra: server
@@ -91,6 +95,28 @@ Edda excels at orchestrating **long-running workflows** that must survive failur
 - **🤖 AI Agent Workflows**: Orchestrate multi-step AI tasks (LLM calls, tool usage, long-running inference)
 - **📡 Event-Driven Workflows**: React to external events with guaranteed delivery and automatic retry
 
+### Business Process Automation
+
+Edda's waiting functions make it ideal for time-based and event-driven business processes:
+
+- **📧 User Onboarding**: Send reminders if users haven't completed setup after N days
+- **🎁 Campaign Processing**: Evaluate conditions and notify winners after campaign ends
+- **💳 Payment Reminders**: Send escalating reminders before payment deadlines
+- **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
+
+**Waiting functions**:
+- `wait_timer(duration_seconds)`: Wait for a relative duration
+- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `wait_event(event_type)`: Wait for external events (near real-time response)
+
+```python
+@workflow
+async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
+    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    if not await check_completed(ctx, user_id):
+        await send_reminder(ctx, user_id)
+```
+
 **Key benefit**: Workflows **never lose progress** - crashes and restarts are handled automatically through deterministic replay.
 
 ## Architecture

{edda_framework-0.4.0.dist-info → edda_framework-0.5.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
 edda/__init__.py,sha256=gmJd0ooVbGNMOLlSj-r6rEt3IkY-FZYCFjhWjIltqlk,1657
 edda/activity.py,sha256=nRm9eBrr0lFe4ZRQ2whyZ6mo5xd171ITIVhqytUhOpw,21025
-edda/app.py,sha256=YxURvhaC1dKcymOwuS1PHU6_iOl_5cZWse2vAKSyX8w,37471
+edda/app.py,sha256=8FKx9Kspbm5Fz-QDz4DgncNkkgdZkij209LHllWkRw4,38288
 edda/compensation.py,sha256=CmnyJy4jAklVrtLJodNOcj6vxET6pdarxM1Yx2RHlL4,11898
 edda/context.py,sha256=YZKBNtblRcaFqte1Y9t2cIP3JHzK-5Tu40x5i5FHtnU,17789
 edda/events.py,sha256=KN06o-Umkwkg9-TwbN4jr1uBZrBrvVSc6m8mOlQGXkA,18043
 edda/exceptions.py,sha256=-ntBLGpVQgPFG5N1o8m_7weejAYkNrUdxTkOP38vsHk,1766
-edda/hooks.py,sha256=eryLQMU1wwfeJkWUPBnq9olFigU6d4TKSRgcWK77a5U,8065
+edda/hooks.py,sha256=HUZ6FTM__DZjwuomDfTDEroQ3mugEPuJHcGm7CTQNvg,8193
 edda/locking.py,sha256=l3YM7zdERizw27jQXfLN7EmcMcrJSVzd7LD8hhsXvIM,11003
 edda/pydantic_utils.py,sha256=dGVPNrrttDeq1k233PopCtjORYjZitsgASPfPnO6R10,9056
 edda/replay.py,sha256=5RIRd0q2ZrH9iiiy35eOUii2cipYg9dlua56OAXvIk4,32499
@@ -16,6 +16,8 @@ edda/integrations/__init__.py,sha256=F_CaTvlDEbldfOpPKq_U9ve1E573tS6XzqXnOtyHcXI
 edda/integrations/mcp/__init__.py,sha256=YK-8m0DIdP-RSqewlIX7xnWU7TD3NioCiW2_aZSgnn8,1232
 edda/integrations/mcp/decorators.py,sha256=UTBb-Un2JK938pDZmANOvfsdKOMI2AF9yGtfSuy8VrE,6284
 edda/integrations/mcp/server.py,sha256=pzCG46Zko9hHmQ3REbo1w3A23SjrGFLiZupwSkIPhOA,13942
+edda/integrations/opentelemetry/__init__.py,sha256=x1_PyyygGDW-rxQTwoIrGzyjKErXHOOKdquFAMlCOAo,906
+edda/integrations/opentelemetry/hooks.py,sha256=FBYnSZBh8_0vw9M1E2AbJrx1cTTsKeiHf5wspr0UnzU,21288
 edda/outbox/__init__.py,sha256=azXG1rtheJEjOyoWmMsBeR2jp8Bz02R3wDEd5tQnaWA,424
 edda/outbox/relayer.py,sha256=2tnN1aOQ8pKWfwEGIlYwYLLwyOKXBjZ4XZsIr1HjgK4,9454
 edda/outbox/transactional.py,sha256=LFfUjunqRlGibaINi-efGXFFivWGO7v3mhqrqyGW6Nw,3808
@@ -33,8 +35,8 @@ edda/viewer_ui/data_service.py,sha256=mXV6bL6REa_UKsk8xMGBIFbsbLpIxe91lX3wgn-FOj
 edda/visualizer/__init__.py,sha256=DOpDstNhR0VcXAs_eMKxaL30p_0u4PKZ4o2ndnYhiRo,343
 edda/visualizer/ast_analyzer.py,sha256=plmx7C9X_X35xLY80jxOL3ljg3afXxBePRZubqUIkxY,13663
 edda/visualizer/mermaid_generator.py,sha256=XWa2egoOTNDfJEjPcwoxwQmblUqXf7YInWFjFRI1QGo,12457
-edda_framework-0.4.0.dist-info/METADATA,sha256=YEsevYgVMtBEBJlAhQL1lALOOiNrejsC9Z6QpyZsFRg,30272
-edda_framework-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-edda_framework-0.4.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.4.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.4.0.dist-info/RECORD,,
+edda_framework-0.5.0.dist-info/METADATA,sha256=GfZ0zYUy_g4zjV_OkYPPmNRTwIxZb77nh-aaS6Z_OYE,31503
+edda_framework-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+edda_framework-0.5.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.5.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.5.0.dist-info/RECORD,,