Fix timer span parent context and update screenshots

- Timer span now correctly uses parentTraceContext as parent, linking
  it to the orchestration trace instead of creating a separate trace
- Updated sample to include 1-second durable timer before fan-out
- Updated screenshots showing 15 spans with timer span in hierarchy
- Updated README with timer span documentation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: torosent

client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java

@@ -150,7 +150,7 @@ public void raiseEvent(String instanceId, String eventName, Object eventPayload)
         Helpers.throwIfArgumentNull(instanceId, "instanceId");
         Helpers.throwIfArgumentNull(eventName, "eventName");
 
-        // Emit an event span matching .NET SDK's StartActivityForNewEventRaisedFromClient
+        // Emit an event span  StartActivityForNewEventRaisedFromClient
         TracingHelper.emitEventRaisedFromClientSpan(eventName, instanceId);
 
         RaiseEventRequest.Builder builder = RaiseEventRequest.newBuilder()

client/src/main/java/com/microsoft/durabletask/TaskOrchestrationExecutor.java

@@ -397,7 +397,7 @@ public void sendEvent(String instanceId, String eventName, Object eventData) {
                         id,
                         serializedEventData != null ? serializedEventData : "(null)"));
 
-                // Emit an event span matching .NET SDK's StartTraceActivityForEventRaisedFromWorker
+                // Emit an event span  StartTraceActivityForEventRaisedFromWorker
                 TracingHelper.emitEventRaisedFromWorkerSpan(eventName, this.instanceId, instanceId);
             }
         }
@@ -744,7 +744,8 @@ public void handleTimerFired(HistoryEvent e) {
                         this.getName(),
                         this.instanceId,
                         timerEventId,
-                        fireAt);
+                        fireAt,
+                        this.parentTraceContext);
             }
 
             CompletableTask<?> task = record.getTask();

client/src/main/java/com/microsoft/durabletask/TracingHelper.java

@@ -278,12 +278,14 @@ static void endSpan(@Nullable Span span, @Nullable Throwable error) {
      * @param instanceId        The orchestration instance ID.
      * @param timerId           The timer event ID.
      * @param fireAt            The ISO-8601 formatted fire time.
+     * @param parentContext     The parent trace context, may be {@code null}.
      */
     static void emitTimerSpan(
             String orchestrationName,
             @Nullable String instanceId,
             int timerId,
-            @Nullable String fireAt) {
+            @Nullable String fireAt,
+            @Nullable TraceContext parentContext) {
         Tracer tracer = GlobalOpenTelemetry.getTracer(TRACER_NAME);
         SpanBuilder spanBuilder = tracer.spanBuilder(
                 TYPE_ORCHESTRATION + ":" + orchestrationName + ":" + TYPE_TIMER)
@@ -292,6 +294,11 @@ static void emitTimerSpan(
                 .setAttribute(ATTR_TASK_NAME, orchestrationName)
                 .setAttribute(ATTR_TASK_ID, String.valueOf(timerId));
 
+        Context parentCtx = extractTraceContext(parentContext);
+        if (parentCtx != null) {
+            spanBuilder.setParent(parentCtx);
+        }
+
         if (instanceId != null) {
             spanBuilder.setAttribute(ATTR_INSTANCE_ID, instanceId);
         }

client/src/test/java/com/microsoft/durabletask/TracingHelperTest.java

@@ -293,7 +293,7 @@ void createClientSpan_withNullParent_returnsNull() {
 
     @Test
     void emitTimerSpan_createsInternalSpanWithFireAt() {
-        TracingHelper.emitTimerSpan("MyOrchestration", "instance-1", 5, "2026-01-01T00:00:00Z");
+        TracingHelper.emitTimerSpan("MyOrchestration", "instance-1", 5, "2026-01-01T00:00:00Z", null);
 
         List<SpanData> spans = spanExporter.getFinishedSpanItems();
         assertEquals(1, spans.size());

samples/README.md

@@ -44,7 +44,7 @@ The `TracingPattern` sample demonstrates the **Fan-Out/Fan-In** pattern with dis
 1. Configures OpenTelemetry with an OTLP exporter pointing to Jaeger
 2. Connects a worker and client to the DTS emulator using a connection string
 3. Creates a parent span (`create_orchestration:FanOutFanIn`) and schedules an orchestration
-4. The orchestration fans out 5 parallel `GetWeather` activities (Seattle, Tokyo, London, Paris, Sydney), fans in the results, then calls `CreateSummary` to aggregate
+4. The orchestration waits on a 1-second **durable timer**, then fans out 5 parallel `GetWeather` activities (Seattle, Tokyo, London, Paris, Sydney), fans in the results, then calls `CreateSummary` to aggregate
 5. The SDK automatically propagates trace context through the full execution chain
 
 ## Screenshots
@@ -60,22 +60,23 @@ Shows the trace from `durabletask-java-tracing-sample` service with spans coveri
 Full span hierarchy showing the fan-out/fan-in pattern with paired Client+Server spans (matching .NET SDK):
 - `create_orchestration:FanOutFanIn` (root, internal)
   - `orchestration:FanOutFanIn` (server — orchestration execution)
+    - `orchestration:FanOutFanIn:timer` (internal — durable timer wait)
     - `activity:GetWeather` ×5 (client — scheduling) → `activity:GetWeather` ×5 (server — execution)
     - `activity:CreateSummary` (client) → `activity:CreateSummary` (server)
 
-14 spans total, Depth 3 — aligned with the .NET SDK trace structure.
+15 spans total, Depth 3 — aligned with the .NET SDK trace structure.
 
 ![Jaeger trace detail](images/jaeger-full-trace-detail.png)
 
-### Jaeger — Span Attributes
+### Jaeger — Span Attributes (Timer)
 
-Activity span showing attributes aligned with the .NET SDK schema:
-- `durabletask.type=activity`
-- `durabletask.task.name=GetWeather`
+Timer span showing attributes aligned with the .NET SDK schema:
+- `durabletask.type=timer`
+- `durabletask.task.name=FanOutFanIn`
+- `durabletask.fire_at=2026-03-03T21:13:15.142Z`
 - `durabletask.task.instance_id=<orchestrationId>`
-- `durabletask.task.task_id=0`
 - `otel.scope.name=Microsoft.DurableTask`
-- `span.kind=server`
+- `span.kind=internal`
 
 ![Jaeger span detail](images/jaeger-span-detail.png)
 

samples/images/jaeger-full-trace-detail.png

@@ -95,6 +95,9 @@ public static void main(String[] args) throws IOException, InterruptedException,
                     @Override
                     public TaskOrchestration create() {
                         return ctx -> {
+                            // Timer: wait briefly (demonstrates timer span)
+                            ctx.createTimer(Duration.ofSeconds(1)).await();
+
                             // Fan-out: schedule multiple parallel activities
                             List<Task<String>> parallelTasks = new java.util.ArrayList<>();
                             String[] cities = {"Seattle", "Tokyo", "London", "Paris", "Sydney"};