服务注册与分布式协调 / 系统课时

排查 Workflow 长时间卡住

排查 Workflow 长时间卡住

Workflow 长时间保持 Running 不一定是故障:它可能正在等 Timer、Signal 或 Activity。有效排查的关键是先看当前执行快照,再沿事件历史末端判断“正常等待、任务未领取、任务执行中还是 Workflow Task 反复失败”,最后才决定是否修复 Worker 或业务逻辑。

学习目标

  • 使用 workflow describe 与事件历史末端判断 Workflow 当前等待点。
  • 区分 Pending Activity、Timer、Signal 等待与 Worker/Task Queue 异常。
  • 根据根因选择恢复动作,并用历史推进和队列状态验证修复结果。

先确认它是否真的卡住

先锁定 Workflow ID、Run ID、Namespace 和 Task Queue。仅凭 Workflow ID 排查可能会命中最新 Run,而不是发生问题的旧 Run;生产故障记录中应保存 Run ID,避免 Continue-As-New、Retry 或重跑后串线。

首先执行 Describe,再查看 Event History。下面的命令不会修改 Workflow,可以作为只读排查入口。

bash
temporal workflow describe \
  --workflow-id "<WORKFLOW_ID>" \
  --run-id "<RUN_ID>" \
  --namespace "<NAMESPACE>"

temporal workflow show \
  --workflow-id "<WORKFLOW_ID>" \
  --run-id "<RUN_ID>" \
  --namespace "<NAMESPACE>"

预期结果

text
<describe 返回该 Run 的执行信息与当前 pending 状态;show 返回按 Event ID 排列的事件历史。实际事件数量、时间与字段随该 Workflow 而不同>

如果状态已经是 Completed、Failed、Canceled、Terminated 或 TimedOut,它不是“仍在卡住”,而是已经关闭,应转去分析关闭原因。只有 Running 才继续沿当前等待点排查。

从事件历史末端做第一次分流

事件历史的末端比“运行了多久”更有诊断价值。重点观察最后几个事件有没有形成“已调度但未开始”“已开始但未完成”或“正常等待”的模式。

历史末端或当前状态 更可能的含义 下一步
WorkflowTaskScheduled 长时间没有 WorkflowTaskStarted Workflow Worker 没有领取任务,或队列容量/路由异常 检查 Workflow Task Queue 的 poller 与 backlog
ActivityTaskScheduled 没有 ActivityTaskStarted Activity Worker 未领取任务 检查 Activity Task Queue、Worker 路由和容量
ActivityTaskStarted 长时间没有完成事件 Activity 正在执行、阻塞或失联 看 Activity 日志、Heartbeat、下游依赖与超时
TimerStarted 且触发时间尚未到 正常 Durable Timer 等待 不要重置或终止,核对预期触发时间
WorkflowTaskCompleted 后没有新命令,代码正在等 Signal/Condition 通常是正常业务等待 核对预期 Signal 是否真的发送到这个 Run
连续出现 WorkflowTaskFailed 或 WorkflowTaskTimedOut Workflow Task 无法稳定完成 查 Worker 日志、非确定性、异常与部署变更

Workflow 长时间卡住的分层诊断路径

重点读取 Pending Activity 与等待语义

workflow describe 中的 Pending Activity 能回答“Activity 还在排队,还是已经被某个 Worker 开始执行”。若长期停在 Scheduled,优先查 Worker 和 Task Queue;若处于 Started,则优先查 Activity 自身、外部服务、线程池/连接池以及 Heartbeat 是否继续上报。

Timer 的语义不同。Temporal 的 Durable Timer 本来就允许 Workflow 在很长时间内不产生业务事件;只要 Timer 的预期触发时间还没到,就不应把它当成故障。Signal 等待也可能表现为历史长时间不增长,因为“尚未收到的 Signal”不会凭空产生历史事件,应结合 Workflow 代码、Query 暴露的业务状态以及调用方发送记录确认。

检查 Task Queue 与 Worker 是否能领任务

Workflow Task 与 Activity Task 即使使用同一个 Task Queue 名称,也属于不同任务类型。排查时分别查看 poller 和 backlog,避免只看到“有 Worker”就误判为两个类型都有人处理。

bash
temporal task-queue describe \
  --task-queue "<TASK_QUEUE>" \
  --namespace "<NAMESPACE>"

预期结果

text
<命令返回该 Task Queue 的 poller 与统计信息,并按任务类型提供可用数据。重点确认近期 poller 是否存在,以及 backlog 数量/年龄是否持续增长;具体显示格式随 CLI 与 Server 版本不同>

没有 poller 时,检查 Worker 是否存活、连接的 Namespace 是否正确、Task Queue 名称是否完全一致,以及 Worker Versioning/部署路由是否把任务送到了没有兼容 Worker 的版本。存在 poller 但 backlog age 持续升高,则更像容量不足,而不是“Worker 完全离线”,应继续看 Worker slot、Activity 延迟和下游吞吐。

按根因修复并验证

如果是 Worker 未领取任务,先恢复正确版本的 Worker 或修复 Namespace、Task Queue、部署路由,再观察原 Workflow 是否自然继续;通常无需重新启动 Workflow。若 Activity 已 Started 但长期无进展,检查它是否仍 Heartbeat、下游调用是否卡死,以及 StartToClose、ScheduleToClose、Heartbeat 超时是否符合业务时长。

如果历史反复出现 Workflow Task 失败,应优先查看对应 Worker 日志。常见原因包括 Workflow 代码抛出未预期异常、非确定性变更、单次 Workflow Task 运行过久,或新版本无法重放旧历史。此时应使用兼容版本恢复处理能力,并通过历史回放或 Worker Versioning 修正部署,而不是反复给 Workflow 发 Signal 试运气。

修复后的验收至少满足三个信号:Event History 出现新的 WorkflowTaskStarted/Completed 或业务事件;原来的 Pending Activity/Task 不再停留在同一状态,或进入符合预期的新 attempt;Task Queue backlog 不再持续恶化。若 Workflow 本应继续运行,它应进入新的合法等待点;若本应结束,则最终进入预期的关闭状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 Workflow 长时间卡住

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通