edda-framework 0.3.1__tar.gz → 0.5.0__tar.gz

{edda_framework-0.3.1 → edda_framework-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.3.1
+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
@@ -730,6 +756,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.1 → edda_framework-0.5.0}/README.md

@@ -39,6 +39,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
@@ -678,6 +700,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.1 → edda_framework-0.5.0}/demo_app.py

@@ -492,10 +492,10 @@ async def order_processing_workflow(
             {"item_id": "ITEM-2", "name": "Product B", "price": 49.99, "quantity": 1}
         ],
         "shipping_address": {
-            "street": "123 Main St",
-            "city": "San Francisco",
-            "state": "CA",
-            "zip_code": "94102"
+            "street": "221B Baker Street",
+            "city": "London",
+            "state": "Greater London",
+            "zip_code": "NW1 6XE"
         }
     }
 

{edda_framework-0.3.1 → edda_framework-0.5.0}/docs/core-features/durable-execution/replay.md

@@ -100,9 +100,9 @@ async def arrange_shipping(ctx: WorkflowContext, order_id: str):
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str):
     # Activity IDs are auto-generated for sequential calls
-    inventory = await reserve_inventory(ctx, order_id, activity_id="reserve_inventory:1")
-    payment = await process_payment(ctx, order_id, activity_id="process_payment:1")
-    shipping = await arrange_shipping(ctx, order_id, activity_id="arrange_shipping:1")
+    inventory = await reserve_inventory(ctx, order_id)
+    payment = await process_payment(ctx, order_id)
+    shipping = await arrange_shipping(ctx, order_id)
 
     return {"status": "completed"}
 ```
@@ -497,16 +497,16 @@ async with workflow_lock(storage, instance_id, worker_id):
 ```python
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str):
-    # Activity 1
-    inventory = await reserve_inventory(ctx, order_id, activity_id="reserve_inventory:1")
+    # Activity 1 (auto-generated ID: "reserve_inventory:1")
+    inventory = await reserve_inventory(ctx, order_id)
     # → DB saved: activity_id="reserve_inventory:1", result={"reservation_id": "R123"}
 
-    # Activity 2
-    payment = await process_payment(ctx, order_id, activity_id="process_payment:1")
+    # Activity 2 (auto-generated ID: "process_payment:1")
+    payment = await process_payment(ctx, order_id)
     # → DB saved: activity_id="process_payment:1", result={"transaction_id": "T456"}
 
     # Activity 3: Exception occurs (e.g., network error)
-    shipping = await arrange_shipping(ctx, order_id, activity_id="arrange_shipping:1")
+    shipping = await arrange_shipping(ctx, order_id)
     # → Exception thrown, workflow interrupted
 ```
 

{edda_framework-0.3.1 → edda_framework-0.5.0}/docs/core-features/hooks.md

@@ -30,9 +30,10 @@ class LogfireHooks(HooksBase):
             instance_id=instance_id,
             workflow_name=workflow_name)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         logfire.info("activity.complete",
             instance_id=instance_id,
+            activity_id=activity_id,
             activity_name=activity_name,
             cache_hit=cache_hit
         )
@@ -69,9 +70,9 @@ The `WorkflowHooks` Protocol defines these methods (all optional):
 | `on_workflow_complete` | `instance_id`, `workflow_name`, `result` | Called when a workflow completes successfully |
 | `on_workflow_failed` | `instance_id`, `workflow_name`, `error` | Called when a workflow fails with an exception |
 | `on_workflow_cancelled` | `instance_id`, `workflow_name` | Called when a workflow is cancelled |
-| `on_activity_start` | `instance_id`, `step`, `activity_name`, `is_replaying` | Called before an activity executes |
-| `on_activity_complete` | `instance_id`, `step`, `activity_name`, `result`, `cache_hit` | Called after an activity completes successfully |
-| `on_activity_failed` | `instance_id`, `step`, `activity_name`, `error` | Called when an activity fails with an exception |
+| `on_activity_start` | `instance_id`, `activity_id`, `activity_name`, `is_replaying` | Called before an activity executes |
+| `on_activity_complete` | `instance_id`, `activity_id`, `activity_name`, `result`, `cache_hit` | Called after an activity completes successfully |
+| `on_activity_failed` | `instance_id`, `activity_id`, `activity_name`, `error` | Called when an activity fails with an exception |
 | `on_event_sent` | `event_type`, `event_source`, `event_data` | Called when an event is sent (transactional outbox) |
 | `on_event_received` | `instance_id`, `event_type`, `event_data` | Called when a workflow receives an awaited event |
 
@@ -150,8 +151,9 @@ class LogfireHooks(HooksBase):
             instance_id=instance_id,
             workflow_name=workflow_name)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         logfire.info("activity.complete",
+            activity_id=activity_id,
             activity_name=activity_name,
             cache_hit=cache_hit)
 
@@ -181,7 +183,7 @@ class DatadogHooks(HooksBase):
             span.set_tag("workflow.name", workflow_name)
             span.set_tag("instance.id", instance_id)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         statsd.increment('edda.activity.completed',
             tags=[f'activity:{activity_name}', f'cache_hit:{cache_hit}'])
 ```
