From a005acffff789185c786638df9898876587e2701 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 14:54:07 +0000 Subject: [PATCH 1/4] Initial plan From 593c9253a2379019c73d9949b51c268c9360ec2a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 14:59:37 +0000 Subject: [PATCH 2/4] feat: support optional spanKind for InvokeAgentScope and ExecuteToolScope Co-authored-by: nikhilNava <211831449+nikhilNava@users.noreply.github.com> --- .../Tracing/Scopes/ExecuteToolScope.cs | 7 ++-- .../Tracing/Scopes/InvokeAgentScope.cs | 7 ++-- .../Tracing/Scopes/ExecuteToolScopeTest.cs | 33 +++++++++++++++++++ .../Tracing/Scopes/InvokeAgentScopeTest.cs | 29 ++++++++++++++++ 4 files changed, 70 insertions(+), 6 deletions(-) diff --git a/src/Observability/Runtime/Tracing/Scopes/ExecuteToolScope.cs b/src/Observability/Runtime/Tracing/Scopes/ExecuteToolScope.cs index 25855523..0d4706b1 100644 --- a/src/Observability/Runtime/Tracing/Scopes/ExecuteToolScope.cs +++ b/src/Observability/Runtime/Tracing/Scopes/ExecuteToolScope.cs @@ -33,6 +33,7 @@ public sealed class ExecuteToolScope : OpenTelemetryScope /// Optional details about the non-agentic caller. /// Optional explicit start time. Useful when recording a tool call after execution has already completed. /// Optional explicit end time. When provided, the span will use this timestamp when disposed instead of the current wall-clock time. + /// Optional span kind override. Defaults to . Use when the tool calls an external service. /// A new ExecuteToolScope instance. /// /// @@ -47,11 +48,11 @@ public sealed class ExecuteToolScope : OpenTelemetryScope /// Learn more about certification requirements /// /// - public static ExecuteToolScope Start(ToolCallDetails details, AgentDetails agentDetails, TenantDetails tenantDetails, string? parentId = null, string? conversationId = null, SourceMetadata? sourceMetadata = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, CallerDetails? callerDetails = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null) => new ExecuteToolScope(details, agentDetails, tenantDetails, parentId, conversationId, sourceMetadata, threatDiagnosticsSummary, callerDetails, startTime, endTime); + public static ExecuteToolScope Start(ToolCallDetails details, AgentDetails agentDetails, TenantDetails tenantDetails, string? parentId = null, string? conversationId = null, SourceMetadata? sourceMetadata = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, CallerDetails? callerDetails = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, ActivityKind? spanKind = null) => new ExecuteToolScope(details, agentDetails, tenantDetails, parentId, conversationId, sourceMetadata, threatDiagnosticsSummary, callerDetails, startTime, endTime, spanKind); - private ExecuteToolScope(ToolCallDetails details, AgentDetails agentDetails, TenantDetails tenantDetails, string? parentId = null, string? conversationId = null, SourceMetadata? sourceMetadata = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, CallerDetails? callerDetails = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null) + private ExecuteToolScope(ToolCallDetails details, AgentDetails agentDetails, TenantDetails tenantDetails, string? parentId = null, string? conversationId = null, SourceMetadata? sourceMetadata = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, CallerDetails? callerDetails = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, ActivityKind? spanKind = null) : base( - kind: ActivityKind.Internal, + kind: spanKind ?? ActivityKind.Internal, agentDetails: agentDetails, tenantDetails: tenantDetails, operationName: OperationName, diff --git a/src/Observability/Runtime/Tracing/Scopes/InvokeAgentScope.cs b/src/Observability/Runtime/Tracing/Scopes/InvokeAgentScope.cs index 84ae8855..1f78e8d4 100644 --- a/src/Observability/Runtime/Tracing/Scopes/InvokeAgentScope.cs +++ b/src/Observability/Runtime/Tracing/Scopes/InvokeAgentScope.cs @@ -35,6 +35,7 @@ public sealed class InvokeAgentScope : OpenTelemetryScope /// Optional explicit start time. Useful when recording an agent invocation after execution has already completed. /// Optional explicit end time. When provided, the span will use this timestamp when disposed instead of the current wall-clock time. /// Optional parent Activity ID used to link this span to an upstream operation. + /// Optional span kind override. Defaults to . Use when the agent is receiving an inbound request. /// A new InvokeAgentScope instance. /// /// @@ -54,11 +55,11 @@ public sealed class InvokeAgentScope : OpenTelemetryScope /// /// public static InvokeAgentScope Start( - InvokeAgentDetails invokeAgentDetails, TenantDetails tenantDetails, Request? request = null, AgentDetails? callerAgentDetails = null, CallerDetails? callerDetails = null, string? conversationId = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? parentId = null) => new InvokeAgentScope(invokeAgentDetails, tenantDetails, request, callerAgentDetails, callerDetails, conversationId, threatDiagnosticsSummary, startTime, endTime, parentId); + InvokeAgentDetails invokeAgentDetails, TenantDetails tenantDetails, Request? request = null, AgentDetails? callerAgentDetails = null, CallerDetails? callerDetails = null, string? conversationId = null, ThreatDiagnosticsSummary? threatDiagnosticsSummary = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? parentId = null, ActivityKind? spanKind = null) => new InvokeAgentScope(invokeAgentDetails, tenantDetails, request, callerAgentDetails, callerDetails, conversationId, threatDiagnosticsSummary, startTime, endTime, parentId, spanKind); - private InvokeAgentScope(InvokeAgentDetails invokeAgentDetails, TenantDetails tenantDetails, Request? request, AgentDetails? callerAgentDetails, CallerDetails? callerDetails, string? conversationId, ThreatDiagnosticsSummary? threatDiagnosticsSummary, DateTimeOffset? startTime, DateTimeOffset? endTime, string? parentId) + private InvokeAgentScope(InvokeAgentDetails invokeAgentDetails, TenantDetails tenantDetails, Request? request, AgentDetails? callerAgentDetails, CallerDetails? callerDetails, string? conversationId, ThreatDiagnosticsSummary? threatDiagnosticsSummary, DateTimeOffset? startTime, DateTimeOffset? endTime, string? parentId, ActivityKind? spanKind) : base( - kind: ActivityKind.Client, + kind: spanKind ?? ActivityKind.Client, agentDetails: invokeAgentDetails.Details, tenantDetails: tenantDetails, operationName: OperationName, diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/ExecuteToolScopeTest.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/ExecuteToolScopeTest.cs index 25fc44e9..05f09eb2 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/ExecuteToolScopeTest.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/ExecuteToolScopeTest.cs @@ -303,4 +303,37 @@ public void SetEndTime_OverridesEndTime() var startTime = new DateTimeOffset(activity.StartTimeUtc); startTime.Should().BeCloseTo(customStartTime, TimeSpan.FromMilliseconds(100)); } + + [TestMethod] + public void SpanKind_DefaultsToInternal() + { + // Act + var activity = ListenForActivity(() => + { + using var scope = ExecuteToolScope.Start( + new ToolCallDetails("TestTool", "args"), + Util.GetAgentDetails(), + Util.GetTenantDetails()); + }); + + // Assert + activity.Kind.Should().Be(System.Diagnostics.ActivityKind.Internal); + } + + [TestMethod] + public void SpanKind_OverrideToClient() + { + // Act + var activity = ListenForActivity(() => + { + using var scope = ExecuteToolScope.Start( + new ToolCallDetails("TestTool", "args"), + Util.GetAgentDetails(), + Util.GetTenantDetails(), + spanKind: System.Diagnostics.ActivityKind.Client); + }); + + // Assert + activity.Kind.Should().Be(System.Diagnostics.ActivityKind.Client); + } } \ No newline at end of file diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/InvokeAgentScopeTest.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/InvokeAgentScopeTest.cs index 5b8cdffb..68dbc8a3 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/InvokeAgentScopeTest.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Scopes/InvokeAgentScopeTest.cs @@ -316,4 +316,33 @@ public void SetEndTime_OverridesEndTime() var startTime = new DateTimeOffset(activity.StartTimeUtc); startTime.Should().BeCloseTo(customStartTime, TimeSpan.FromMilliseconds(100)); } + + [TestMethod] + public void SpanKind_DefaultsToClient() + { + // Act + var activity = ListenForActivity(() => + { + using var scope = InvokeAgentScope.Start(Details, Util.GetTenantDetails()); + }); + + // Assert + activity.Kind.Should().Be(System.Diagnostics.ActivityKind.Client); + } + + [TestMethod] + public void SpanKind_OverrideToServer() + { + // Act + var activity = ListenForActivity(() => + { + using var scope = InvokeAgentScope.Start( + Details, + Util.GetTenantDetails(), + spanKind: System.Diagnostics.ActivityKind.Server); + }); + + // Assert + activity.Kind.Should().Be(System.Diagnostics.ActivityKind.Server); + } } \ No newline at end of file From 12ced0c80bd0312fe577192bea558108e0be716a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 16:04:52 +0000 Subject: [PATCH 3/4] feat: add spanKind support to DTOs and builders Co-authored-by: nikhilNava <211831449+nikhilNava@users.noreply.github.com> --- src/Observability/Runtime/DTOs/BaseData.cs | 11 +++++- .../DTOs/Builders/ExecuteToolDataBuilder.cs | 7 +++- .../DTOs/Builders/InvokeAgentDataBuilder.cs | 8 +++- .../Runtime/DTOs/ExecuteToolData.cs | 7 +++- .../Runtime/DTOs/InvokeAgentData.cs | 7 +++- .../DTOs/BaseDataTests.cs | 33 +++++++++++++++- .../Builders/ExecuteToolDataBuilderTests.cs | 34 +++++++++++++++++ .../Builders/InvokeAgentDataBuilderTests.cs | 38 +++++++++++++++++++ .../DTOs/ExecuteToolDataTests.cs | 14 +++++++ .../DTOs/InvokeAgentDataTests.cs | 14 +++++++ 10 files changed, 163 insertions(+), 10 deletions(-) diff --git a/src/Observability/Runtime/DTOs/BaseData.cs b/src/Observability/Runtime/DTOs/BaseData.cs index 82154b17..5732d90c 100644 --- a/src/Observability/Runtime/DTOs/BaseData.cs +++ b/src/Observability/Runtime/DTOs/BaseData.cs @@ -19,12 +19,14 @@ public abstract class BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. + /// Optional span kind for the operation (e.g., Client, Server, Internal). public BaseData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, - string? parentSpanId = null) + string? parentSpanId = null, + ActivityKind? spanKind = null) { Attributes = attributes ?? new Dictionary(); StartTime = startTime; @@ -32,6 +34,7 @@ public BaseData( // Generate a random span ID if not provided. Use ActivitySpanId for consistency with tracing. SpanId = spanId ?? ActivitySpanId.CreateRandom().ToString(); ParentSpanId = parentSpanId; + SpanKind = spanKind; } /// @@ -64,6 +67,11 @@ public BaseData( /// public string? ParentSpanId { get; } + /// + /// Gets the span kind for the operation, if provided. + /// + public ActivityKind? SpanKind { get; } + /// /// Gets the duration of the operation if both start and end times are provided. /// @@ -84,6 +92,7 @@ public BaseData( { "EndTime", EndTime }, { "SpanId", SpanId }, { "ParentSpanId", ParentSpanId }, + { "SpanKind", SpanKind }, { "Duration", Duration } }; diff --git a/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs b/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs index 533a2027..62027d2b 100644 --- a/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs +++ b/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs @@ -5,6 +5,7 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; +using System.Diagnostics; using static Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes.OpenTelemetryConstants; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders @@ -31,6 +32,7 @@ public class ExecuteToolDataBuilder : BaseDataBuilder /// Optional source metadata for the operation. /// Optional details about the non-agentic caller. /// Optional dictionary of extra attributes. + /// Optional span kind override. Use or as appropriate. /// An ExecuteToolData object containing all telemetry data. public static ExecuteToolData Build( ToolCallDetails toolCallDetails, @@ -44,11 +46,12 @@ public static ExecuteToolData Build( string? parentSpanId = null, SourceMetadata? sourceMetadata = null, CallerDetails? callerDetails = null, - IDictionary? extraAttributes = null) + IDictionary? extraAttributes = null, + ActivityKind? spanKind = null) { var attributes = BuildAttributes(toolCallDetails, agentDetails, tenantDetails, conversationId, responseContent, sourceMetadata, callerDetails, extraAttributes); - return new ExecuteToolData(attributes, startTime, endTime, spanId, parentSpanId); + return new ExecuteToolData(attributes, startTime, endTime, spanId, parentSpanId, spanKind); } private static Dictionary BuildAttributes( diff --git a/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs b/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs index 7ea5dc23..57ec19f6 100644 --- a/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs +++ b/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs @@ -4,6 +4,7 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; +using System.Diagnostics; using static Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes.OpenTelemetryConstants; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders @@ -31,6 +32,7 @@ public class InvokeAgentDataBuilder : BaseDataBuilder /// Optional span ID for the operation. /// Optional parent span ID for distributed tracing. /// Optional dictionary of extra attributes. + /// Optional span kind override. Use or as appropriate. /// An InvokeAgentData object containing all telemetry data. public static InvokeAgentData Build( InvokeAgentDetails invokeAgentDetails, @@ -45,7 +47,8 @@ public static InvokeAgentData Build( DateTimeOffset? endTime = null, string? spanId = null, string? parentSpanId = null, - IDictionary? extraAttributes = null) + IDictionary? extraAttributes = null, + ActivityKind? spanKind = null) { var attributes = BuildAttributes( invokeAgentDetails, @@ -63,7 +66,8 @@ public static InvokeAgentData Build( startTime, endTime, spanId, - parentSpanId); + parentSpanId, + spanKind); } /// diff --git a/src/Observability/Runtime/DTOs/ExecuteToolData.cs b/src/Observability/Runtime/DTOs/ExecuteToolData.cs index 44526868..b7934539 100644 --- a/src/Observability/Runtime/DTOs/ExecuteToolData.cs +++ b/src/Observability/Runtime/DTOs/ExecuteToolData.cs @@ -4,6 +4,7 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; +using System.Diagnostics; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs { @@ -20,13 +21,15 @@ public class ExecuteToolData : BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. + /// Optional span kind override. Defaults to null (unset). Use or as appropriate. public ExecuteToolData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, - string? parentSpanId = null) - : base(attributes, startTime, endTime, spanId, parentSpanId) + string? parentSpanId = null, + ActivityKind? spanKind = null) + : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } /// diff --git a/src/Observability/Runtime/DTOs/InvokeAgentData.cs b/src/Observability/Runtime/DTOs/InvokeAgentData.cs index 4ba3d88f..3e07a910 100644 --- a/src/Observability/Runtime/DTOs/InvokeAgentData.cs +++ b/src/Observability/Runtime/DTOs/InvokeAgentData.cs @@ -4,6 +4,7 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; +using System.Diagnostics; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs { @@ -20,13 +21,15 @@ public class InvokeAgentData : BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. + /// Optional span kind override. Defaults to null (unset). Use or as appropriate. public InvokeAgentData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, - string? parentSpanId = null) - : base(attributes, startTime, endTime, spanId, parentSpanId) + string? parentSpanId = null, + ActivityKind? spanKind = null) + : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs index f696ed46..5a27d78e 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs @@ -17,7 +17,8 @@ public TestData( DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, - string? parentSpanId = null) : base(attributes, startTime, endTime, spanId, parentSpanId) { } + string? parentSpanId = null, + ActivityKind? spanKind = null) : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } public override string Name => "Test"; } @@ -131,5 +132,35 @@ public void Attributes_PreserveTypes() data.Attributes["bool"].Should().BeOfType(); data.Attributes["null"].Should().BeNull(); } + + [TestMethod] + public void SpanKind_DefaultsToNull() + { + var data = new TestData(); + data.SpanKind.Should().BeNull(); + } + + [TestMethod] + public void SpanKind_UsesProvidedValue() + { + var data = new TestData(spanKind: ActivityKind.Client); + data.SpanKind.Should().Be(ActivityKind.Client); + } + + [TestMethod] + public void SpanKind_IncludedInToDictionary() + { + var data = new TestData(spanKind: ActivityKind.Server); + var dict = data.ToDictionary(); + dict.Should().ContainKey("SpanKind").WhoseValue.Should().Be(ActivityKind.Server); + } + + [TestMethod] + public void SpanKind_NullInToDictionary_WhenNotProvided() + { + var data = new TestData(); + var dict = data.ToDictionary(); + dict.Should().ContainKey("SpanKind").WhoseValue.Should().BeNull(); + } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs index 04417a1a..00b9f2c1 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs @@ -332,5 +332,39 @@ public void Build_IgnoresNullValues_InExtraAttributes() data.Attributes.Should().NotContainKey("tool.null"); data.Attributes.Should().ContainKey("tool.valid").WhoseValue.Should().Be("yes"); } + + [TestMethod] + public void Build_SpanKind_DefaultsToNull() + { + // Arrange + var tool = new ToolCallDetails("toolSK", null); + var agent = new AgentDetails("agent-sk"); + var tenant = new TenantDetails(Guid.NewGuid()); + var conversationId = "conv-sk-default"; + + // Act + var data = ExecuteToolDataBuilder.Build(tool, agent, tenant, conversationId); + + // Assert + data.SpanKind.Should().BeNull(); + } + + [TestMethod] + public void Build_SpanKind_PassesThroughProvidedValue() + { + // Arrange + var tool = new ToolCallDetails("toolSK", null); + var agent = new AgentDetails("agent-sk"); + var tenant = new TenantDetails(Guid.NewGuid()); + var conversationId = "conv-sk-client"; + + // Act + var data = ExecuteToolDataBuilder.Build( + tool, agent, tenant, conversationId, + spanKind: System.Diagnostics.ActivityKind.Client); + + // Assert + data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Client); + } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs index 7e3686ce..1797a3a4 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs @@ -498,5 +498,43 @@ public void Build_WithAgentPlatformId_SetsExpectedAttributes() telemetry.Attributes.Should().ContainKey(OpenTelemetryConstants.GenAiInputMessagesKey); telemetry.Attributes[OpenTelemetryConstants.GenAiInputMessagesKey].Should().Be("Hello"); } + + [TestMethod] + public void Build_SpanKind_DefaultsToNull() + { + // Arrange + var endpoint = new Uri("https://example.com"); + var agentDetails = new AgentDetails("agent-123", "TestAgent"); + var invokeAgentDetails = new InvokeAgentDetails(endpoint: endpoint, details: agentDetails); + var tenantDetails = new TenantDetails(Guid.NewGuid()); + var conversationId = "conv-sk-default"; + + // Act + var data = InvokeAgentDataBuilder.Build(invokeAgentDetails, tenantDetails, conversationId); + + // Assert + data.SpanKind.Should().BeNull(); + } + + [TestMethod] + public void Build_SpanKind_PassesThroughProvidedValue() + { + // Arrange + var endpoint = new Uri("https://example.com"); + var agentDetails = new AgentDetails("agent-123", "TestAgent"); + var invokeAgentDetails = new InvokeAgentDetails(endpoint: endpoint, details: agentDetails); + var tenantDetails = new TenantDetails(Guid.NewGuid()); + var conversationId = "conv-sk-server"; + + // Act + var data = InvokeAgentDataBuilder.Build( + invokeAgentDetails, + tenantDetails, + conversationId, + spanKind: System.Diagnostics.ActivityKind.Server); + + // Assert + data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Server); + } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs index a6fcc4bc..257d5cf1 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs @@ -16,5 +16,19 @@ public void Name_ReturnsExecuteTool() var data = new ExecuteToolData(); data.Name.Should().Be(OpenTelemetryConstants.OperationNames.ExecuteTool.ToString()); } + + [TestMethod] + public void SpanKind_DefaultsToNull() + { + var data = new ExecuteToolData(); + data.SpanKind.Should().BeNull(); + } + + [TestMethod] + public void SpanKind_UsesProvidedValue() + { + var data = new ExecuteToolData(spanKind: System.Diagnostics.ActivityKind.Client); + data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Client); + } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs index d5ff09c6..bef4685d 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs @@ -13,5 +13,19 @@ public void Name_ReturnsInvokeAgent() var data = new InvokeAgentData(); data.Name.Should().Be(OpenTelemetryConstants.OperationNames.InvokeAgent.ToString()); } + + [TestMethod] + public void SpanKind_DefaultsToNull() + { + var data = new InvokeAgentData(); + data.SpanKind.Should().BeNull(); + } + + [TestMethod] + public void SpanKind_UsesProvidedValue() + { + var data = new InvokeAgentData(spanKind: System.Diagnostics.ActivityKind.Server); + data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Server); + } } } From 9e8863f750aea8c8d5cddee983b4e57c55fda09b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 16:22:05 +0000 Subject: [PATCH 4/4] feat: replace ActivityKind with string SpanKindConstants in DTOs/Builders, update FormatLogData with Kind default Co-authored-by: nikhilNava <211831449+nikhilNava@users.noreply.github.com> --- .../Runtime/Common/ExportFormatter.cs | 4 +- src/Observability/Runtime/DTOs/BaseData.cs | 8 ++-- .../DTOs/Builders/ExecuteToolDataBuilder.cs | 5 +-- .../DTOs/Builders/InvokeAgentDataBuilder.cs | 5 +-- .../Runtime/DTOs/ExecuteToolData.cs | 5 +-- .../Runtime/DTOs/InvokeAgentData.cs | 5 +-- .../Runtime/DTOs/SpanKindConstants.cs | 38 +++++++++++++++++++ .../Common/ExportFormatterTests.cs | 7 +++- .../DTOs/BaseDataTests.cs | 10 ++--- .../Builders/ExecuteToolDataBuilderTests.cs | 5 ++- .../Builders/InvokeAgentDataBuilderTests.cs | 5 ++- .../DTOs/ExecuteToolDataTests.cs | 4 +- .../DTOs/InvokeAgentDataTests.cs | 4 +- 13 files changed, 74 insertions(+), 31 deletions(-) create mode 100644 src/Observability/Runtime/DTOs/SpanKindConstants.cs diff --git a/src/Observability/Runtime/Common/ExportFormatter.cs b/src/Observability/Runtime/Common/ExportFormatter.cs index 6c2e1c50..e49bf310 100644 --- a/src/Observability/Runtime/Common/ExportFormatter.cs +++ b/src/Observability/Runtime/Common/ExportFormatter.cs @@ -1,5 +1,6 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT License. +using Microsoft.Agents.A365.Observability.Runtime.DTOs; using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; @@ -146,7 +147,8 @@ public string FormatLogData(IDictionary data) StartTimeUnixNano = data.TryGetValue("StartTime", out var startTimeObj) && startTimeObj != null ? ToUnixNanos(((DateTimeOffset)startTimeObj).UtcDateTime) : 0, EndTimeUnixNano = data.TryGetValue("EndTime", out var endTimeObj) && endTimeObj != null ? ToUnixNanos(((DateTimeOffset)endTimeObj).UtcDateTime) : 0, SpanId = data["SpanId"], - ParentSpanId = data["ParentSpanId"] + ParentSpanId = data["ParentSpanId"], + Kind = data.TryGetValue("SpanKind", out var spanKindObj) && spanKindObj != null ? spanKindObj : SpanKindConstants.Client }; return SerializePayload(payload); diff --git a/src/Observability/Runtime/DTOs/BaseData.cs b/src/Observability/Runtime/DTOs/BaseData.cs index 5732d90c..4ddb0175 100644 --- a/src/Observability/Runtime/DTOs/BaseData.cs +++ b/src/Observability/Runtime/DTOs/BaseData.cs @@ -19,14 +19,14 @@ public abstract class BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. - /// Optional span kind for the operation (e.g., Client, Server, Internal). + /// Optional span kind for the operation. Use values (e.g., , , ). public BaseData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, string? parentSpanId = null, - ActivityKind? spanKind = null) + string? spanKind = null) { Attributes = attributes ?? new Dictionary(); StartTime = startTime; @@ -68,9 +68,9 @@ public BaseData( public string? ParentSpanId { get; } /// - /// Gets the span kind for the operation, if provided. + /// Gets the span kind for the operation, if provided. See for valid values. /// - public ActivityKind? SpanKind { get; } + public string? SpanKind { get; } /// /// Gets the duration of the operation if both start and end times are provided. diff --git a/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs b/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs index 62027d2b..716cee7e 100644 --- a/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs +++ b/src/Observability/Runtime/DTOs/Builders/ExecuteToolDataBuilder.cs @@ -5,7 +5,6 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; -using System.Diagnostics; using static Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes.OpenTelemetryConstants; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders @@ -32,7 +31,7 @@ public class ExecuteToolDataBuilder : BaseDataBuilder /// Optional source metadata for the operation. /// Optional details about the non-agentic caller. /// Optional dictionary of extra attributes. - /// Optional span kind override. Use or as appropriate. + /// Optional span kind override. Use or as appropriate. /// An ExecuteToolData object containing all telemetry data. public static ExecuteToolData Build( ToolCallDetails toolCallDetails, @@ -47,7 +46,7 @@ public static ExecuteToolData Build( SourceMetadata? sourceMetadata = null, CallerDetails? callerDetails = null, IDictionary? extraAttributes = null, - ActivityKind? spanKind = null) + string? spanKind = null) { var attributes = BuildAttributes(toolCallDetails, agentDetails, tenantDetails, conversationId, responseContent, sourceMetadata, callerDetails, extraAttributes); diff --git a/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs b/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs index 57ec19f6..bde57e81 100644 --- a/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs +++ b/src/Observability/Runtime/DTOs/Builders/InvokeAgentDataBuilder.cs @@ -4,7 +4,6 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; -using System.Diagnostics; using static Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes.OpenTelemetryConstants; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders @@ -32,7 +31,7 @@ public class InvokeAgentDataBuilder : BaseDataBuilder /// Optional span ID for the operation. /// Optional parent span ID for distributed tracing. /// Optional dictionary of extra attributes. - /// Optional span kind override. Use or as appropriate. + /// Optional span kind override. Use or as appropriate. /// An InvokeAgentData object containing all telemetry data. public static InvokeAgentData Build( InvokeAgentDetails invokeAgentDetails, @@ -48,7 +47,7 @@ public static InvokeAgentData Build( string? spanId = null, string? parentSpanId = null, IDictionary? extraAttributes = null, - ActivityKind? spanKind = null) + string? spanKind = null) { var attributes = BuildAttributes( invokeAgentDetails, diff --git a/src/Observability/Runtime/DTOs/ExecuteToolData.cs b/src/Observability/Runtime/DTOs/ExecuteToolData.cs index b7934539..e55e1eb8 100644 --- a/src/Observability/Runtime/DTOs/ExecuteToolData.cs +++ b/src/Observability/Runtime/DTOs/ExecuteToolData.cs @@ -4,7 +4,6 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; -using System.Diagnostics; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs { @@ -21,14 +20,14 @@ public class ExecuteToolData : BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. - /// Optional span kind override. Defaults to null (unset). Use or as appropriate. + /// Optional span kind override. Defaults to null (unset). Use or as appropriate. public ExecuteToolData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, string? parentSpanId = null, - ActivityKind? spanKind = null) + string? spanKind = null) : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } diff --git a/src/Observability/Runtime/DTOs/InvokeAgentData.cs b/src/Observability/Runtime/DTOs/InvokeAgentData.cs index 3e07a910..0bf75116 100644 --- a/src/Observability/Runtime/DTOs/InvokeAgentData.cs +++ b/src/Observability/Runtime/DTOs/InvokeAgentData.cs @@ -4,7 +4,6 @@ using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; using System; using System.Collections.Generic; -using System.Diagnostics; namespace Microsoft.Agents.A365.Observability.Runtime.DTOs { @@ -21,14 +20,14 @@ public class InvokeAgentData : BaseData /// Optional custom end time for the operation. /// Optional span ID for the operation. If not provided one will be created. /// Optional parent span ID for distributed tracing. - /// Optional span kind override. Defaults to null (unset). Use or as appropriate. + /// Optional span kind override. Defaults to null (unset). Use or as appropriate. public InvokeAgentData( IDictionary? attributes = null, DateTimeOffset? startTime = null, DateTimeOffset? endTime = null, string? spanId = null, string? parentSpanId = null, - ActivityKind? spanKind = null) + string? spanKind = null) : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } diff --git a/src/Observability/Runtime/DTOs/SpanKindConstants.cs b/src/Observability/Runtime/DTOs/SpanKindConstants.cs new file mode 100644 index 00000000..3c18df91 --- /dev/null +++ b/src/Observability/Runtime/DTOs/SpanKindConstants.cs @@ -0,0 +1,38 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +namespace Microsoft.Agents.A365.Observability.Runtime.DTOs +{ + /// + /// Provides string constants for OpenTelemetry span kind values. + /// These constants are used in DTOs and Builders to avoid taking a dependency + /// on . + /// + public static class SpanKindConstants + { + /// + /// Indicates that the span covers server-side handling of a synchronous RPC or other remote request. + /// + public const string Server = "Server"; + + /// + /// Indicates that the span describes a request to some remote service. + /// + public const string Client = "Client"; + + /// + /// Indicates that the span describes a producer sending a message to a broker. + /// + public const string Producer = "Producer"; + + /// + /// Indicates that the span describes a consumer receiving a message from a broker. + /// + public const string Consumer = "Consumer"; + + /// + /// Default span kind. Indicates that the span represents an internal operation within an application. + /// + public const string Internal = "Internal"; + } +} diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Common/ExportFormatterTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Common/ExportFormatterTests.cs index 945a56a9..2c0fc069 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Common/ExportFormatterTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Common/ExportFormatterTests.cs @@ -439,7 +439,8 @@ public void FormatLogData_WithAllFields_ProducesExpectedJson() start, end, spanId, - parentSpanId); + parentSpanId, + spanKind: SpanKindConstants.Client); var formatter = CreateFormatter(); // Act @@ -453,6 +454,7 @@ public void FormatLogData_WithAllFields_ProducesExpectedJson() root.GetProperty("Name").GetString().Should().Be("InvokeAgent"); root.GetProperty("SpanId").GetString().Should().Be(spanId); root.GetProperty("ParentSpanId").GetString().Should().Be(parentSpanId); + root.GetProperty("Kind").GetString().Should().Be(SpanKindConstants.Client); var attrs = root.GetProperty("Attributes"); attrs.GetProperty("attr1").GetString().Should().Be("value1"); @@ -497,6 +499,9 @@ public void FormatLogData_WithMissingOptionalFields_ProducesDefaults() // ParentSpanId should be omitted due to null (ignore when writing null) root.TryGetProperty("ParentSpanId", out _).Should().BeFalse(); + // Kind defaults to Client when SpanKind is null + root.GetProperty("Kind").GetString().Should().Be(SpanKindConstants.Client); + var attrs = root.GetProperty("Attributes"); attrs.GetProperty("key").GetString().Should().Be("val"); } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs index 5a27d78e..a7c915e0 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/BaseDataTests.cs @@ -18,7 +18,7 @@ public TestData( DateTimeOffset? endTime = null, string? spanId = null, string? parentSpanId = null, - ActivityKind? spanKind = null) : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } + string? spanKind = null) : base(attributes, startTime, endTime, spanId, parentSpanId, spanKind) { } public override string Name => "Test"; } @@ -143,16 +143,16 @@ public void SpanKind_DefaultsToNull() [TestMethod] public void SpanKind_UsesProvidedValue() { - var data = new TestData(spanKind: ActivityKind.Client); - data.SpanKind.Should().Be(ActivityKind.Client); + var data = new TestData(spanKind: SpanKindConstants.Client); + data.SpanKind.Should().Be(SpanKindConstants.Client); } [TestMethod] public void SpanKind_IncludedInToDictionary() { - var data = new TestData(spanKind: ActivityKind.Server); + var data = new TestData(spanKind: SpanKindConstants.Server); var dict = data.ToDictionary(); - dict.Should().ContainKey("SpanKind").WhoseValue.Should().Be(ActivityKind.Server); + dict.Should().ContainKey("SpanKind").WhoseValue.Should().Be(SpanKindConstants.Server); } [TestMethod] diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs index 00b9f2c1..34f6b22a 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/ExecuteToolDataBuilderTests.cs @@ -1,4 +1,5 @@ using FluentAssertions; +using Microsoft.Agents.A365.Observability.Runtime.DTOs; using Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders; using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts; using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; @@ -361,10 +362,10 @@ public void Build_SpanKind_PassesThroughProvidedValue() // Act var data = ExecuteToolDataBuilder.Build( tool, agent, tenant, conversationId, - spanKind: System.Diagnostics.ActivityKind.Client); + spanKind: SpanKindConstants.Client); // Assert - data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Client); + data.SpanKind.Should().Be(SpanKindConstants.Client); } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs index 1797a3a4..f5c22275 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/Builders/InvokeAgentDataBuilderTests.cs @@ -1,4 +1,5 @@ using FluentAssertions; +using Microsoft.Agents.A365.Observability.Runtime.DTOs; using Microsoft.Agents.A365.Observability.Runtime.DTOs.Builders; using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts; using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes; @@ -531,10 +532,10 @@ public void Build_SpanKind_PassesThroughProvidedValue() invokeAgentDetails, tenantDetails, conversationId, - spanKind: System.Diagnostics.ActivityKind.Server); + spanKind: SpanKindConstants.Server); // Assert - data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Server); + data.SpanKind.Should().Be(SpanKindConstants.Server); } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs index 257d5cf1..56c8d623 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/ExecuteToolDataTests.cs @@ -27,8 +27,8 @@ public void SpanKind_DefaultsToNull() [TestMethod] public void SpanKind_UsesProvidedValue() { - var data = new ExecuteToolData(spanKind: System.Diagnostics.ActivityKind.Client); - data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Client); + var data = new ExecuteToolData(spanKind: SpanKindConstants.Client); + data.SpanKind.Should().Be(SpanKindConstants.Client); } } } diff --git a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs index bef4685d..f287d5ed 100644 --- a/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs +++ b/src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/DTOs/InvokeAgentDataTests.cs @@ -24,8 +24,8 @@ public void SpanKind_DefaultsToNull() [TestMethod] public void SpanKind_UsesProvidedValue() { - var data = new InvokeAgentData(spanKind: System.Diagnostics.ActivityKind.Server); - data.SpanKind.Should().Be(System.Diagnostics.ActivityKind.Server); + var data = new InvokeAgentData(spanKind: SpanKindConstants.Server); + data.SpanKind.Should().Be(SpanKindConstants.Server); } } }