Add sample DT app + screenshots

Author: andystaples

examples/distributed-tracing/README.md

@@ -0,0 +1,186 @@
+# Distributed Tracing Example
+
+This example demonstrates how to set up **distributed tracing** with the
+Durable Task Python SDK using [OpenTelemetry](https://opentelemetry.io/)
+and [Jaeger](https://www.jaegertracing.io/) as the trace backend.
+
+The sample orchestration showcases three key Durable Task features that
+all produce correlated trace spans:
+
+1. **Timers** — a short delay before starting work.
+1. **Sub-orchestration** — delegates city-level weather collection to a
+   child orchestration.
+1. **Activities** — individual activity calls to fetch weather data and
+   produce a summary.
+
+## Prerequisites
+
+- [Docker](https://www.docker.com/) (for the emulator and Jaeger)
+- Python 3.10+
+
+## Quick Start
+
+### 1. Start the DTS Emulator
+
+```bash
+docker run --name dtsemulator -d -p 8080:8080 mcr.microsoft.com/dts/dts-emulator:latest
+```
+
+### 2. Start Jaeger
+
+Jaeger's all-in-one image accepts OTLP over gRPC on port **4317** and
+serves the UI on port **16686**:
+
+```bash
+docker run --name jaeger -d \
+  -p 4317:4317 \
+  -p 16686:16686 \
+  jaegertracing/all-in-one:latest
+```
+
+PowerShell:
+
+```powershell
+docker run --name jaeger -d `
+  -p 4317:4317 `
+  -p 16686:16686 `
+  jaegertracing/all-in-one:latest
+```
+
+### 3. Install Dependencies
+
+Create and activate a virtual environment, then install the required
+packages:
+
+```bash
+python -m venv .venv
+```
+
+Bash:
+
+```bash
+source .venv/bin/activate
+```
+
+PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Install requirements:
+
+```bash
+pip install -r requirements.txt
+```
+
+If you are running from a local clone of the repository, install the
+local packages in editable mode instead (run from the repo root):
+
+```bash
+pip install -e ".[opentelemetry]" -e ./durabletask-azuremanaged
+```
+
+### 4. Run the Example
+
+```bash
+python app.py
+```
+
+Once the orchestration completes, open the Jaeger UI at
+<http://localhost:16686>, select the **durabletask-tracing-example**
+service, and click **Find Traces** to explore the spans.
+
+## What You Will See in Jaeger
+
+A single trace for the orchestration will contain spans for:
+
+- **`orchestration:weather_report_orchestrator`** — the top-level
+  orchestration span.
+- **`timer`** — the 2-second timer delay.
+- **`orchestration:collect_weather`** — the sub-orchestration span.
+- **`activity:get_weather`** — one span per city
+  (Tokyo, Seattle, London).
+- **`activity:summarize`** — the final summarization activity.
+
+All spans share the same trace ID, so you can follow the full execution
+flow from the parent orchestration through the sub-orchestration and
+into each activity.
+
+## Configuration
+
+The example reads the following environment variables (all optional):
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENDPOINT` | `http://localhost:8080` | DTS emulator / scheduler endpoint |
+| `TASKHUB` | `default` | Task hub name |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP gRPC endpoint (Jaeger) |
+
+## Important Usage Guidelines for Distributed Tracing
+
+### Install the OpenTelemetry extras
+
+The SDK ships OpenTelemetry as an **optional** dependency. Install it
+with the `opentelemetry` extra:
+
+```bash
+pip install "durabletask[opentelemetry]"
+```
+
+Without these packages the SDK still works, but no trace spans are
+emitted.
+
+### Configure the `TracerProvider` before starting the worker
+
+OpenTelemetry requires a configured `TracerProvider` with at least one
+`SpanProcessor` and exporter **before** any spans are created. In
+practice this means setting it up at the top of your entry-point module,
+before constructing the worker or client:
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+resource = Resource.create({"service.name": "my-app"})
+provider = TracerProvider(resource=resource)
+provider.add_span_processor(
+    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True))
+)
+trace.set_tracer_provider(provider)
+```
+
+### Flush spans before exiting
+
+The `BatchSpanProcessor` buffers spans and exports them in the
+background. If the process exits before the buffer is flushed, some
+spans may be lost. Call `provider.force_flush()` (and optionally add a
+short sleep) before your program terminates:
+
+```python
+provider.force_flush()
+```
+
+### Orchestrator code must remain deterministic
+
+Distributed tracing does **not** change the determinism requirement for
+orchestrator functions. Do not create your own OpenTelemetry spans
+inside orchestrator code — the SDK handles span creation automatically.
+Activity functions and client code are free to create additional spans
+as needed.
+
+### Use `BatchSpanProcessor` in production
+
+`SimpleSpanProcessor` exports every span synchronously, which adds
+latency to every operation. Use `BatchSpanProcessor` for production
+workloads to avoid performance overhead.
+
+### Choose the right exporter for your backend
+
+This example uses the OTLP/gRPC exporter, which is compatible with
+Jaeger 1.35+, the OpenTelemetry Collector, Azure Monitor (via the
+Azure Monitor OpenTelemetry exporter), and many other backends. Swap
+the exporter if your tracing backend uses a different protocol.

examples/distributed-tracing/app.py

@@ -0,0 +1,168 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Distributed tracing example using OpenTelemetry and Jaeger.
+
+This example demonstrates how to configure OpenTelemetry distributed tracing
+with the Durable Task Python SDK. The orchestration showcases timers,
+activities, and a sub-orchestration, all producing correlated trace spans
+visible in the Jaeger UI.
+
+Prerequisites:
+  - DTS emulator running on localhost:8080
+  - Jaeger running on localhost:4317 (OTLP gRPC) / localhost:16686 (UI)
+  - pip install -r requirements.txt
+"""
+
+import os
+import time
+from datetime import timedelta
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from azure.identity import DefaultAzureCredential
+
+from durabletask import client, task
+from durabletask.azuremanaged.client import DurableTaskSchedulerClient
+from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
+
+
+# ---------------------------------------------------------------------------
+# OpenTelemetry configuration — MUST be done before any spans are created
+# ---------------------------------------------------------------------------
+
+OTEL_ENDPOINT = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
+
+resource = Resource.create({"service.name": "durabletask-tracing-example"})
+provider = TracerProvider(resource=resource)
+provider.add_span_processor(
+    BatchSpanProcessor(
+        OTLPSpanExporter(endpoint=OTEL_ENDPOINT, insecure=True)
+    )
+)
+trace.set_tracer_provider(provider)
+
+
+# ---------------------------------------------------------------------------
+# Activity functions
+# ---------------------------------------------------------------------------
+
+def get_weather(ctx: task.ActivityContext, city: str) -> str:
+    """Simulate fetching weather data for a city."""
+    # In a real app this would call an external API
+    weather_data = {
+        "Tokyo": "Sunny, 22°C",
+        "Seattle": "Rainy, 12°C",
+        "London": "Cloudy, 15°C",
+    }
+    result = weather_data.get(city, "Unknown")
+    print(f"  [Activity] get_weather({city}) -> {result}")
+    return result
+
+
+def summarize(ctx: task.ActivityContext, reports: list) -> str:
+    """Combine individual weather reports into a summary string."""
+    summary = " | ".join(reports)
+    print(f"  [Activity] summarize -> {summary}")
+    return summary
+
+
+# ---------------------------------------------------------------------------
+# Sub-orchestration
+# ---------------------------------------------------------------------------
+
+def collect_weather(ctx: task.OrchestrationContext, cities: list):
+    """Sub-orchestration that collects weather for a list of cities."""
+    results = []
+    for city in cities:
+        weather = yield ctx.call_activity(get_weather, input=city)
+        results.append(f"{city}: {weather}")
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Main orchestration
+# ---------------------------------------------------------------------------
+
+def weather_report_orchestrator(ctx: task.OrchestrationContext, cities: list):
+    """Top-level orchestration demonstrating timers, activities, and sub-orchestrations.
+
+    Flow:
+      1. Wait for a short timer (simulating a scheduled delay).
+      2. Call a sub-orchestration to collect weather data for each city.
+      3. Call an activity to summarize the results.
+    """
+    # Step 1 — Timer: wait briefly before starting work
+    yield ctx.create_timer(timedelta(seconds=2))
+    if not ctx.is_replaying:
+        print("  [Orchestrator] Timer fired — starting weather collection")
+
+    # Step 2 — Sub-orchestration: delegate city-level work
+    reports = yield ctx.call_sub_orchestrator(collect_weather, input=cities)
+
+    # Step 3 — Activity: summarize the collected reports
+    summary = yield ctx.call_activity(summarize, input=reports)
+
+    return summary
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    # Use environment variables if provided, otherwise use default emulator values
+    taskhub_name = os.getenv("TASKHUB", "default")
+    endpoint = os.getenv("ENDPOINT", "http://localhost:8080")
+
+    print(f"Using taskhub: {taskhub_name}")
+    print(f"Using endpoint: {endpoint}")
+    print(f"OTLP endpoint: {OTEL_ENDPOINT}")
+
+    # Set credential to None for emulator, or DefaultAzureCredential for Azure
+    secure_channel = endpoint.startswith("https://")
+    credential = DefaultAzureCredential() if secure_channel else None
+
+    with DurableTaskSchedulerWorker(
+        host_address=endpoint,
+        secure_channel=secure_channel,
+        taskhub=taskhub_name,
+        token_credential=credential,
+    ) as w:
+        # Register orchestrators and activities
+        w.add_orchestrator(weather_report_orchestrator)
+        w.add_orchestrator(collect_weather)
+        w.add_activity(get_weather)
+        w.add_activity(summarize)
+        w.start()
+        print("Worker started.")
+
+        # Create client, schedule the orchestration, and wait for completion
+        c = DurableTaskSchedulerClient(
+            host_address=endpoint,
+            secure_channel=secure_channel,
+            taskhub=taskhub_name,
+            token_credential=credential,
+        )
+
+        cities = ["Tokyo", "Seattle", "London"]
+        instance_id = c.schedule_new_orchestration(
+            weather_report_orchestrator, input=cities,
+        )
+        print(f"Orchestration started: {instance_id}")
+
+        state = c.wait_for_orchestration_completion(instance_id, timeout=60)
+        if state and state.runtime_status == client.OrchestrationStatus.COMPLETED:
+            print(f"Orchestration completed! Result: {state.serialized_output}")
+        elif state:
+            print(f"Orchestration failed: {state.failure_details}")
+
+        # Flush any remaining spans to the exporter
+        provider.force_flush()
+        time.sleep(1)
+
+    print("Done. Open Jaeger at http://localhost:16686 to view traces.")

examples/distributed-tracing/images/dts-dashboard-completed.png

@@ -0,0 +1,4 @@
+durabletask[opentelemetry]
+durabletask-azuremanaged
+azure-identity
+opentelemetry-exporter-otlp-proto-grpc