@@ -199,7 +201,7 @@ class PrometheusHooks(HooksBase):
     async def on_workflow_start(self, instance_id, workflow_name, input_data):
         workflow_started.labels(workflow_name=workflow_name).inc()
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         activity_executed.labels(activity_name=activity_name, cache_hit=str(cache_hit)).inc()
 ```
 
@@ -218,17 +220,50 @@ class SentryHooks(HooksBase):
             })
             sentry_sdk.capture_exception(error)
 
-    async def on_activity_failed(self, instance_id, step, activity_name, error):
+    async def on_activity_failed(self, instance_id, activity_id, activity_name, error):
         with sentry_sdk.push_scope() as scope:
             scope.set_context("activity", {
                 "instance_id": instance_id,
+                "activity_id": activity_id,
                 "activity_name": activity_name,
             })
             sentry_sdk.capture_exception(error)
 ```
 
+### OpenTelemetry (Official Integration)
+
+Edda provides an official OpenTelemetry integration with full tracing, optional metrics, and W3C Trace Context propagation.
+
+```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,
+)
+```
+
+**Features:**
+
+- ✅ Distributed tracing with parent-child span relationships
+- ✅ Optional metrics (counters, histograms)
+- ✅ W3C Trace Context propagation via CloudEvents
+- ✅ Automatic context inheritance from ASGI/WSGI middleware
+
+👉 **See [OpenTelemetry Integration](../integrations/opentelemetry.md) for full documentation.**
+
 ## See Also
 
