一個包含 12 個步驟、兩個條件分支和一個迴圈的 workflow,在迴圈第三次迭代的第二個子步驟失敗了。錯誤訊息顯示「unexpected response format」。你該從哪裡開始查起?
沒有詳細的執行資料,你只能猜測。有了執行追蹤,你就能確切看到發生了什麼——每個輸入、每個輸出、每個時間邊界、每次重試嘗試——以鏡像 workflow 結構的階層式檢視呈現。
執行追蹤捕捉了什麼
每次 workflow 執行都會產生一個執行追蹤:一個鏡像 workflow 執行圖的 span 樹。每個 span 記錄:
- 步驟識別 — 哪個步驟,包含 ID 和名稱
- 時間 — 開始時間、結束時間和持續時間(毫秒)
- 輸入 — 模板解析後傳遞給步驟的確切值
- 輸出 — 步驟產生的結構化輸出(或拋出的錯誤)
- 重試嘗試 — 如果步驟有重試,每次嘗試都會記錄其錯誤和下次嘗試前的退避延遲
- 巢狀上下文 — 條件的哪個分支、迴圈的哪次迭代、平行步驟的哪個分支
階層式結構
追蹤樹精確遵循 workflow 的結構:
Workflow Run
├── Step 1: Research prospect (recipe) — 2.3s, success
├── Step 2: Qualify lead (recipe) — 1.8s, success
├── Step 3: Condition (score >= 70)
│ └── Then branch
│ ├── Step 3a: Parallel
│ │ ├── Branch A: Draft email — 3.1s, success
│ │ └── Branch B: Draft LinkedIn message — 2.7s, success
│ └── Step 3b: Review (approval) — waiting
└── Step 4: Archive (skipped — condition took then-branch)條件分支顯示採用了哪條路徑以及原因。迴圈顯示每次迭代及其項目和子步驟結果。平行分支顯示並行執行的個別時間。
三層可觀測性
執行追蹤是三個互補可觀測性層之一:
執行追蹤(Firestore)是詳細的單次執行檢查工具。它們支援執行檢查器 UI,專為除錯個別執行而設計。每次執行都會產生追蹤,追蹤會在執行記錄的生命週期內保留。
Prometheus metrics 追蹤整體營運健康狀況:總執行次數、成功率、持續時間百分位數和錯誤計數。這些資料提供儀表板和警報——「workflow X 的成功率在過去一小時內降至 95% 以下」。
OpenTelemetry spans 提供跨服務邊界的分散式追蹤。withSpan() wrapper 為任何被檢測的程式碼路徑建立 spans,攜帶 workflow 和步驟的 metadata。這些與任何相容 OTel 的後端(Jaeger、Datadog、Honeycomb)整合,進行跨系統追蹤關聯。
使用追蹤進行除錯
找出失敗點
開啟執行詳情頁面並展開追蹤樹。失敗的步驟會被突顯。點擊失敗的步驟查看其確切輸入和錯誤訊息。將輸入與預期進行比較——問題通常是上游步驟產生了非預期的輸出,然後傳遞給下游步驟。
發現模板解析問題
每個步驟的追蹤顯示解析後的輸入值——模板替換之後。如果步驟期望 {{step.research.company_name}} 但得到 undefined,追蹤會顯示實際解析的值。檢查被引用的步驟是否產生了預期的輸出欄位。
識別效能瓶頸
按持續時間排序以找出最慢的步驟。當相似步驟耗時 2 秒,某個步驟卻耗時 15 秒時,可能是遇到速率限制、使用了比必要更昂貴的模型,或處理了意外龐大的輸入。
除錯重試行為
當步驟在成功(或永久失敗)前重試時,追蹤顯示每次嘗試:觸發重試的錯誤、退避延遲,以及下次嘗試的結果。常見模式:暫時性的 429 速率限制(退避後重試成功)、持續性的 400 錯誤(所有重試都因相同錯誤失敗——修正輸入,而非重試次數)。
追蹤是自動的
你不需要配置追蹤。每次 workflow 執行都會產生追蹤,每個步驟都被檢測,追蹤以非同步方式持久化(fire-and-forget),因此不會減慢執行速度。當你開啟詳情檢視時,執行檢查器會按需讀取追蹤。
執行追蹤適用於所有方案。Prometheus metrics 和 OpenTelemetry 整合僅適用於企業版。深入了解 workflows 或 開始免費試用。