mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Tao Chen
e3b4b6662b
* feat(workflows): Make telemetry opt-in via WithOpenTelemetry() - Add WorkflowTelemetryOptions class with EnableSensitiveData property - Add WorkflowTelemetryContext to manage ActivitySource lifecycle - Add WithOpenTelemetry() extension method on WorkflowBuilder - Update all workflow components to use telemetry context: - WorkflowBuilder, Workflow, Executor - InProcessRunnerContext, InProcessRunner - LockstepRunEventStream, StreamingRunEventStream - All edge runners (Direct, FanIn, FanOut, Response) - Telemetry is now disabled by default - Users must call WithOpenTelemetry() to enable spans/activities BREAKING CHANGE: Workflow telemetry is now opt-in. Users who relied on automatic telemetry must add .WithOpenTelemetry() to their workflow builder. * refactor: Pass telemetry context as parameter instead of via interface - Remove IWorkflowContextWithTelemetry interface - Add internal ExecuteAsync overload that accepts WorkflowTelemetryContext - Public ExecuteAsync delegates with WorkflowTelemetryContext.Disabled - InProcessRunner passes TelemetryContext when calling ExecuteAsync - BoundContext now implements IWorkflowContext (not the removed interface) * Add optional ActivitySource parameter to WithOpenTelemetry Allow users to provide their own ActivitySource when enabling telemetry, giving them better control over the ActivitySource lifecycle. When not provided, the framework creates one internally (existing behavior). Changes: - Add optional activitySource parameter to WithOpenTelemetry() extension - Update WorkflowTelemetryContext to accept external ActivitySource - Add unit test for user-provided ActivitySource scenario * Add component-level telemetry control with disable flags Allow users to selectively disable specific activity types via WorkflowTelemetryOptions. All activities are enabled by default. New disable flags: - DisableWorkflowBuild: Disables workflow.build activities - DisableWorkflowRun: Disables workflow_invoke activities - DisableExecutorProcess: Disables executor.process activities - DisableEdgeGroupProcess: Disables edge_group.process activities - DisableMessageSend: Disables message.send activities Added helper methods to WorkflowTelemetryContext for each activity type and updated all activity creation sites to use them. * Implement EnableSensitiveData to log executor input/output When EnableSensitiveData is true in WorkflowTelemetryOptions, executor input and output are logged as JSON-serialized attributes in the executor.process activity. New activity tags: - executor.input: JSON serialized input message - executor.output: JSON serialized output result (non-void only) Added suppression attributes for AOT/trimming warnings since this is an opt-in feature for debugging/diagnostics. * Refactor activity start methods to centralize tagging logic Move tagging logic into WorkflowTelemetryContext methods: - StartExecutorProcessActivity now accepts executorId, executorType, messageType, and message; sets all tags including executor.input when EnableSensitiveData is true - Added SetExecutorOutput method to set executor.output after execution - StartMessageSendActivity now accepts sourceId, targetId, and message; sets all tags including message.content when EnableSensitiveData is true Simplified Executor.cs and InProcessRunnerContext.cs by removing inline tagging code. Added message.content tag constant. * Revert Python changes * Update samples and code cleanup * Fix file formatting * Add comment * Add telemetry configuration to declarative workflow * Remove delays in tests * Address comments
70 lines
3.0 KiB
C#
70 lines
3.0 KiB
C#
// Copyright (c) Microsoft. All rights reserved.
|
|
|
|
using System;
|
|
using System.Diagnostics;
|
|
using Microsoft.Agents.AI.Workflows.Observability;
|
|
using Microsoft.Shared.Diagnostics;
|
|
|
|
namespace Microsoft.Agents.AI.Workflows;
|
|
|
|
/// <summary>
|
|
/// Provides extension methods for adding OpenTelemetry instrumentation to <see cref="WorkflowBuilder"/> instances.
|
|
/// </summary>
|
|
public static class OpenTelemetryWorkflowBuilderExtensions
|
|
{
|
|
/// <summary>
|
|
/// Enables OpenTelemetry instrumentation for the workflow, providing comprehensive observability for workflow operations.
|
|
/// </summary>
|
|
/// <param name="builder">The <see cref="WorkflowBuilder"/> to which OpenTelemetry support will be added.</param>
|
|
/// <param name="configure">
|
|
/// An optional callback that provides additional configuration of the <see cref="WorkflowTelemetryOptions"/> instance.
|
|
/// This allows for fine-tuning telemetry behavior such as enabling sensitive data collection.
|
|
/// </param>
|
|
/// <param name="activitySource">
|
|
/// An optional <see cref="ActivitySource"/> to use for telemetry. If provided, this activity source will be used
|
|
/// directly and the caller retains ownership (responsible for disposal). If <see langword="null"/>, a shared
|
|
/// default activity source named "Microsoft.Agents.AI.Workflows" will be used.
|
|
/// </param>
|
|
/// <returns>The <see cref="WorkflowBuilder"/> with OpenTelemetry instrumentation enabled, enabling method chaining.</returns>
|
|
/// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// This extension adds comprehensive telemetry capabilities to workflows, including:
|
|
/// <list type="bullet">
|
|
/// <item><description>Distributed tracing of workflow execution</description></item>
|
|
/// <item><description>Executor invocation and processing spans</description></item>
|
|
/// <item><description>Edge routing and message delivery spans</description></item>
|
|
/// <item><description>Workflow build and validation spans</description></item>
|
|
/// <item><description>Error tracking and exception details</description></item>
|
|
/// </list>
|
|
/// </para>
|
|
/// <para>
|
|
/// By default, workflow telemetry is disabled. Call this method to enable telemetry collection.
|
|
/// </para>
|
|
/// </remarks>
|
|
/// <example>
|
|
/// <code>
|
|
/// var workflow = new WorkflowBuilder(startExecutor)
|
|
/// .AddEdge(executor1, executor2)
|
|
/// .WithOpenTelemetry(cfg => cfg.EnableSensitiveData = true)
|
|
/// .Build();
|
|
/// </code>
|
|
/// </example>
|
|
public static WorkflowBuilder WithOpenTelemetry(
|
|
this WorkflowBuilder builder,
|
|
Action<WorkflowTelemetryOptions>? configure = null,
|
|
ActivitySource? activitySource = null)
|
|
{
|
|
Throw.IfNull(builder);
|
|
|
|
WorkflowTelemetryOptions options = new();
|
|
configure?.Invoke(options);
|
|
|
|
WorkflowTelemetryContext context = new(options, activitySource);
|
|
|
|
builder.SetTelemetryContext(context);
|
|
|
|
return builder;
|
|
}
|
|
}
|