Microsoft Agent Framework 工作流 - 可观测性

可观测性提供有关执行期间工作流的内部状态和行为的见解。 这包括帮助监视和调试工作流的日志记录、指标和跟踪功能。

小窍门

可观测性是一项框架范围的功能，不限于工作流。 有关详细信息，请参阅 可观测性。

除了标准 GenAI 遥测之外，Agent Framework 工作流还发出其他范围、日志和指标，以便更深入地了解工作流执行。 这些可观测性功能可帮助开发人员了解消息流、执行程序的性能以及可能发生的任何错误。

启用可观测性

有关在应用程序中启用可观测性的说明，请参阅 “启用可观测性 ”。

有关在应用程序中启用可观测性的说明，请参阅 “启用可观测性 ”。

工作流跨度

在工作流执行期间发出以下跨度：

跨度名称 Description
workflow.build 为每个工作流构建发出。
workflow.session 表示工作流执行全过程的外部跨度，包括从开始到停止或出现错误的整个生命周期。
workflow_invoke 为工作流会话中的每个输入到停止周期发出。
executor.process {executor_id} 为每个处理消息的执行程序发出。 执行程序 ID 附加到跨度名称。
edge_group.process 为每个处理消息的边组发出。
message.send 每当一个执行器向另一个执行器发送消息时发出。

在工作流执行期间发出以下跨度：

跨度名称 Description
workflow.build 为每个工作流构建发出。
workflow.run 为每个工作流执行发出。
executor.process {executor_id} 为每个处理消息的执行程序发出。 执行程序 ID 附加到跨度名称。
edge_group.process {edge_group_type} 为每个处理消息的边组发出。 边缘组类型被添加到跨度名称。
message.send 每当一个执行器向另一个执行器发送消息时发出。

在工作流执行期间发出以下跨度：

跨度名称 Description
workflow.build 为每个工作流构建发出。
workflow.session 表示工作流执行会话整个生命周期的外层跨度。
workflow_invoke 为工作流会话中的每个输入到停止周期发出。
executor.process {executor_id} 为每个处理消息的执行程序发出。 执行程序 ID 附加到跨度名称。
edge_group.process 为每个处理消息的边组发出。
message.send 为从一个执行程序发送到另一个执行程序的每条消息发出。

Span 属性

跨度携带提供有关操作附加上下文的属性。 在工作流跨度上设置以下属性：

Attribute 跨度 Description
workflow.id workflow.build、workflow.session 工作流的唯一标识符。
workflow.name workflow.session 工作流的名称。
workflow.description workflow.session 工作流的说明。
workflow.definition workflow.build 工作流图的 JSON 定义。
session.id workflow.session 唯一会话标识符。
executor.id executor.process 执行者的唯一标识符。
executor.type executor.process 执行器的类型名称。
executor.input executor.process 输入消息。 仅当启用敏感数据时设置。
executor.output executor.process 执行器的输出。 仅当启用敏感数据时设置。
message.type executor.process、message.send 消息的类型名称。
message.content message.send 消息内容。 仅当启用敏感数据时设置。
message.source_id message.send 发送消息的执行者 ID。
message.target_id message.send 目标执行程序的 ID（如果指定）。
edge_group.type edge_group.process 边缘组的类型。
edge_group.delivered edge_group.process 消息是否已传递（布尔值）。
edge_group.delivery_status edge_group.process 传递结果（请参阅 边缘组传递状态）。
error.type 任何出错的跨度 异常类型名称。
Attribute 跨度 Description
workflow.id workflow.build、workflow.run 工作流的唯一标识符。
workflow.name workflow.run 工作流的名称。
workflow.description workflow.run 工作流的说明。
workflow.definition workflow.build 工作流图的 JSON 定义。
workflow_builder.name workflow.build 工作流生成器的名称。
workflow_builder.description workflow.build 工作流生成器的说明。
executor.id executor.process 执行者的唯一标识符。
executor.type executor.process 执行器的类型名称。
message.type executor.process、message.send 消息的类型名称。
message.payload_type executor.process 消息有效负载的数据类型。
message.destination_executor_id message.send 目标执行程序的 ID（如果指定）。
message.source_id edge_group.process 发送消息的执行者 ID。
message.target_id edge_group.process 目标执行程序的 ID（如果指定）。
edge_group.type edge_group.process 边缘组的类型。
edge_group.id edge_group.process 边缘组的唯一标识符。
edge_group.delivered edge_group.process 消息是否已传递（布尔值）。
edge_group.delivery_status edge_group.process 传递结果（请参阅 边缘组传递状态）。
Attribute 跨度 Description
workflow.id workflow.build、workflow.session、workflow_invoke 工作流启动执行器 ID。
workflow.name workflow.session、workflow_invoke 设置时工作流名称。
workflow.description workflow.session、workflow_invoke 设置时工作流说明。
workflow.definition workflow.build 工作流图的 JSON 定义。
session.id workflow.session、workflow_invoke 工作流会话标识符。
executor.id executor.process 执行器 ID。
executor.implementation.id executor.process 执行器实现标识符。
executor.input executor.process 输入消息。 仅当启用敏感数据时设置。
executor.output executor.process 执行器输出 仅当启用敏感数据时设置。
message.type executor.process 已处理消息的类型名称。
message.content message.send 消息内容。 仅当启用敏感数据时设置。
message.source_id edge_group.process、message.send 发送消息的执行者 ID。
message.target_id edge_group.process、message.send 指定时的目标执行程序 ID。
edge_group.type edge_group.process 正在处理的边缘组的类型。
edge_group.delivered edge_group.process 消息是否已送达。
edge_group.delivery_status edge_group.process 传递结果（请参阅 边缘组传递状态）。
error.type 任何出错的跨度 异常类型名称。
error.message 任何出错的跨度 异常消息。

