feat: align tracing attributes with .NET SDK conventions#126
Open
feat: align tracing attributes with .NET SDK conventions#126
Conversation
- Add execution_id attribute on orchestration creation spans - Add version attribute on activity execution spans (name + version) - Add name and instance_id attributes on timer spans - Add durabletask.task.status attribute on orchestration completion - Pass instanceId through processActionsForTracing for timer enrichment - Add setOrchestrationStatusFromActions helper with status string mapping - Add 13 new unit tests covering all attribute additions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Aligns the JS SDK’s OpenTelemetry spans/attributes with DurableTask .NET conventions to improve cross-SDK trace parity and observability.
Changes:
- Add new tracing attributes: orchestration
execution_id, activityversion, timertask.name/task.instance_id, and orchestration completiondurabletask.task.status. - Wire orchestration
instanceIdinto tracing action processing so timer spans can be enriched. - Extend unit tests and update the Azure-managed distributed tracing sample + changelog.
Reviewed changes
Copilot reviewed 6 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/durabletask-js/src/tracing/trace-helper.ts | Adds execution_id, activity version, timer enrichment, and orchestration status helper; plumbs instanceId into action tracing. |
| packages/durabletask-js/src/tracing/index.ts | Re-exports the new orchestration status helper. |
| packages/durabletask-js/src/worker/task-hub-grpc-worker.ts | Passes instanceId to tracing action processing and sets orchestration completion status on spans. |
| packages/durabletask-js/test/tracing.spec.ts | Adds unit tests covering the new attributes and status mapping. |
| examples/azure-managed/distributed-tracing/index.ts | Updates sample OTel bootstrap/resource initialization and span processor wiring. |
| CHANGELOG.md | Adds an “Upcoming” entry for the tracing alignment. |
| doc/images/tracing/jaeger-trace-list.png | Adds/updates tracing screenshot asset. |
…etion Implement the retroactive span emission pattern matching the .NET SDK's EmitTraceActivityForTaskCompleted/Failed and EmitTraceActivityForTimer: - emitRetroactiveActivityClientSpan(): Creates Client spans at activity completion/failure time with historical startTime from TaskScheduled event - emitRetroactiveSubOrchClientSpan(): Same for sub-orchestration completions - emitSpanForTimer(): Now accepts optional startTime parameter for creation- to-fired duration coverage - processNewEventsForTracing(): Pre-processes new history events (before orchestrator executor runs) to emit retroactive spans, matching .NET's worker-level tracing pattern This addresses the architectural gap where JS emitted scheduling spans only at scheduling time (proactive), while .NET and Java emit retroactive spans at completion time with accurate scheduling-to-completion duration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…map lookup - Extract common emitRetroactiveClientSpan() helper to eliminate duplication between emitRetroactiveActivityClientSpan and emitRetroactiveSubOrchClientSpan - Replace orchestrationStatusToString switch/case with object lookup map - Hoist duplicate orchName computation to shared scope in worker Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Set durabletask.task.status in failure path too (not just success path) - Extract executionId to local variable instead of double getExecutionid() call - Use traceExporter option directly instead of spanProcessors with 'as any' cast - Add PR link (#126) to CHANGELOG entries per repo convention Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… spans - Remove timer span emission from processActionsForTracing (timer spans are now emitted only retroactively from TimerFired events via processNewEventsForTracing, matching .NET/Java behavior) - Add instance_id attribute to event spans from worker (emitSpanForEventSent), matching .NET's StartTraceActivityForEventRaisedFromWorker - Update tests to verify timer spans are no longer created proactively Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…n_id - setOrchestrationStatusFromActions now sets ERROR span status when orchestration completes with FAILED (matching .NET behavior where span gets ActivityStatusCode.Error with result message). Previously JS always set OK on success path even when executor reported FAILED. - Removed separate setSpanOk call; status is now fully determined by the completion action status. - Added execution_id attribute to event spans from worker, matching .NET's StartTraceActivityForEventRaisedFromWorker. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add 2-second timer to sequenceOrchestrator to showcase retroactive timer spans - Capture fresh screenshots showing timer span with 2.01s duration and all attributes (fire_at, instance_id, name, task_id, type=timer) - Remove old retroactive-client-span screenshot, add timer-span screenshot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…screenshots Rewrote the distributed-tracing sample to match the Java SDK's tracing sample (FanOutFanIn): 1s timer → 5× parallel GetWeather → CreateSummary. This produces a trace structure directly comparable to the Java PR screenshots. Updated Jaeger screenshots to match the Java PR pattern: - jaeger-trace-list.png: Trace search showing FanOutFanIn trace (25 spans) - jaeger-full-trace-detail.png: Full trace detail with span hierarchy - jaeger-span-detail.png: Span detail showing attributes (aligned with .NET) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
YunchuWang
reviewed
Mar 4, 2026
YunchuWang
reviewed
Mar 4, 2026
…ations Address review feedback from @YunchuWang: processActionsForTracing was creating CLIENT spans at scheduling time, AND processNewEventsForTracing was creating retroactive CLIENT spans at completion time — resulting in duplicate CLIENT spans per activity/sub-orchestration. .NET never creates actual CLIENT spans for scheduling. Instead, it generates a random span ID (ActivitySpanId.CreateRandom()) and constructs a TraceContext directly, without creating a span. Changed to match .NET exactly: - Replaced startSpanForSchedulingTask() with injectTraceContextForSchedulingTask() which generates a random span ID and injects trace context without creating a span - Same for startSpanForSchedulingSubOrchestration() → injectTraceContextForSchedulingSubOrchestration() - Only the retroactive CLIENT spans (from processNewEventsForTracing) now exist Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Address review feedback from @YunchuWang: in the catch block, setSpanError sets the span with the actual exception message, but setOrchestrationStatusFromActions would then overwrite it with a generic 'Orchestration failed' because the synthesized action has undefined result. Now the catch path sets the status attribute directly without calling setOrchestrationStatusFromActions, preserving the specific error message. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What changed?
execution_idon creation spans,versionon activity execution spans,name/instance_idon timer spans, anddurabletask.task.statuson orchestration completionWhy is this change needed?
The JS SDK's tracing was missing several attributes present in the .NET SDK and used a proactive-only span emission model (point-in-time spans at scheduling). Both .NET and Java SDKs emit retroactive spans at completion time with historical timestamps, providing accurate scheduling-to-completion duration visibility in trace tools like Jaeger. This PR closes the gap.
Issues / work items
Project checklist
CHANGELOG.mdAI-assisted code disclosure (required)
Was an AI tool used? (select one)
If AI was used:
packages/durabletask-js/src/tracing/trace-helper.ts� new functions:emitRetroactiveActivityClientSpan,emitRetroactiveSubOrchClientSpan,processNewEventsForTracing,setOrchestrationStatusFromActions,orchestrationStatusToString; updatedemitSpanForTimerwithstartTimeparameterpackages/durabletask-js/src/tracing/index.ts� new exportspackages/durabletask-js/src/worker/task-hub-grpc-worker.ts� integratedprocessNewEventsForTracingandsetOrchestrationStatusFromActionspackages/durabletask-js/test/tracing.spec.ts� 27 new unit testsexamples/azure-managed/distributed-tracing/index.ts� fixed OTel Resource import compatibilityCHANGELOG.md� updatedAI verification (required if AI was used):
Testing
Automated tests
Manual validation (only if runtime/behavior changed)
docker compose up -dexamples/azure-managed/distributed-tracingsample � both orchestrations completed successfullyinstance_idattribute and historical start timesdurabletask.task.status=Completedon orchestration spansDetails
1. Attribute Alignment
create_orchestrationdurabletask.task.execution_idactivity(Server)durabletask.task.versiontimer(Internal)durabletask.task.nametimer(Internal)durabletask.task.instance_idorchestration(Server)durabletask.task.status2. Retroactive Span Emission Model
Previously, the JS SDK only emitted activity/sub-orchestration Client spans proactively at scheduling time (point-in-time spans with zero duration). The .NET and Java SDKs emit these retroactively at completion time with historical scheduling timestamps.
This PR adds retroactive span emission matching the .NET pattern (
EmitTraceActivityForTaskCompleted/Failed,EmitTraceActivityForTimer):activity:{name}(Client)orchestration:{name}(Client)orchestration:{name}:timer(Internal)Proactive Client spans are preserved for trace context injection (Server span parents). Retroactive spans add timeline/duration coverage.
Span Types Summary
Producercreate_orchestration:{name}[@({version})]Serverorchestration:{name}[@({version})]Clientactivity:{name}[@({version})]Clientactivity:{name}[@({version})]Serveractivity:{name}[@({version})]Internalorchestration:{orchName}:timerProducerorchestration_event:{eventName}Screenshots (Jaeger)
Jaeger — Trace search showing FanOutFanIn trace (25 spans):
Jaeger — Full trace detail with proper span durations (timer, parallel activities, aggregation):
Jaeger — Span detail showing attributes (aligned with .NET SDK schema):
Notes for reviewers
_executeOrchestratorInternal), matching the .NET worker patternSetSpanIdreflection hack), so retroactive Client spans get new span IDs rather than matching the original scheduling context � this is a known platform limitation shared with JavaSetSpanIdreflection hack. JS stores the original span ID asdurabletask.task.replay_span_idattribute for cross-replay correlation instead. This is not a fixable gap.