+- **[OpenTelemetry Integration](../integrations/opentelemetry.md)**: Official OpenTelemetry integration with full documentation
 - **[Complete Logfire Example](https://github.com/i2y/edda/blob/main/examples/observability_with_logfire.py)**: Full implementation with multiple workflows
+- **[Complete OpenTelemetry Example](https://github.com/i2y/edda/blob/main/examples/observability_with_opentelemetry.py)**: Full implementation with tracing, optional metrics, and CloudEvents context propagation
 - **[Observability Guide](https://github.com/i2y/edda/blob/main/examples/README_observability.md)**: Detailed guide with more integration examples
 - **[API Reference](https://github.com/i2y/edda/blob/main/edda/hooks.py)**: WorkflowHooks Protocol definition

{edda_framework-0.3.1 → edda_framework-0.5.0}/docs/core-features/workflows-activities.md

@@ -147,8 +147,8 @@ async def async_activity(ctx: WorkflowContext, data: str) -> dict:
 async def mixed_workflow(ctx: WorkflowContext, user_id: str) -> dict:
     # Workflows are always async (for deterministic replay)
     # But can call both sync and async activities
-    user = await create_user_record(ctx, user_id, "user@example.com", activity_id="create:1")
-    data = await async_activity(ctx, user_id, activity_id="fetch:1")
+    user = await create_user_record(ctx, user_id, "user@example.com")
+    data = await async_activity(ctx, user_id)
     return {"user": user, "data": data}
 ```
 
@@ -823,8 +823,8 @@ def process_legacy_data(ctx: WorkflowContext, data: str) -> dict:
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str) -> dict:
     # Both sync and async activities work fine
-    user = await create_user_record(ctx, order_id, activity_id="user:1")  # Sync
-    payment = await process_payment(ctx, 99.99, activity_id="pay:1")  # Async
+    user = await create_user_record(ctx, order_id)  # Sync
+    payment = await process_payment(ctx, 99.99)  # Async
     return {"user": user, "payment": payment}
 ```
 

{edda_framework-0.3.1 → edda_framework-0.5.0}/docs/getting-started/first-workflow.md

@@ -272,36 +272,40 @@ async def main():
     # Initialize the app (required before starting workflows)
     await app.initialize()
 
-    # Create order input
-    order = OrderInput(
-        order_id="ORD-12345",
-        customer_email="customer@example.com",
-        items=[
-            OrderItem(product_id="PROD-1", quantity=2, unit_price=29.99),
-            OrderItem(product_id="PROD-2", quantity=1, unit_price=49.99),
-        ],
-        shipping_address=ShippingAddress(
-            street="123 Main St",
-            city="San Francisco",
-            postal_code="94105",
-            country="USA"
+    try:
+        # Create order input
+        order = OrderInput(
+            order_id="ORD-12345",
+            customer_email="customer@example.com",
+            items=[
+                OrderItem(product_id="PROD-1", quantity=2, unit_price=29.99),
+                OrderItem(product_id="PROD-2", quantity=1, unit_price=49.99),
+            ],
+            shipping_address=ShippingAddress(
+                street="1-2-3 Dogenzaka",
+                city="Shibuya",
+                postal_code="150-0001",
+                country="Japan"
+            )
         )
-    )
 
-    # Start workflow
-    print("Starting order processing workflow...")
-    instance_id = await order_processing_workflow.start(input=order)
+        # Start workflow
+        print("Starting order processing workflow...")
+        instance_id = await order_processing_workflow.start(input=order)
+
+        print(f"\n✅ Workflow started: {instance_id}")
 
-    print(f"\n✅ Workflow started: {instance_id}")
+        # Get result
+        instance = await app.storage.get_instance(instance_id)
+        if instance["status"] == "completed":
+            result = instance["output_data"]
+            print(f"📊 Order completed:")
+            print(f"   - Order ID: {result['order_id']}")
+            print(f"   - Total: ${result['total_amount']:.2f}")
+            print(f"   - Tracking: {result['confirmation_number']}")
 
-    # Get result
-    instance = await app.storage.get_instance(instance_id)
-    if instance["status"] == "completed":
-        result = instance["output_data"]
-        print(f"📊 Order completed:")
-        print(f"   - Order ID: {result['order_id']}")
-        print(f"   - Total: ${result['total_amount']:.2f}")
-        print(f"   - Tracking: {result['confirmation_number']}")
+    finally:
+        await app.shutdown()
 
 if __name__ == "__main__":
     asyncio.run(main())
@@ -322,7 +326,7 @@ Starting order processing workflow...
 
 📦 Reserving inventory for ORD-12345: $109.97
 💳 Processing payment for ORD-12345: $109.97
-🚚 Shipping ORD-12345 to San Francisco, USA
+🚚 Shipping ORD-12345 to Shibuya, Japan
 
 ✅ Workflow started: <instance_id>
 📊 Order completed:
@@ -364,7 +368,7 @@ uv run python order_workflow.py
 ```
 📦 Reserving inventory for ORD-12345: $109.97
 💳 Processing payment for ORD-12345: $109.97
-🚚 Shipping ORD-12345 to San Francisco, USA
+🚚 Shipping ORD-12345 to Shibuya, Japan
 💥 Exception: Shipping service unavailable!
 
 ❌ Refunding payment for ORD-12345: $109.97

{edda_framework-0.3.1 → edda_framework-0.5.0}/docs/index.md

@@ -36,6 +36,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
@@ -93,21 +115,22 @@ from edda import EddaApp, workflow, activity, WorkflowContext
 
 @activity
 async def process_payment(ctx: WorkflowContext, amount: float):
-    # Durable execution - automatically recorded in history
     print(f"Processing payment: ${amount}")
     return {"status": "paid", "amount": amount}
 
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float):
-    # Workflow orchestrates activities with automatic retry on crash
     result = await process_payment(ctx, amount)
     return {"order_id": order_id, **result}
 
-# Simplified example - production code needs:
-# 1. await app.initialize() before starting workflows
-# 2. try-finally with await app.shutdown() for cleanup
-app = EddaApp(service_name="demo-service", db_url="sqlite:///workflow.db")
-instance_id = await order_workflow.start(order_id="ORD-123", amount=99.99)
+async def main():
+    app = EddaApp(service_name="demo-service", db_url="sqlite:///workflow.db")
+    await app.initialize()
+    try:
+        instance_id = await order_workflow.start(order_id="ORD-123", amount=99.99)
+        print(f"Started workflow: {instance_id}")
+    finally:
+        await app.shutdown()
 ```
 
 **What happens on crash?**

edda_framework-0.5.0/docs/integrations/opentelemetry.md

@@ -0,0 +1,179 @@
+# OpenTelemetry Integration
+
+Edda provides official integration with [OpenTelemetry](https://opentelemetry.io/), enabling distributed tracing and optional metrics for your durable workflows.
+
+## Overview
+
+OpenTelemetry is an industry-standard observability framework. Edda's OpenTelemetry integration provides:
+
+- **Distributed Tracing**: Workflow and activity spans with parent-child relationships
+- **Optional Metrics**: Counters for workflow/activity execution, histograms for duration
+- **W3C Trace Context**: Propagate traces across service boundaries via CloudEvents
+- **Automatic Context Inheritance**: Inherit from ASGI/WSGI middleware or CloudEvents headers
+
+## Installation
+
+Install Edda with OpenTelemetry support:
+
+```bash
+pip install edda-framework[opentelemetry]
+
+# Or using uv
+uv add edda-framework --extra opentelemetry
+```
+
+## Quick Start
+
+```python
+from edda import EddaApp, workflow, activity, WorkflowContext
+from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+# Create hooks (console exporter for development)
+hooks = OpenTelemetryHooks(
+    service_name="order-service",
+    otlp_endpoint=None,  # Use console exporter
+    enable_metrics=False,
+)
+
+# Or with OTLP exporter for production (Jaeger, Tempo, etc.)
+hooks = OpenTelemetryHooks(
+    service_name="order-service",
+    otlp_endpoint="http://localhost:4317",
+    enable_metrics=True,
+)
+
+app = EddaApp(
+    service_name="order-service",
+    db_url="sqlite:///workflow.db",
+    hooks=hooks,
+)
+
+@activity
+async def reserve_inventory(ctx: WorkflowContext, order_id: str):
+    return {"reserved": True}
+
+@workflow
+async def order_workflow(ctx: WorkflowContext, order_id: str):
+    await reserve_inventory(ctx, order_id)
+    return {"status": "completed"}
+
+async def main():
+    await app.initialize()
+    await order_workflow.start(order_id="ORD-123")
+```
+
+## Span Hierarchy
+
+Edda creates a hierarchical span structure:
+
+```
+workflow:order_workflow (parent)
+├── activity:reserve_inventory:1 (child)
+├── activity:process_payment:1 (child)
+└── activity:ship_order:1 (child)
+```
+
+## Span Attributes
+
+**Workflow Spans**:
+- `edda.workflow.instance_id`
+- `edda.workflow.name`
+- `edda.workflow.cancelled` (when cancelled)
+
+**Activity Spans**:
+- `edda.activity.id` (e.g., "reserve_inventory:1")
+- `edda.activity.name`
+- `edda.activity.is_replaying`
+- `edda.activity.cache_hit`
+
+## Metrics (Optional)
+
+When `enable_metrics=True`:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `edda.workflow.started` | Counter | Workflows started |
+| `edda.workflow.completed` | Counter | Workflows completed |
+| `edda.workflow.failed` | Counter | Workflows failed |
+| `edda.workflow.duration` | Histogram | Workflow execution time |
+| `edda.activity.executed` | Counter | Activities executed |
+| `edda.activity.cache_hit` | Counter | Activity cache hits |
+| `edda.activity.duration` | Histogram | Activity execution time |
+
+## Trace Context Propagation
+
+### Automatic Context Inheritance
+
+OpenTelemetryHooks automatically inherits trace context from multiple sources, with the following priority:
+
+1. **Explicit `_trace_context` in input_data** (highest priority)
+   - Extracted from CloudEvents extension attributes
+   - Useful for cross-service trace propagation
+
+2. **Current active span** (e.g., from ASGI/WSGI middleware)
+   - Automatically detected using `trace.get_current_span()`
+   - Works with OpenTelemetry instrumentation middleware
+
+3. **New root span** (if no parent context is found)
+
+### CloudEvents Integration
+
+Inject trace context when sending events:
+
+```python
+from edda.integrations.opentelemetry import inject_trace_context
+
+event_data = {"order_id": "ORD-123"}
+event_data = inject_trace_context(hooks, ctx.instance_id, event_data)
+await send_event_transactional(ctx, "order.shipped", "orders", event_data)
+```
+
+When a CloudEvent contains W3C Trace Context extension attributes (`traceparent`, `tracestate`), they are automatically extracted and used as the parent context:
+
+```bash
+# CloudEvent with trace context
+curl -X POST http://localhost:8001/ \
+  -H "Content-Type: application/json" \
+  -H "ce-specversion: 1.0" \
+  -H "ce-type: order.created" \
+  -H "ce-source: external-service" \
+  -H "ce-id: event-123" \
+  -H "ce-traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" \
+  -d '{"order_id": "ORD-123"}'
+```
+
+### ASGI/WSGI Middleware
+
+OpenTelemetryHooks automatically inherits from the current active span:
+
+```python
+from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+
+# Middleware creates parent span for each HTTP request
+app = OpenTelemetryMiddleware(edda_app)
+
+# Workflow spans automatically inherit from the request span
+```
+
+### Existing TracerProvider Reuse
+
+If a TracerProvider is already configured (e.g., by ASGI middleware or your application), OpenTelemetryHooks will reuse it instead of creating a new one:
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+# Configure your own provider
+provider = TracerProvider(resource=my_resource)
+trace.set_tracer_provider(provider)
+
+# OpenTelemetryHooks will use the existing provider
+hooks = OpenTelemetryHooks(service_name="my-service")
+# No new provider is created!
+```
+
+## Related Documentation
+
+- [Lifecycle Hooks](../core-features/hooks.md) - Detailed hooks documentation
+- [Example](../../examples/observability_with_opentelemetry.py) - Complete working example
+- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)