可觀測性可讓您深入瞭解執行期間工作流程的內部狀態和行為。 這包括日誌記錄、指標和追蹤功能，可協助監控和偵錯工作流程。
小提示
可觀察性是整個框架的功能，並不限於工作流程。 更多資訊請參見 可觀察性。
除了標準 的 GenAI 遙測之外，代理框架工作流程還會發出額外的跨度、日誌和指標，以提供對工作流程執行的更深入的見解。 這些可觀察性功能幫助開發者了解訊息的流程、執行器的效能以及可能發生的任何錯誤。
啟用可觀測性
請參閱 啟用可觀察性 ，了解如何在您的應用程式中啟用可觀察性。
請參閱 啟用可觀察性 ，了解如何在您的應用程式中啟用可觀察性。
工作流程跨度
在工作流程執行過程中會發出以下區間：
| 跨度名稱 | Description |
|---|---|
workflow.build |
每次工作流程建置都會產生。 |
workflow.session |
外層範圍代表工作流程執行的整個生命週期，從開始到停止或錯誤。 |
workflow_invoke |
在工作流程會話中，每個輸入到停止週期都會輸出。 |
executor.process {executor_id} |
每個執行緒在處理訊息時都會發出。 執行者 ID 會附加在 span 名稱後面。 |
edge_group.process |
每個邊緣群組在處理訊息時都會發出訊號。 |
message.send |
每發送一則從執行人發送給另一執行人的訊息。 |
在工作流程執行過程中會發出以下區間：
| 跨度名稱 | Description |
|---|---|
workflow.build |
每次工作流程建置都會產生。 |
workflow.run |
每次工作流程執行都會產生。 |
executor.process {executor_id} |
每個執行者處理訊息時都會發出。 執行者 ID 會附加在 span 名稱後面。 |
edge_group.process {edge_group_type} |
針對每個處理訊息的邊緣群組發出訊號。 邊緣群組類型會附加在範圍名稱後面。 |
message.send |
每當一則訊息從一個執行單元傳送給另一個執行單元時，將會觸發一個事件。 |
跨度屬性
跨度帶有屬性，提供關於操作的額外背景資訊。 以下屬性會設定於工作流程範圍：
| 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 |
邊緣路由條件被判定為不成立。 |
exception |
在邊緣處理過程中發生了例外。 |
buffered |
訊息已被緩衝，等待其他訊息匯入（fan-in）。 |
edge_group.delivered布林屬性提供快速檢查訊息是否成功送達。
遙測配置
工作流遙測可以透過工作流建構器的WithOpenTelemetry擴充方法啟用。 該 WorkflowTelemetryOptions 類別提供細緻的控制，以決定哪些範圍被發射：
| Option | 預設值 | Description |
|---|---|---|
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 區段。 |
警告
啟用敏感資料會將原始訊息內容、執行器輸入與輸出納入遙測資料中。 僅在安全環境下啟用，且遙測資料受到適當保護。
工作流程遙測可透過全域 enable_instrumentation() 功能啟用。 啟用儀器功能時，所有工作流程區間都會自動發出。 此 configure_otel_providers() 函式可用於設定追蹤、指標與日誌的匯出器。
警告
檢視您的遙測管線設定，確保在匯出追蹤時敏感資料受到適當保護。