Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/concepts/activities.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,18 @@ public override async Task<OrderResult> RunTask(
> [!IMPORTANT]
> Do not include `TaskContext` or `CancellationToken` parameters in activity interface methods. Only JSON-serializable input and output types are allowed.

## Activity Start Times in History

`TaskCompletedEvent.StartedTime` and `TaskFailedEvent.StartedTime` record the worker's UTC time immediately before the dispatcher calls `TaskActivity.RunAsync`. This excludes queueing and middleware work before that call, but includes any input conversion, host invocation, and output conversion inside `RunAsync`. The scheduled event's `Timestamp` and the response event's `Timestamp` keep their existing meanings.

The value belongs to the invocation associated with that response's `TaskScheduledId`. Each retry scheduled by the orchestration has its own scheduled event. A redelivery of the same scheduled event captures a new start; abandoned invocations do not produce history entries. No separate start event is emitted, so this does not expose in-flight starts or a log of every execution attempt. Timestamps from different workers are subject to clock skew.

Start time is unknown (`null`, omitted from JSON) for older history, older workers, middleware that skips the activity invocation, and default completions synthesized without an activity result. Middleware that replaces a response after invoking the activity retains the observed start only when the replacement refers to the same scheduled event.

The Azure Storage provider preserves this metadata in activity response messages, History-table rows, and `GetOrchestrationHistoryAsync` JSON. Other providers and protocol-specific history mappings are not covered by this guarantee; they must preserve the new fields where they translate events. In particular, the Durable Functions protobuf history contract needs a separate update.

The existing Durable Functions JSON `GetStatusAsync(showHistory: true)` projection can retain the additive fields, but requires adoption of a Core package containing this change. Consumers must not substitute `ScheduledTime` when `StartedTime` is absent.

## Activity Best Practices

### 1. Keep Activities Focused
Expand Down
12 changes: 12 additions & 0 deletions src/DurableTask.Core/History/TaskCompletedEvent.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@

namespace DurableTask.Core.History
{
using System;
using System.Runtime.Serialization;

/// <summary>
Expand Down Expand Up @@ -50,5 +51,16 @@ public TaskCompletedEvent(int eventId, int taskScheduledId, string result)
/// </summary>
[DataMember]
public string Result { get; private set; }

/// <summary>
/// Gets or sets the UTC time at which the dispatcher invoked <see cref="TaskActivity.RunAsync"/>.
/// </summary>
/// <remarks>
/// This is the start of the invocation associated with this response, not the time the task was scheduled.
/// A redelivered task records only the invocation whose response is persisted. The value is <c>null</c>
/// for older history or when the dispatcher did not observe a matching activity invocation.
/// </remarks>
[DataMember(EmitDefaultValue = false)]
public DateTime? StartedTime { get; set; }
}
}
12 changes: 12 additions & 0 deletions src/DurableTask.Core/History/TaskFailedEvent.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
#nullable enable
namespace DurableTask.Core.History
{
using System;
using System.Runtime.Serialization;

/// <summary>
Expand Down Expand Up @@ -77,5 +78,16 @@ private TaskFailedEvent()
/// </summary>
[DataMember]
public FailureDetails? FailureDetails { get; private set; }

/// <summary>
/// Gets or sets the UTC time at which the dispatcher invoked <see cref="TaskActivity.RunAsync"/>.
/// </summary>
/// <remarks>
/// This is the start of the invocation associated with this response, not the time the task was scheduled.
/// A redelivered task records only the invocation whose response is persisted. The value is <c>null</c>
/// for older history or when the dispatcher did not observe a matching activity invocation.
/// </remarks>
[DataMember(EmitDefaultValue = false)]
public DateTime? StartedTime { get; set; }
}
}
7 changes: 7 additions & 0 deletions src/DurableTask.Core/TaskActivityDispatcher.cs
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,7 @@ async Task OnProcessWorkItemAsync(TaskActivityWorkItem workItem)
});

