Enhance OpenTelemetry tracing documentation and client implementation for Python SDK

- Updated README to clarify OpenTelemetry tracing setup and functionality.
- Improved comments in client and worker scripts to reflect automatic span creation.
- Removed manual span creation from activity functions, leveraging SDK's built-in capabilities.
- Updated Jaeger UI references in documentation to match service name changes.

Author: torosent

samples/durable-task-sdks/python/opentelemetry-tracing/README.md

@@ -4,7 +4,7 @@ Python | Durable Task SDK
 
 ## Description
 
-This sample demonstrates how to add OpenTelemetry distributed tracing to a Durable Task SDK Python application. Traces are exported to Jaeger for visualization, allowing you to see the full flow of orchestrations and activities.
+This sample demonstrates OpenTelemetry distributed tracing with the Durable Task SDK for Python. The SDK **automatically** creates activity spans with `durabletask.*` tags and propagates W3C trace context from orchestrations to activities — no manual span creation needed in your activity code.
 
 ## Prerequisites
 
@@ -33,28 +33,44 @@ This sample demonstrates how to add OpenTelemetry distributed tracing to a Durab
    ```
 
 4. View traces:
-   - **Jaeger UI:** http://localhost:16686 (search for service `durable-worker`)
+   - **Jaeger UI:** http://localhost:16686 (search for service `DistributedTracingSample`)
    - **DTS Dashboard:** http://localhost:8082
 
 ## Viewing Traces
 
-Open the [Jaeger UI](http://localhost:16686), select the `durable-worker` service, and click **Find Traces**. You'll see one trace per activity — `validate_order`, `process_payment`, `ship_order`, and `send_notification`:
+Open the [Jaeger UI](http://localhost:16686), select the **DistributedTracingSample** service, and click **Find Traces**. You'll see a single trace with **5 Spans** — the parent `create_orchestration:OrderProcessingOrchestration` with 4 child activity spans:
 
-![Jaeger search results showing 4 activity traces](images/jaeger-search-results.png)
+![Jaeger search results showing orchestration trace with 5 spans](images/jaeger-search-results.png)
 
-Click on any trace to see span details including tags, duration, and OpenTelemetry metadata:
+Click on the trace to see the full span tree with parent-child hierarchy and rich `durabletask.*` tags (automatically added by the SDK):
 
-![Jaeger trace detail showing span tags and process info](images/jaeger-trace-detail.png)
+![Jaeger trace detail showing nested activity spans with durable task metadata](images/jaeger-trace-detail.png)
+
+## How It Works
+
+The Durable Task Python SDK has **built-in OpenTelemetry support**:
+
+1. **Client side**: When you schedule an orchestration with an active OpenTelemetry span, the SDK captures the W3C trace context (`traceparent`/`tracestate`) and sends it with the request.
+2. **Orchestrator side**: The SDK stores the parent trace context and passes it to all child activities and sub-orchestrations.
+3. **Activity side**: The SDK wraps each activity execution in an `activity:<name>` span as a child of the orchestration's trace context, with `durabletask.task.instance_id`, `durabletask.task.name`, and `durabletask.task.task_id` tags.
+
+All you need is to configure a `TracerProvider` with an exporter — the SDK does the rest.
 
 ## What You'll See
 
-These traces help you:
+The Jaeger UI shows a single trace for the entire orchestration with nested child spans for each activity. This helps you:
 
-- Identify slow activities
+- Identify slow activities within an orchestration
 - See the sequential flow of function chaining
-- Correlate traces across distributed services
+- Correlate the full orchestration lifecycle in one trace
 - Debug failures with full context
 
+## Clean Up
+
+```bash
+docker compose down
+```
+
 ## Learn More
 
 - [Observability Guide](../../../../docs/observability.md)

samples/durable-task-sdks/python/opentelemetry-tracing/client.py

@@ -1,4 +1,9 @@
-"""Client to schedule and monitor orchestrations with OpenTelemetry tracing."""
+"""Client to schedule and monitor orchestrations with OpenTelemetry tracing.
+
+The SDK automatically captures the current OpenTelemetry span context
+and propagates it as W3C trace context to the orchestration, which then
+forwards it to all activities and sub-orchestrations.
+"""
 import os
 import asyncio
 
@@ -18,7 +23,7 @@
 provider.add_span_processor(BatchSpanProcessor(exporter))
 trace.set_tracer_provider(provider)
 
-tracer = trace.get_tracer("Microsoft.DurableTask")
+tracer = trace.get_tracer("durabletask")
 
 
 async def main():
@@ -32,7 +37,8 @@ async def main():
         token_credential=None,
     )
 
-    # Create a parent span for the orchestration, matching the .NET SDK pattern
+    # Create a parent span — the SDK automatically captures this context
+    # and propagates it to the orchestration and all child activities.
     with tracer.start_as_current_span(
         "create_orchestration:OrderProcessingOrchestration",
         attributes={

samples/durable-task-sdks/python/opentelemetry-tracing/images/jaeger-search-results.png

@@ -1,4 +1,9 @@
-"""Worker with OpenTelemetry tracing for Durable Task SDK."""
+"""Worker with OpenTelemetry tracing for Durable Task SDK.
+
+The SDK automatically creates activity spans with durabletask.* tags
+and propagates W3C trace context from orchestrations to activities.
+All you need is to configure a TracerProvider with an exporter.
+"""
 import asyncio
 import os
 import time
@@ -15,60 +20,40 @@
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-# Configure OpenTelemetry with a service name that identifies this application
+# Configure OpenTelemetry — the SDK uses this tracer provider automatically
 resource = Resource.create({"service.name": "DistributedTracingSample"})
 provider = TracerProvider(resource=resource)
 otlp_endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
 exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
 provider.add_span_processor(BatchSpanProcessor(exporter))
 trace.set_tracer_provider(provider)
 
-tracer = trace.get_tracer("Microsoft.DurableTask")
-
-
-def _activity_span(activity_name: str, task_id: int = 0):
-    """Create an activity span with durable task metadata tags."""
-    span = tracer.start_span(
-        f"activity:{activity_name}",
-        attributes={
-            "durabletask.task.name": activity_name,
-            "durabletask.type": "activity",
-            "durabletask.task.task_id": task_id,
-        },
-    )
-    return span
 
+# Activities — no manual span creation needed. The SDK wraps each
+# activity execution in an "activity:<name>" span automatically.
 
 def validate_order(ctx, order_id: str) -> str:
-    span = _activity_span("ValidateOrder", task_id=1)
-    with trace.use_span(span, end_on_exit=True):
-        logger.info(f"Validating order: {order_id}")
-        time.sleep(0.1)
-        return f"Validated({order_id})"
+    logger.info(f"Validating order: {order_id}")
+    time.sleep(0.1)
+    return f"Validated({order_id})"
 
 
 def process_payment(ctx, input: str) -> str:
-    span = _activity_span("ProcessPayment", task_id=2)
-    with trace.use_span(span, end_on_exit=True):
-        logger.info(f"Processing payment for: {input}")
-        time.sleep(0.2)
-        return f"Paid({input})"
+    logger.info(f"Processing payment for: {input}")
+    time.sleep(0.2)
+    return f"Paid({input})"
 
 
 def ship_order(ctx, input: str) -> str:
-    span = _activity_span("ShipOrder", task_id=3)
-    with trace.use_span(span, end_on_exit=True):
-        logger.info(f"Shipping: {input}")
-        time.sleep(0.15)
-        return f"Shipped({input})"
+    logger.info(f"Shipping: {input}")
+    time.sleep(0.15)
+    return f"Shipped({input})"
 
 
 def send_notification(ctx, input: str) -> str:
-    span = _activity_span("SendNotification", task_id=4)
-    with trace.use_span(span, end_on_exit=True):
-        logger.info(f"Notifying customer: {input}")
-        time.sleep(0.05)
-        return f"Notified({input})"
+    logger.info(f"Notifying customer: {input}")
+    time.sleep(0.05)
+    return f"Notified({input})"
 
 
 def order_processing_orchestration(ctx, order_id: str):