Merge branch 'main' into stevosyan/extended-sessions-for-orchestrations-isolated

Author: Sophia Tevosyan

.gitignore

@@ -348,3 +348,6 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+# Rider (cross platform .NET/C# tools) working folder
+.idea/

CHANGELOG.md

@@ -1,15 +1,15 @@
 # Changelog
 
-## (Unreleased)
-
-- Expose gRPC retry options in Azure Managed extensions ([#447](https://github.com/microsoft/durabletask-dotnet/pull/447))
+## v1.13.0
+- Add orchestration execution tracing ([#441](https://github.com/microsoft/durabletask-dotnet/pull/441))
 
 ## v1.12.0
 
 - Activity tag support ([#426](https://github.com/microsoft/durabletask-dotnet/pull/426))
 - Adding Analyzer to build and release ([#444](https://github.com/microsoft/durabletask-dotnet/pull/444))
 - Add ability to filter orchestrations at worker ([#443](https://github.com/microsoft/durabletask-dotnet/pull/443))
 - Removing breaking change for TaskOptions ([#446](https://github.com/microsoft/durabletask-dotnet/pull/446))
+- Expose gRPC retry options in Azure Managed extensions ([#447](https://github.com/microsoft/durabletask-dotnet/pull/447))
 
 ## v1.11.0
 

src/Analyzers/AnalyzerReleases.Shipped.md

@@ -7,16 +7,16 @@
 
 Rule ID | Category | Severity | Notes
 --------|----------|----------|-------
-DURABLE0001 | Orchestration | Warning | DateTimeOrchestrationAnalyzer
-DURABLE0002 | Orchestration | Warning | GuidOrchestrationAnalyzer
-DURABLE0003 | Orchestration | Warning | DelayOrchestrationAnalyzer
-DURABLE0004 | Orchestration | Warning | ThreadTaskOrchestrationAnalyzer
-DURABLE0005 | Orchestration | Warning | IOOrchestrationAnalyzer
-DURABLE0006 | Orchestration | Warning | EnvironmentOrchestrationAnalyzer
-DURABLE0007 | Orchestration | Warning | CancellationTokenOrchestrationAnalyzer
-DURABLE0008 | Orchestration | Warning | OtherBindingsOrchestrationAnalyzer
-DURABLE1001 | Attribute Binding | Error | OrchestrationTriggerBindingAnalyzer
-DURABLE1002 | Attribute Binding | Error | DurableClientBindingAnalyzer
-DURABLE1003 | Attribute Binding | Error | EntityTriggerBindingAnalyzer
-DURABLE2001 | Activity | Warning | MatchingInputOutputTypeActivityAnalyzer
-DURABLE2002 | Activity | Warning | MatchingInputOutputTypeActivityAnalyzer
+DURABLE0001 | Orchestration | Warning | **DateTimeOrchestrationAnalyzer**: Warns when non-deterministic DateTime properties like DateTime.Now, DateTime.UtcNow, or DateTime.Today are used in orchestration methods. Use context.CurrentUtcDateTime instead to ensure deterministic replay and to follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp).
+DURABLE0002 | Orchestration | Warning | **GuidOrchestrationAnalyzer**: Warns when Guid.NewGuid() is used in an orchestration method. This can break determinism. Please use context.NewGuid() for orchestration-safe GUID generation to follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp).
+DURABLE0003 | Orchestration | Warning | **DelayOrchestrationAnalyzer**: Warns when Task.Delay or Thread.Sleep are used in orchestrations. These APIs are non-deterministic. Please use context.CreateTimer for delays instead to follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp).
+DURABLE0004 | Orchestration | Warning | **ThreadTaskOrchestrationAnalyzer**: Warns on usage of non-deterministic thread and task APIs like Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew in orchestrations. Orchestrations must not use parallelism APIs as these break replay and don't follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp).
+DURABLE0005 | Orchestration | Warning | **IOOrchestrationAnalyzer**: Warns when I/O APIs (e.g., HttpClient, Azure Storage clients) are used directly in orchestrations. I/O calls are not replay-safe and should be invoked via activities to follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp)
+DURABLE0006 | Orchestration | Warning | **EnvironmentOrchestrationAnalyzer**: Warns on usage of System.Environment APIs (e.g., GetEnvironmentVariable) in orchestrations. Reading environment variables can introduce non-determinism. Please follow [orchestrator code constraints](https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-code-constraints?tabs=csharp)
+DURABLE0007 | Orchestration | Warning | **CancellationTokenOrchestrationAnalyzer**: Warns when CancellationToken parameters are used in orchestration function signatures. Orchestration methods should not accept cancellation tokens directly.
+DURABLE0008 | Orchestration | Warning | **OtherBindingsOrchestrationAnalyzer**: Warns when orchestration methods have input parameters with bindings other than [OrchestrationTrigger] (e.g., [EntityTrigger], [DurableClient]). Orchestrations must only use [OrchestrationTrigger] bindings.
+DURABLE1001 | Attribute Binding | Error | **OrchestrationTriggerBindingAnalyzer**: Ensures [OrchestrationTrigger] is only applied to parameters of type TaskOrchestrationContext.
+DURABLE1002 | Attribute Binding | Error | **DurableClientBindingAnalyzer**: Ensures [DurableClient] is only applied to parameters of type DurableTaskClient.
+DURABLE1003 | Attribute Binding | Error | **EntityTriggerBindingAnalyzer**: Ensures [EntityTrigger] is only applied to parameters of type TaskEntityDispatcher.
+DURABLE2001 | Activity | Warning | **MatchingInputOutputTypeActivityAnalyzer**: Warns when the input type passed to an activity invocation does not match the activity's definition.
+DURABLE2002 | Activity | Warning | **MatchingInputOutputTypeActivityAnalyzer**: Warns when the output type expected from an activity invocation does not match the activity's definition.

src/Client/AzureManaged/DurableTaskSchedulerClientOptions.cs

@@ -173,7 +173,7 @@ this.Credential is not null
         switch (authType.ToLowerInvariant())
         {
             case "defaultazure":
-                return new DefaultAzureCredential();
+                return new DefaultAzureCredential(); // CodeQL [SM05137] Use DefaultAzureCredential explicitly for local development and is decided by the user
             case "managedidentity":
                 return new ManagedIdentityCredential(connectionString.ClientId);
             case "workloadidentity":

src/Client/Grpc/GrpcDurableTaskClient.cs

@@ -5,6 +5,7 @@
 using System.Text;
 using Google.Protobuf.WellKnownTypes;
 using Microsoft.DurableTask.Client.Entities;
+using Microsoft.DurableTask.Tracing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
@@ -107,24 +108,6 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(
             }
         }
 
-        if (Activity.Current?.Id != null || Activity.Current?.TraceStateString != null)
-        {
-            if (request.ParentTraceContext == null)
-            {
-                request.ParentTraceContext = new P.TraceContext();
-            }
-
-            if (Activity.Current?.Id != null)
-            {
-                request.ParentTraceContext.TraceParent = Activity.Current?.Id;
-            }
-
-            if (Activity.Current?.TraceStateString != null)
-            {
-                request.ParentTraceContext.TraceState = Activity.Current?.TraceStateString;
-            }
-        }
-
         DateTimeOffset? startAt = options?.StartAt;
         this.logger.SchedulingOrchestration(
             request.InstanceId,
@@ -138,6 +121,8 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(
             request.ScheduledStartTimestamp = Timestamp.FromDateTimeOffset(startAt.Value.ToUniversalTime());
         }
 
+        using Activity? newActivity = TraceHelper.StartActivityForNewOrchestration(request);
+
         P.CreateInstanceResponse? result = await this.sidecarClient.StartInstanceAsync(
             request, cancellationToken: cancellation);
         return result.InstanceId;
@@ -159,6 +144,8 @@ public override async Task RaiseEventAsync(
             Input = this.DataConverter.Serialize(eventPayload),
         };
 
+        using Activity? traceActivity = TraceHelper.StartActivityForNewEventRaisedFromClient(request, instanceId);
+
         await this.sidecarClient.RaiseEventAsync(request, cancellationToken: cancellation);
     }
 

src/Grpc/versions.txt

@@ -1,2 +1,2 @@
-# The following files were downloaded from branch stevosyan/extended-sessions-for-orchestrations-isolated at 2025-08-01 23:50:40 UTC
+# The following files were downloaded from branch stevosyan/extended-sessions-for-orchestrations-isolated at 2025-08-21 02:06:15 UTC
 https://raw.githubusercontent.com/microsoft/durabletask-protobuf/930a06ef7df4f3156fdaa619e8e4d6439d43fcb5/protos/orchestrator_service.proto

src/Shared/Grpc/ProtoUtils.cs

@@ -3,6 +3,7 @@
 
 using System.Buffers;
 using System.Buffers.Text;
+using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Text;
 using DurableTask.Core;
@@ -15,6 +16,7 @@
 using Google.Protobuf.WellKnownTypes;
 using DTCore = DurableTask.Core;
 using P = Microsoft.DurableTask.Protobuf;
+using TraceHelper = Microsoft.DurableTask.Tracing.TraceHelper;
 
 namespace Microsoft.DurableTask;
 
@@ -268,29 +270,39 @@ internal static Timestamp ToTimestamp(this DateTime dateTime)
     /// Constructs a <see cref="P.OrchestratorResponse" />.
     /// </summary>
     /// <param name="instanceId">The orchestrator instance ID.</param>
+    /// <param name="executionId">The orchestrator execution ID.</param>
     /// <param name="customStatus">The orchestrator customer status or <c>null</c> if no custom status.</param>
     /// <param name="actions">The orchestrator actions.</param>
     /// <param name="completionToken">
     /// The completion token for the work item. It must be the exact same <see cref="P.WorkItem.CompletionToken" />
     /// value that was provided by the corresponding <see cref="P.WorkItem"/> that triggered the orchestrator execution.
     /// </param>
     /// <param name="entityConversionState">The entity conversion state, or null if no conversion is required.</param>
+    /// <param name="orchestrationActivity">The <see cref="Activity" /> that represents orchestration execution.</param>
     /// <param name="requiresHistory">Whether or not a history is required to complete the orchestration request and none was provided.</param>
     /// <returns>The orchestrator response.</returns>
     /// <exception cref="NotSupportedException">When an orchestrator action is unknown.</exception>
     internal static P.OrchestratorResponse ConstructOrchestratorResponse(
         string instanceId,
+        string executionId,
         string? customStatus,
         IEnumerable<OrchestratorAction>? actions,
         string completionToken,
         EntityConversionState? entityConversionState,
+        Activity? orchestrationActivity,
         bool requiresHistory = false)
     {
         var response = new P.OrchestratorResponse
         {
             InstanceId = instanceId,
             CustomStatus = customStatus,
             CompletionToken = completionToken,
+            OrchestrationTraceContext =
+                new()
+                {
+                    SpanID = orchestrationActivity?.SpanId.ToString(),
+                    SpanStartTime = orchestrationActivity?.StartTimeUtc.ToTimestamp(),
+                },
             RequiresHistory = requiresHistory,
         };
 
@@ -305,15 +317,34 @@ internal static P.OrchestratorResponse ConstructOrchestratorResponse(
         {
             var protoAction = new P.OrchestratorAction { Id = action.Id };
 
+            P.TraceContext? CreateTraceContext()
+            {
+                if (orchestrationActivity is null)
+                {
+                    return null;
+                }
+
+                ActivitySpanId clientSpanId = ActivitySpanId.CreateRandom();
+                ActivityContext clientActivityContext = new(orchestrationActivity.TraceId, clientSpanId, orchestrationActivity.ActivityTraceFlags, orchestrationActivity.TraceStateString);
+
+                return new P.TraceContext
+                {
+                    TraceParent = $"00-{clientActivityContext.TraceId}-{clientActivityContext.SpanId}-0{clientActivityContext.TraceFlags:d}",
+                    TraceState = clientActivityContext.TraceState,
+                };
+            }
+
             switch (action.OrchestratorActionType)
             {
                 case OrchestratorActionType.ScheduleOrchestrator:
                     var scheduleTaskAction = (ScheduleTaskOrchestratorAction)action;
+
                     protoAction.ScheduleTask = new P.ScheduleTaskAction
                     {
                         Name = scheduleTaskAction.Name,
                         Version = scheduleTaskAction.Version,
                         Input = scheduleTaskAction.Input,
+                        ParentTraceContext = CreateTraceContext(),
                     };
 
                     if (scheduleTaskAction.Tags != null)
@@ -333,6 +364,7 @@ internal static P.OrchestratorResponse ConstructOrchestratorResponse(
                         InstanceId = subOrchestrationAction.InstanceId,
                         Name = subOrchestrationAction.Name,
                         Version = subOrchestrationAction.Version,
+                        ParentTraceContext = CreateTraceContext(),
                     };
                     break;
                 case OrchestratorActionType.CreateTimer:
@@ -387,6 +419,12 @@ internal static P.OrchestratorResponse ConstructOrchestratorResponse(
                             Name = sendEventAction.EventName,
                             Data = sendEventAction.EventData,
                         };
+
+                        // Distributed Tracing: start a new trace activity derived from the orchestration
+                        // for an EventRaisedEvent (external event)
+                        using Activity? traceActivity = TraceHelper.StartTraceActivityForEventRaisedFromWorker(sendEventAction, instanceId, executionId);
+
+                        traceActivity?.Stop();
                     }
 
                     break;

src/Shared/Grpc/Tracing/DiagnosticActivityExtensions.cs

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics;
+using System.Linq.Expressions;
+using System.Reflection;
+
+// NOTE: Modified from https://github.com/Azure/durabletask/blob/main/src/DurableTask.Core/Tracing/DiagnosticActivityExtensions.cs
+namespace Microsoft.DurableTask.Tracing;
+
+/// <summary>
+/// Replica from System.Diagnostics.DiagnosticSource >= 6.0.0.
+/// </summary>
+enum ActivityStatusCode
+{
+    /// <summary>
+    /// The default value indicating the status code is not initialized.
+    /// </summary>
+    Unset = 0,
+
+    /// <summary>
+    /// Indicates the operation has been validated and completed successfully.
+    /// </summary>
+    Ok = 1,
+
+    /// <summary>
+    /// Indicates an error was encountered during the operation.
+    /// </summary>
+    Error = 2,
+}
+
+/// <summary>
+/// Extensions for <see cref="Activity"/>.
+/// </summary>
+static class DiagnosticActivityExtensions
+{
+    static readonly Action<Activity, string> SetSpanIdMethod;
+    static readonly Action<Activity, ActivityStatusCode, string> SetStatusMethod;
+
+    static DiagnosticActivityExtensions()
+    {
+        BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Instance;
+        SetSpanIdMethod = (typeof(Activity).GetField("_spanId", flags)
+                          ?? throw new InvalidOperationException("The field Activity._spanId was not found."))
+                            .CreateSetter<Activity, string>();
+        SetStatusMethod = CreateSetStatus();
+    }
+
+    /// <summary>
+    /// Explicitly sets the span ID for the given activity.
+    /// </summary>
+    /// <param name="activity">The activity on which to set the span ID.</param>
+    /// <param name="spanId">The span ID to set.</param>
+    public static void SetSpanId(this Activity activity, string spanId)
+        => SetSpanIdMethod(activity, spanId);
+
+    /// <summary>
+    /// Explicitly sets the status code and description for the given activity.
+    /// </summary>
+    /// <param name="activity">The activity on which to set the span ID.</param>
+    /// <param name="status">The status to set.</param>
+    /// <param name="description">The description to set.</param>
+    public static void SetStatus(this Activity activity, ActivityStatusCode status, string description)
+        => SetStatusMethod(activity, status, description);
+
+    static Action<Activity, ActivityStatusCode, string> CreateSetStatus()
+    {
+        MethodInfo? method = typeof(Activity).GetMethod("SetStatus");
+
+        if (method is null)
+        {
+            return (activity, status, description) =>
+            {
+#pragma warning disable CA1510
+                if (activity is null)
+                {
+                    throw new ArgumentNullException(nameof(activity));
+                }
+#pragma warning restore CA1510
+
+                string? str = status switch
+                {
+                    ActivityStatusCode.Unset => "UNSET",
+                    ActivityStatusCode.Ok => "OK",
+                    ActivityStatusCode.Error => "ERROR",
+                    _ => null,
+                };
+
+                activity.SetTag("otel.status_code", str);
+                activity.SetTag("otel.status_description", description);
+            };
+        }
+
+        /*
+            building expression tree to effectively perform:
+            (activity, status, description) => activity.SetStatus((ActivityStatusCode)(int)status, description);
+        */
+
+        ParameterExpression targetExp = Expression.Parameter(typeof(Activity), "target");
+        ParameterExpression status = Expression.Parameter(typeof(ActivityStatusCode), "status");
+        ParameterExpression description = Expression.Parameter(typeof(string), "description");
+        UnaryExpression convert = Expression.Convert(status, typeof(int));
+        convert = Expression.Convert(convert, method.GetParameters().First().ParameterType);
+        MethodCallExpression callExp = Expression.Call(targetExp, method, convert, description);
+        return Expression.Lambda<Action<Activity, ActivityStatusCode, string>>(callExp, targetExp, status, description)
+            .Compile();
+    }
+}