ActivityExecutionResult? result;
DateTime? activityStartedTime = null;
try
{
await this.dispatchPipeline.RunAsync(dispatchContext, async _ =>
Expand Down Expand Up @@ -216,6 +217,7 @@ await this.dispatchPipeline.RunAsync(dispatchContext, async _ =>

try
{
activityStartedTime = DateTime.UtcNow;
string? output = await taskActivity.RunAsync(context, scheduledEvent.Input);
responseEvent = new TaskCompletedEvent(-1, scheduledEvent.EventId, output);
}
Expand Down Expand Up @@ -267,8 +269,13 @@ await this.dispatchPipeline.RunAsync(dispatchContext, async _ =>

if (eventToRespond is TaskCompletedEvent completedEvent)
{
completedEvent.StartedTime = completedEvent.TaskScheduledId == scheduledEvent.EventId ? activityStartedTime : null;
this.logHelper.TaskActivityCompleted(orchestrationInstance, scheduledEvent.Name, completedEvent);
}
else if (eventToRespond is TaskFailedEvent failedEvent)
{
failedEvent.StartedTime = failedEvent.TaskScheduledId == scheduledEvent.EventId ? activityStartedTime : null;
}
else if (eventToRespond is null)
{
// Default response if middleware prevents a response from being generated
Expand Down
66 changes: 66 additions & 0 deletions test/DurableTask.AzureStorage.Tests/AzureTableTrackingStoreTest.cs
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ namespace DurableTask.AzureStorage.Tests
using DurableTask.Core.Tracking;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using Moq;
using Newtonsoft.Json.Linq;

[TestClass]
public class AzureTableTrackingStoreTest
Expand Down Expand Up @@ -164,5 +165,70 @@ public async Task InstanceStoreBackedTrackingStore_PersistsParentOnCreation()
Assert.AreSame(startedEvent.ParentInstance, writtenState.State.ParentInstance);
Assert.AreEqual(ParentInstanceId, writtenState.State.ParentInstance.OrchestrationInstance.InstanceId);
}

[TestMethod]
[DataRow(false)]
[DataRow(true)]
public async Task ActivityStartedTime_PersistsInHistoryAndHistoryJson(bool failed)
{
const string InstanceId = "instance";
const string ExecutionId = "execution";
DateTime scheduledTime = new DateTime(2026, 1, 2, 12, 0, 0, DateTimeKind.Utc);
DateTime startedTime = scheduledTime.AddMinutes(12);
DateTime completedTime = scheduledTime.AddMinutes(15);
var settings = TestHelpers.GetTestAzureStorageOrchestrationServiceSettings(enableExtendedSessions: false);
settings.TaskHubName = "started" + Guid.NewGuid().ToString("N");
var storageClient = new AzureStorageClient(settings);
var messageManager = new MessageManager(settings, storageClient, settings.TaskHubName.ToLowerInvariant() + "-largemessages");
var trackingStore = new AzureTableTrackingStore(storageClient, messageManager);
using var service = new AzureStorageOrchestrationService(settings);
var runtimeState = new OrchestrationRuntimeState();
runtimeState.AddEvent(new ExecutionStartedEvent(0, null)
{
Name = "orchestration",
OrchestrationInstance = new OrchestrationInstance { InstanceId = InstanceId, ExecutionId = ExecutionId },
Timestamp = scheduledTime,
});
runtimeState.AddEvent(new TaskScheduledEvent(1, "activity", "v1") { Timestamp = scheduledTime });
HistoryEvent response = failed
? new TaskFailedEvent(2, 1, "failure", "details") { StartedTime = startedTime, Timestamp = completedTime }
: new TaskCompletedEvent(2, 1, "result") { StartedTime = startedTime, Timestamp = completedTime };
runtimeState.AddEvent(response);
runtimeState.AddEvent(new TaskScheduledEvent(3, "legacy", "v1") { Timestamp = scheduledTime });
runtimeState.AddEvent(new TaskCompletedEvent(4, 3, "legacy") { Timestamp = completedTime });

try
{
await trackingStore.CreateAsync();
OrchestrationHistory empty = await trackingStore.GetHistoryEventsAsync(InstanceId, ExecutionId);
await trackingStore.UpdateStateAsync(
runtimeState, runtimeState, InstanceId, ExecutionId, new OrchestrationETags(), empty.TrackingStoreContext);

var tableClient = new TableServiceClient(TestHelpers.GetTestStorageAccountConnectionString())
.GetTableClient(settings.TaskHubName + "History");
TableEntity row = (await tableClient.GetEntityAsync<TableEntity>(InstanceId, "0000000000000002")).Value;
Assert.AreEqual(startedTime, row.GetDateTime("StartedTime"));
Assert.AreEqual(completedTime, row.GetDateTime("_Timestamp"));
TableEntity legacyRow = (await tableClient.GetEntityAsync<TableEntity>(InstanceId, "0000000000000004")).Value;
Assert.IsFalse(legacyRow.ContainsKey("StartedTime"));

OrchestrationHistory history = await trackingStore.GetHistoryEventsAsync(InstanceId, ExecutionId);
HistoryEvent actual = history.Events[2];
Assert.AreEqual(response.EventType, actual.EventType);
Assert.AreEqual(startedTime, actual is TaskFailedEvent failure ? failure.StartedTime : ((TaskCompletedEvent)actual).StartedTime);
Assert.IsNull(((TaskCompletedEvent)history.Events[4]).StartedTime);

JArray json = JArray.Parse(await service.GetOrchestrationHistoryAsync(InstanceId, ExecutionId));
Assert.AreEqual(scheduledTime, (DateTime)json[1]["Timestamp"]);
Assert.AreEqual(startedTime, (DateTime)json[2]["StartedTime"]);
Assert.AreEqual(completedTime, (DateTime)json[2]["Timestamp"]);
Assert.AreEqual(1, (int)json[2]["TaskScheduledId"]);
Assert.IsNull(json[4]["StartedTime"]);
}
finally
{
await trackingStore.DeleteAsync();
}
}
}
}
41 changes: 41 additions & 0 deletions test/DurableTask.AzureStorage.Tests/MessageManagerTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,47 @@ public async Task SerializeMessageDataAsync_InlinePayloadMatchesPreviousWirePayl
((GenericEvent)roundTrippedMessage.TaskMessage.Event).Data);
}

