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

排查 Non-Determinism 错误

排查 Non-Determinism 错误

Non-Determinism 表示 Worker 在重放历史时,当前 Workflow 代码生成的命令序列与已记录历史无法对应。排查重点不是“哪一行抛异常”,而是找到第一处命令分叉,再用 Replay 复现,并为存量执行保留兼容路径或旧 Worker。

学习目标

  • 根据 Workflow History 找到当前代码与既有命令序列第一次不一致的位置。
  • 使用 Replay 在发布前复现并验证确定性问题。
  • 选择版本分支、Worker Versioning 或旧 Worker,让存量执行安全完成。

先找第一处历史与代码分叉

Temporal 会把 Workflow 执行过程中的关键决定记录进 History。Worker 处理新的 Workflow Task 时会重放这些历史事件,并重新执行 Workflow 代码;只要代码在相同历史输入下生成了不同的 Activity、Timer、Child Workflow 等命令,重放就可能失败。

因此不要从最新日志倒推全部代码。先固定失败的 Workflow ID 和 Run ID,导出对应 History,然后定位报错附近“历史已经记录了什么”和“当前代码准备发出什么”。第一处不一致通常比后续连锁错误更有价值。

Workflow History 与当前代码第一次命令分叉

识别最常见的破坏方式

最直接的原因是发布后改变了命令顺序,例如旧代码先启动 Activity A 再启动 Timer,新代码把 Timer 提前;对于仍在执行的旧 Workflow,重放到这一段时就会与历史不一致。

另一类原因是 Workflow 直接读取重放时可能变化的值,例如标准库当前时间、随机数、进程环境变量、外部文件、网络结果,或依赖不稳定遍历顺序来决定是否调度命令。Workflow 中应使用 SDK 提供的确定性时间和随机/Side Effect 机制,外部 I/O 则放进 Activity。

用 Replay 在本地复现

Replay 的价值是让同一份真实 History 在不继续推进生产 Workflow 的情况下经过当前代码。下面是 Go SDK 中常见的回放片段;它依赖项目已经定义 OrderWorkflow,并提供实现了 SDK log.Logger 接口的 logger,因此这里明确作为片段示例。

go
replayer := worker.NewWorkflowReplayer()
replayer.RegisterWorkflow(OrderWorkflow)

err := replayer.ReplayWorkflowHistoryFromJSONFile(logger, "history.json")
if err != nil {
	return fmt.Errorf("replay failed: %w", err)
}

验证方法是固定同一份 history.json:在故障版本上 Replay 应稳定复现错误;完成修复后,Replay 应返回 nil。如果仍失败,继续以新的第一处分叉为定位点,而不是一次性修改更多代码。

对受影响范围较大的发布,应抽取多份 History 覆盖不同运行阶段,因为某个版本分支可能只在特定路径、定时器阶段或长时间运行的 Workflow 上触发。Replay 通过一份样本,只能证明这一份历史兼容。

用兼容分支保住存量执行

当业务确实需要改变命令顺序,而旧 Workflow 仍会重放到这段代码时,可以用版本分支把旧 History 和新执行分开。下面的片段依赖已注册的 ChargeOrder 与 ReserveStock Activity,展示经典的 workflow.GetVersion 兼容方式。

go
func OrderWorkflow(ctx workflow.Context) error {
	ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
		StartToCloseTimeout: time.Minute,
	})

	version := workflow.GetVersion(
		ctx,
		"order-sequence-v2",
		workflow.DefaultVersion,
		1,
	)

	if version == workflow.DefaultVersion {
		if err := workflow.ExecuteActivity(ctx, "ChargeOrder").Get(ctx, nil); err != nil {
			return err
		}
		return workflow.ExecuteActivity(ctx, "ReserveStock").Get(ctx, nil)
	}

	if err := workflow.ExecuteActivity(ctx, "ReserveStock").Get(ctx, nil); err != nil {
		return err
	}
	return workflow.ExecuteActivity(ctx, "ChargeOrder").Get(ctx, nil)
}

旧 History 在没有新版本 Marker 的情况下继续走旧顺序,新启动的执行则记录版本并走新顺序。验证时必须同时 Replay 旧 History,并新启动一条 Workflow 检查新路径;只验证其中一边,仍可能留下新的确定性问题。

如果团队已经使用 Worker Versioning 或明确的部署版本路由,也可以让旧 Workflow 继续由兼容旧代码的 Worker 处理,新执行进入新版本。关键原则不变:同一份 History 必须始终能找到与它兼容的 Workflow 代码。

什么时候应该回退旧 Worker

若刚发布后大量长流程同时报 Non-Determinism,而修复分支还没有经过足够 Replay 样本验证,最稳妥的止血通常是恢复能够重放这些 History 的旧 Worker,并停止让不兼容版本继续接管受影响执行。

只有在确认受影响 Workflow 已经完成、迁移或由兼容版本稳定接管后,才能清理旧代码路径。清理前再次用代表性的旧 History 做 Replay,并观察 Workflow Task 是否持续推进、Non-Determinism 错误是否归零;“新启动的 Workflow 正常”并不能证明存量执行已经安全。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查 Non-Determinism 错误

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

登录哪都通