可觀測性可讓您深入瞭解執行期間工作流程的內部狀態和行為。 這包括日誌記錄、指標和追蹤功能，可協助監控和偵錯工作流程。
Tip
可觀察性是整個框架的功能，並不限於工作流程。 更多資訊請參見 可觀察性。
除了標準的 GenAI 遙測之外，Agent Framework 工作流程也會發出額外的跨度、記錄與計量，以提供對工作流程執行更深入的深入解析。 這些可觀察性功能幫助開發者了解訊息的流程、執行器的效能以及可能發生的任何錯誤。
啟用可觀測性
請參閱 啟用可觀察性 ，了解如何在您的應用程式中啟用可觀察性。
請參閱 啟用可觀察性 ，了解如何在您的應用程式中啟用可觀察性。
工作流程跨度
以下是在工作流程執行期間發出的跨度：
| 跨度名稱 | 說明 |
|---|---|
workflow.build |
針對每個工作流程組建發出。 |
workflow.session |
外層範圍代表工作流程執行的整個生命週期，從開始到停止或錯誤。 |
workflow_invoke |
針對工作流程工作階段內的每個輸入到停止週期發出。 |
executor.process {executor_id} |
每個執行緒在處理訊息時都會發出。 執行者 ID 會附加在 span 名稱後面。 |
edge_group.process |
針對處理訊息的每個邊緣群組發出。 |
message.send |
針對從一個執行程式傳送到另一個執行程式的每則訊息發出。 |
以下是在工作流程執行期間發出的跨度：
| 跨度名稱 | 說明 |
|---|---|
workflow.build |
針對每個工作流程組建發出。 |
workflow.run |
針對每次工作流程執行發出。 |
executor.process {executor_id} |
每個執行緒在處理訊息時都會發出。 執行者 ID 會附加在 span 名稱後面。 |
edge_group.process {edge_group_type} |
針對處理訊息的每個邊緣群組發出。 邊緣群組類型會附加在範圍名稱後面。 |
message.send |
針對從一個執行程式傳送到另一個執行程式的每則訊息發出。 |
以下是在工作流程執行期間發出的跨度：
| 跨度名稱 | 說明 |
|---|---|
workflow.build |
針對每個工作流程組建發出。 |
workflow.session |
代表工作流程執行工作階段生命週期的外部跨度。 |
workflow_invoke |
針對工作流程工作階段內的每個輸入到停止週期發出。 |
executor.process {executor_id} |
每個執行緒在處理訊息時都會發出。 執行者 ID 會附加在 span 名稱後面。 |
edge_group.process |
針對處理訊息的每個邊緣群組發出。 |
message.send |
每當有訊息從一個執行器傳送到另一個執行器時發出。 |
跨度屬性
跨度攜帶了可提供有關該作業之額外內容的屬性。 以下屬性會設定於工作流程範圍：
| Attribute | 跨度 | 說明 |
|---|---|---|
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 | 跨度 | 說明 |
|---|---|---|
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 | 跨度 | 說明 |
|---|---|---|
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 |
執行人身份證。 |
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 |
任意誤差的跨度 | 例外狀況訊息。 |
範圍事件
跨度事件是附著於跨度上的結構化日誌條目，提供每個跨度內關鍵時刻的時間軸。
| 活動名稱 | 跨度 | 說明 |
|---|---|---|
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 |
當工作流程調用遇到錯誤時會發出。 |
| 活動名稱 | 跨度 | 說明 |
|---|---|---|
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 |
當工作流程執行遇到錯誤時會產生。 |
| 活動名稱 | 跨度 | 說明 |
|---|---|---|
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 設定為以下其中之一：
| 現況 | 說明 |
|---|---|
delivered |
訊息已送達目標執行者。 |
dropped type mismatch |
目標執行者無法處理訊息類型。 |
dropped target mismatch |
訊息指定了一個與此邊緣不符的目標。 |
dropped condition false |
邊緣路由條件被判定為不成立。 |
exception |
在邊緣處理過程中發生了例外。 |
buffered |
訊息已被緩衝，正在等待其他訊息以進行收合傳送 (fan-in)。 |
edge_group.delivered布林屬性提供快速檢查訊息是否成功送達。
遙測配置
工作流遙測可以透過工作流建構器的WithOpenTelemetry擴充方法啟用。
WorkflowTelemetryOptions 類別提供了對發出哪些跨度的精細控制：
| Option | Default | 說明 |
|---|---|---|
EnableSensitiveData |
false |
包含原始輸入、輸出及訊息內容，並以span屬性表示。 |
DisableWorkflowBuild |
false |
禁用 workflow.build 範圍。 |
DisableWorkflowRun |
false |
禁用 workflow.session 和 workflow_invoke 範圍。 |
DisableExecutorProcess |
false |
禁用 executor.process 範圍。 |
DisableEdgeGroupProcess |
false |
禁用 edge_group.process 範圍。 |
DisableMessageSend |
false |
禁用 message.send 範圍。 |
Warning
啟用敏感資料會將原始訊息內容、執行器輸入與輸出納入遙測資料中。 僅在安全環境下啟用，且遙測資料受到適當保護。
工作流程遙測可透過全域 enable_instrumentation() 功能啟用。 啟用檢測功能時，所有工作流程跨度都會自動發出。 此 configure_otel_providers() 函式可用於設定追蹤、指標與日誌的匯出器。
Warning
檢視您的遙測管線設定，確保在匯出追蹤時敏感資料受到適當保護。
工作流程可觀察性
工作流程遙測可以透過工作流程建構器啟用 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)
}
}