可观测性提供有关执行期间工作流的内部状态和行为的见解。 这包括帮助监视和调试工作流的日志记录、指标和跟踪功能。
小窍门
可观测性是一项框架范围的功能，不限于工作流。 有关详细信息，请参阅 可观测性。
除了标准 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 |
针对从执行程序发送到另一个执行程序的每个消息发出。 |
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 |
传递结果（请参阅 边缘组传递状态）。 |
跨度事件
跨度事件是附加到跨度的结构化日志条目，提供每个跨度内关键时刻的时间线。
| 事件名称 | 跨度 | 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 |
工作流运行遇到错误时发出。 |
跨度之间的链接
当执行程序向另一个执行程序发送消息时，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 span 元素。 |
DisableEdgeGroupProcess |
false |
禁用 edge_group.process 范围。 |
DisableMessageSend |
false |
禁用 message.send 跨度。 |
警告
启用敏感数据会导致原始消息内容、执行程序输入和执行程序输出包含在遥测中。 仅在遥测数据受到适当保护的安全环境中启用此功能。
通过全局 enable_instrumentation() 函数启用工作流遥测。 启用监控后，将自动记录所有工作流跨度。 该 configure_otel_providers() 函数可用于为跟踪、指标和日志设置导出程序。
警告
查看遥测管道配置，以确保在导出跟踪时适当保护敏感数据。