跨度事件

跨度事件是附加到跨度的结构化日志条目，提供每个跨度内关键时刻的时间线。

事件名称 跨度 Description
build.started workflow.build 生成过程开始时发出。
build.validation_completed workflow.build 在构建验证通过时发出。
build.completed workflow.build 编译成功完成时触发。
build.error workflow.build 构建失败时将发出错误信息。
session.started workflow.session 在工作流会话开始时发出。
session.completed workflow.session 工作流会话完成时发出。
session.error workflow.session 工作流会话遇到错误时发出。
workflow.started workflow_invoke 在工作流调用开始时发出。
workflow.completed workflow_invoke 工作流调用完成时发出。
workflow.error workflow_invoke 当工作流调用遇到错误时发出。
事件名称 跨度 Description
build.started workflow.build 生成过程开始时发出。
build.validation_completed workflow.build 在构建验证通过时发出。
build.completed workflow.build 编译成功完成时触发。
build.error workflow.build 构建失败时将发出错误信息。
workflow.started workflow.run 在工作流运行开始时发出。
workflow.completed workflow.run 工作流运行完成时发出。
workflow.error workflow.run 工作流运行遇到错误时发出。
事件名称 跨度 Description
build.started workflow.build 生成过程开始时发出。
build.validation_completed workflow.build 在构建验证通过时发出。
build.completed workflow.build 编译成功完成时触发。
build.error workflow.build 构建失败时将发出错误信息。
session.started workflow.session 在工作流会话开始时发出。
session.completed workflow.session 工作流会话完成时发出。
session.error workflow.session 工作流会话遇到错误时发出。
workflow.started workflow_invoke 在工作流调用开始时发出。
workflow.completed workflow_invoke 工作流调用完成时发出。
workflow.error workflow_invoke 当工作流调用遇到错误时发出。

当执行程序向另一个执行程序发送消息时，message.send 跨度会作为 executor.process 跨度的子跨度创建。 但是，目标执行程序的 executor.process 跨度不是 message.send 跨度的子级，因为执行不是嵌套的。 相反，目标执行程序的 executor.process 跨度链接到源执行程序的 message.send 跨度。 此链接通过工作流执行创建可跟踪路径，而无需暗示嵌套调用层次结构。

相同的链接方法适用于 edge_group.process 跨度，这些范围链接到源 message.send 范围以便进行因果跟踪。 这支持多个源跨度贡献于单个处理跨度的扇入场景。

边缘组交付状态

边缘组处理范围包括传递状态属性，这些属性指示通过每个边缘组路由消息的结果。 该 edge_group.delivery_status 属性设置为以下值之一：

地位 Description
delivered 消息已传送至目标执行器。
dropped type mismatch 目标执行程序无法处理消息类型。
dropped target mismatch 该消息指定了与此边缘不匹配的目标。
dropped condition false 边缘路由条件的计算结果为 false。
exception 边缘处理期间发生异常。
buffered 消息被缓冲，等待附加消息（扇入）。

edge_group.delivered布尔属性提供快速检查消息是否已成功传递。

遥测配置

可以通过工作流生成器上的扩展方法启用 WithOpenTelemetry 工作流遥测。 WorkflowTelemetryOptions 类提供对发出哪些跨度的细粒度控制：

选项 默认 Description
EnableSensitiveData false 包括跨度属性中的原始输入、输出和消息内容。
DisableWorkflowBuild false 禁用 workflow.build 跨度。
DisableWorkflowRun false 禁用 workflow.session 和 workflow_invoke 跨度。
DisableExecutorProcess false 禁用 executor.process 跨度。
DisableEdgeGroupProcess false 禁用 edge_group.process 跨度。
DisableMessageSend false 禁用 message.send 跨度。

警告

启用敏感数据会导致原始消息内容、执行程序输入和执行程序输出包含在遥测中。 仅在遥测数据受到适当保护的安全环境中启用此功能。

通过全局 enable_instrumentation() 函数启用工作流遥测。 当启用检测时，所有工作流跨度都会自动发出。 该 configure_otel_providers() 函数可用于为跟踪、指标和日志设置导出程序。

警告

查看遥测管道配置，以确保在导出跟踪时适当保护敏感数据。

工作流可观测性

可以在工作流生成器上启用 WithTelemetry 工作流遥测。 使用工作流 OpenTelemetry 跟踪程序包将跨度连接到你的 OpenTelemetry 提供程序。

启用工作流跟踪

import workflowotel "github.com/microsoft/agent-framework-go/workflow/observability/opentelemetry"

wf, err := workflow.NewBuilder(startExecutor).
    AddEdge(startExecutor, nextExecutor).
    WithTelemetry(
        workflowotel.New(workflowotel.Config{}),
        workflow.TelemetryOptions{EnableSensitiveData: true},
    ).
    Build()

TelemetryOptions 可以禁用工作流构建/运行、执行程序进程、边组或消息发送跨度，并且当设置了 EnableSensitiveData 时可以包含序列化的输入和输出。

观察工作流事件

通过事件流监视工作流执行：

for evt := range run.NewEvents() {
    switch e := evt.(type) {
    case workflow.ExecutorCompletedEvent:
        log.Printf("Executor %s completed", e.ExecutorID)
    }
}

后续步骤

  • Last updated on