Add entity operation Client/Server trace spans

Add Client spans (emitted during orchestration replay) and Server spans
(emitted during entity execution) for entity operations. This creates
proper Client->Server span nesting in trace viewers, matching the
existing pattern used by activities and sub-orchestrations.

- TraceHelper: Add EmitTraceActivityForEntityOperationCompleted/Failed
  and StartTraceActivityForSchedulingEntityOperation (Client spans)
- Processor: Handle EntityOperationCompleted/Failed in newEvents switch
  with GetEntityOperationCalledEvent helper for request correlation
- Include before/after screenshots showing entity traces in Aspire

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

Author: cgillum

after-entity-traces.png

@@ -254,6 +254,51 @@ public static void EmitTraceActivityForTaskFailed(
         activity?.Dispose();
     }
 
+    /// <summary>
+    /// Emits a new trace activity for an entity operation that successfully completes.
+    /// </summary>
+    /// <param name="instanceId">The ID of the associated orchestration.</param>
+    /// <param name="historyEvent">The associated <see cref="P.HistoryEvent" />.</param>
+    /// <param name="calledEvent">The associated <see cref="P.EntityOperationCalledEvent"/>.</param>
+    public static void EmitTraceActivityForEntityOperationCompleted(
+        string? instanceId,
+        P.HistoryEvent? historyEvent,
+        P.EntityOperationCalledEvent? calledEvent)
+    {
+        Activity? activity = StartTraceActivityForSchedulingEntityOperation(instanceId, historyEvent, calledEvent);
+
+        activity?.Dispose();
+    }
+
+    /// <summary>
+    /// Emits a new trace activity for an entity operation that fails.
+    /// </summary>
+    /// <param name="instanceId">The ID of the associated orchestration.</param>
+    /// <param name="historyEvent">The associated <see cref="P.HistoryEvent" />.</param>
+    /// <param name="calledEvent">The associated <see cref="P.EntityOperationCalledEvent"/>.</param>
+    /// <param name="failedEvent">The associated <see cref="P.EntityOperationFailedEvent"/>.</param>
+    public static void EmitTraceActivityForEntityOperationFailed(
+        string? instanceId,
+        P.HistoryEvent? historyEvent,
+        P.EntityOperationCalledEvent? calledEvent,
+        P.EntityOperationFailedEvent? failedEvent)
+    {
+        Activity? activity = StartTraceActivityForSchedulingEntityOperation(instanceId, historyEvent, calledEvent);
+
+        if (activity is null)
+        {
+            return;
+        }
+
+        if (failedEvent != null)
+        {
+            string statusDescription = failedEvent.FailureDetails?.ErrorMessage ?? "Unspecified entity operation failure";
+            activity.SetStatus(ActivityStatusCode.Error, statusDescription);
+        }
+
+        activity.Dispose();
+    }
+
     /// <summary>
     /// Emits a new trace activity for sub-orchestration execution when the sub-orchestration
     /// completes successfully.
@@ -461,6 +506,65 @@ static string CreateSpanName(string spanDescription, string? taskName, string? t
         return newActivity;
     }
 
+    /// <summary>
+    /// Starts a new trace activity for scheduling an entity operation. Represents the time between
+    /// enqueuing the entity operation message and it completing.
+    /// </summary>
+    /// <param name="instanceId">The ID of the associated orchestration.</param>
+    /// <param name="historyEvent">The associated <see cref="P.HistoryEvent" />.</param>
+    /// <param name="calledEvent">The associated <see cref="P.EntityOperationCalledEvent"/>.</param>
+    /// <returns>
+    /// Returns a newly started <see cref="Activity"/> with entity operation metadata.
+    /// </returns>
+    static Activity? StartTraceActivityForSchedulingEntityOperation(
+        string? instanceId,
+        P.HistoryEvent? historyEvent,
+        P.EntityOperationCalledEvent? calledEvent)
+    {
+        if (calledEvent == null)
+        {
+            return null;
+        }
+
+        string entityName = historyEvent?.EntityOperationCalled?.TargetInstanceId ?? string.Empty;
+        string spanName = string.IsNullOrEmpty(calledEvent.Operation)
+            ? $"{TraceActivityConstants.EntityOperation}:{entityName}"
+            : $"{TraceActivityConstants.EntityOperation}:{entityName}:{calledEvent.Operation}";
+
+        Activity? newActivity = ActivityTraceSource.StartActivity(
+            spanName,
+            kind: ActivityKind.Client,
+            startTime: historyEvent?.Timestamp?.ToDateTimeOffset() ?? default,
+            parentContext: Activity.Current?.Context ?? default);
+
+        if (newActivity == null)
+        {
+            return null;
+        }
+
+        if (calledEvent.ParentTraceContext != null)
+        {
+            if (ActivityContext.TryParse(
+                    calledEvent.ParentTraceContext.TraceParent,
+                    calledEvent.ParentTraceContext?.TraceState,
+                    out ActivityContext parentContext))
+            {
+                newActivity.SetSpanId(parentContext.SpanId.ToString());
+            }
+        }
+
+        newActivity.AddTag(Schema.Task.Type, TraceActivityConstants.EntityOperation);
+        newActivity.AddTag(Schema.Task.Name, entityName);
+        newActivity.AddTag(Schema.Task.InstanceId, instanceId);
+
+        if (!string.IsNullOrEmpty(calledEvent.Operation))
+        {
+            newActivity.AddTag("durabletask.entity.operation", calledEvent.Operation);
+        }
+
+        return newActivity;
+    }
+
     /// <summary>
     /// Starts a new trace activity for sub-orchestrations. Represents the time between enqueuing
     /// the sub-orchestration message and it completing.

before-entity-traces.png

@@ -502,6 +502,14 @@ async Task OnRunOrchestratorAsync(
                     return taskScheduledEvent;
                 }
 
+                P.HistoryEvent? GetEntityOperationCalledEvent(string requestId)
+                {
+                    return request
+                        .PastEvents
+                        .Where(x => x.EventTypeCase == P.HistoryEvent.EventTypeOneofCase.EntityOperationCalled)
+                        .FirstOrDefault(x => x.EntityOperationCalled.RequestId == requestId);
+                }
+
                 foreach (var newEvent in request.NewEvents)
                 {
                     switch (newEvent.EventTypeCase)
@@ -565,6 +573,33 @@ async Task OnRunOrchestratorAsync(
                                 newEvent.Timestamp.ToDateTime(),
                                 newEvent.TimerFired);
                             break;
+
+                        case P.HistoryEvent.EventTypeOneofCase.EntityOperationCompleted:
+                            {
+                                P.HistoryEvent? entityCalledEvent =
+                                    GetEntityOperationCalledEvent(
+                                        newEvent.EntityOperationCompleted.RequestId);
+
+                                TraceHelper.EmitTraceActivityForEntityOperationCompleted(
+                                    request.InstanceId,
+                                    entityCalledEvent,
+                                    entityCalledEvent?.EntityOperationCalled);
+                                break;
+                            }
+
+                        case P.HistoryEvent.EventTypeOneofCase.EntityOperationFailed:
+                            {
+                                P.HistoryEvent? entityCalledEvent =
+                                    GetEntityOperationCalledEvent(
+                                        newEvent.EntityOperationFailed.RequestId);
+
+                                TraceHelper.EmitTraceActivityForEntityOperationFailed(
+                                    request.InstanceId,
+                                    entityCalledEvent,
+                                    entityCalledEvent?.EntityOperationCalled,
+                                    newEvent.EntityOperationFailed);
+                                break;
+                            }
                     }
                 }
             }