一个包含 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 或 开始免费试用。