Implement tracing support for Durable Task SDKs

- Add trace-helper functions to manage OpenTelemetry spans for orchestrations, activities, and timers.
- Introduce methods to start spans for new orchestrations, orchestration executions, task scheduling, and event handling.
- Implement span error handling and status management.
- Create protobuf messages for orchestration trace context.
- Add tests to validate tracing functionality, including span creation, attribute verification, and error handling.

Author: torosent

package-lock.json

@@ -42,11 +42,21 @@
     "google-protobuf": "^3.21.2"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.25.0",
     "@types/google-protobuf": "^3.15.6",
     "@types/jest": "^29.5.1",
     "@types/node": "^18.16.1",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.0.4"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   }
-}
+}

packages/durabletask-js/package.json

@@ -29,6 +29,13 @@ import { Logger, ConsoleLogger } from "../types/logger.type";
 import { StartOrchestrationOptions } from "../task/options";
 import { mapToRecord } from "../utils/tags.util";
 import { populateTagsMap } from "../utils/pb-helper.util";
+import {
+  startSpanForNewOrchestration,
+  startSpanForEventRaisedFromClient,
+  setSpanError,
+  setSpanOk,
+  endSpan,
+} from "../tracing";
 
 // Re-export MetadataGenerator for backward compatibility
 export { MetadataGenerator } from "../utils/grpc-helper.util";
@@ -218,15 +225,26 @@ export class TaskHubGrpcClient {
 
     populateTagsMap(req.getTagsMap(), tags);
 
+    // Create a tracing span for the new orchestration (if OTEL is available)
+    const span = startSpanForNewOrchestration(req);
+
     this._logger.info(`Starting new ${name} instance with ID = ${req.getInstanceid()}${effectiveVersion ? ` (version: ${effectiveVersion})` : ""}`);
 
-    const res = await callWithMetadata<pb.CreateInstanceRequest, pb.CreateInstanceResponse>(
-      this._stub.startInstance.bind(this._stub),
-      req,
-      this._metadataGenerator,
-    );
+    try {
+      const res = await callWithMetadata<pb.CreateInstanceRequest, pb.CreateInstanceResponse>(
+        this._stub.startInstance.bind(this._stub),
+        req,
+        this._metadataGenerator,
+      );
 
-    return res.getInstanceid();
+      setSpanOk(span);
+      return res.getInstanceid();
+    } catch (e: any) {
+      setSpanError(span, e);
+      throw e;
+    } finally {
+      endSpan(span);
+    }
   }
 
   /**
@@ -376,13 +394,25 @@ export class TaskHubGrpcClient {
 
     req.setInput(i);
 
+    // Create a tracing span for the raised event (if OTEL is available)
+    const span = startSpanForEventRaisedFromClient(eventName, instanceId);
+
     this._logger.info(`Raising event '${eventName}' for instance '${instanceId}'`);
 
-    await callWithMetadata<pb.RaiseEventRequest, pb.RaiseEventResponse>(
-      this._stub.raiseEvent.bind(this._stub),
-      req,
-      this._metadataGenerator,
-    );
+    try {
+      await callWithMetadata<pb.RaiseEventRequest, pb.RaiseEventResponse>(
+        this._stub.raiseEvent.bind(this._stub),
+        req,
+        this._metadataGenerator,
+      );
+
+      setSpanOk(span);
+    } catch (e: any) {
+      setSpanError(span, e);
+      throw e;
+    } finally {
+      endSpan(span);
+    }
   }
 
   /**

packages/durabletask-js/src/client/client.ts

@@ -92,3 +92,16 @@ export { ReplaySafeLogger, ReplayContext } from "./types/replay-safe-logger";
 
 // Versioning utilities
 export { compareVersions } from "./utils/versioning.util";
+
+// Distributed Tracing (OpenTelemetry)
+export {
+  TRACER_NAME,
+  DurableTaskAttributes,
+  TaskType,
+  createSpanName,
+  createTimerSpanName,
+  getOtelApi,
+  getTracer,
+  OrchestrationSpanInfo,
+  startSpanForEventRaisedFromClient,
+} from "./tracing";

packages/durabletask-js/src/index.ts

@@ -89,6 +89,10 @@ export interface ExecutionStartedEvent extends HistoryEventBase {
   parentInstance?: ParentInstanceInfo;
   scheduledStartTimestamp?: Date;
   tags?: Record<string, string>;
+  /** The parent trace context for distributed tracing (W3C Trace Context). */
+  parentTraceContext?: TraceContext;
+  /** The span ID assigned to this orchestration execution for replay continuity. */
+  orchestrationSpanId?: string;
 }
 
 /**
@@ -151,6 +155,8 @@ export interface TaskScheduledEvent extends HistoryEventBase {
   version?: string;
   input?: string;
   tags?: Record<string, string>;
+  /** The parent trace context for distributed tracing (W3C Trace Context). */
+  parentTraceContext?: TraceContext;
 }
 
 /**
@@ -181,6 +187,8 @@ export interface SubOrchestrationInstanceCreatedEvent extends HistoryEventBase {
   instanceId?: string;
   input?: string;
   tags?: Record<string, string>;
+  /** The parent trace context for distributed tracing (W3C Trace Context). */
+  parentTraceContext?: TraceContext;
 }
 
 /**