[TestMethod]
[DataRow(false, false)]
[DataRow(false, true)]
[DataRow(true, false)]
[DataRow(true, true)]
public async Task SerializeMessageDataAsync_PreservesActivityStartedTime(bool useDataContractSerialization, bool failed)
{
var settings = new AzureStorageOrchestrationServiceSettings
{
UseDataContractSerialization = useDataContractSerialization,
};
var manager = SetupMessageManager(settings, "$root");
DateTime startedTime = new DateTime(2026, 1, 2, 12, 12, 0, DateTimeKind.Utc);
MessageData message = CreateMessageData("unused");
message.TaskMessage.Event = failed
? new TaskFailedEvent(-1, 7, "failure", "details") { StartedTime = startedTime }
: new TaskCompletedEvent(-1, 7, "result") { StartedTime = startedTime };

string payload = await manager.SerializeMessageDataAsync(message);
MessageData actual = manager.DeserializeMessageData(payload);

Assert.AreEqual(MessageFormatFlags.InlineJson, manager.GetMessageFormatFlags(message));
Assert.AreEqual(message.TaskMessage.Event.Timestamp, actual.TaskMessage.Event.Timestamp);
Assert.AreEqual(message.TaskMessage.OrchestrationInstance.InstanceId, actual.TaskMessage.OrchestrationInstance.InstanceId);
Assert.AreEqual(message.TaskMessage.OrchestrationInstance.ExecutionId, actual.TaskMessage.OrchestrationInstance.ExecutionId);
if (failed)
{
var response = (TaskFailedEvent)actual.TaskMessage.Event;
Assert.AreEqual(7, response.TaskScheduledId);
Assert.AreEqual(startedTime, response.StartedTime);
Assert.AreEqual("failure", response.Reason);
}
else
{
var response = (TaskCompletedEvent)actual.TaskMessage.Event;
Assert.AreEqual(7, response.TaskScheduledId);
Assert.AreEqual(startedTime, response.StartedTime);
Assert.AreEqual("result", response.Result);
}
}

[DataTestMethod]
[DataRow(false, 0)]
[DataRow(false, 1)]
Expand Down
Loading
Loading