Go runtime/trace 任务区域如何标记异步链路：Log、Region 与查看顺序

异步请求一旦跨过 goroutine，单看函数耗时就很难回答“这一段等待到底属于哪个请求”。Go 的 runtime/trace 可以把一次请求放进 Task，再用 Log 记录关键事件，用 NewRegion 标出阶段；采集结束后，事件之间的关系仍然能沿着同一条任务链查看。

先准备一个能跨协程运行的实验

本实验只完成一个任务：模拟订单请求经过“读取缓存、异步计算、写回结果”三个阶段，并把它们放入同一个 trace Task。使用 Go 模块即可，不需要额外服务。

mkdir trace-regions && cd trace-regions && go mod init example.com/trace-regions

新建 main.go，先把采集文件打开。trace.Start 成功后才继续创建任务；用 defer trace.Stop() 收尾，可以避免中途返回时忘记写完 trace。

package main
import ("context"; "fmt"; "os"; "runtime/trace"; "sync"; "time")
func main() { file, err := os.Create("request.trace"); if err != nil { panic(err) }; if err := trace.Start(file); err != nil { _ = file.Close(); panic(err) }; defer func(){ trace.Stop(); _ = file.Close() }(); ctx, task := trace.NewTask(context.Background(), "order-request"); defer task.End(); trace.Log(ctx, "request", "accepted"); var wg sync.WaitGroup; wg.Add(1); go func(){ defer wg.Done(); runStages(ctx) }(); wg.Wait(); fmt.Println("trace written: request.trace") }
func runStages(ctx context.Context) { cache := trace.StartRegion(ctx, "cache-read"); time.Sleep(8*time.Millisecond); cache.End(); trace.Log(ctx,"cache","hit"); compute := trace.StartRegion(ctx,"async-compute"); time.Sleep(12*time.Millisecond); compute.End(); trace.Log(ctx,"result","ready"); persist := trace.StartRegion(ctx,"result-write"); time.Sleep(6*time.Millisecond); persist.End() }

把 Task、Region 和 Log 放在正确的位置

trace.NewTask 返回带任务标识的上下文和任务句柄。把这个上下文传给新 goroutine，后续的 Region 与 Log 才能归到同一次逻辑操作中。关键不是变量名，而是上下文不能被替换成没有任务关系的新上下文。

Region 适合表示有开始和结束的阶段，所以要在阶段入口调用 trace.StartRegion，在所有正常路径和提前返回路径上调用 End。Log 是瞬时事件，适合写“缓存命中”“结果就绪”这类状态变化，不要拿它代替阶段边界。

func loadAndCompute(ctx context.Context) error { region := trace.StartRegion(ctx, "load-config"); defer region.End(); trace.Log(ctx, "source", "local-cache"); if err := loadConfig(); err != nil { trace.Log(ctx, "load", "failed"); return err }; return nil }

验收点很明确：无论 loadConfig 成功还是返回错误，load-config 都应有完整的开始和结束边界；失败只作为 Log 事件出现，不会把错误路径误判成成功阶段。

运行采集并核对输出

运行程序后，项目目录应出现非空的 request.trace。先核对文件存在，再交给 Go 自带的 trace 工具查看：

go run . && test -s request.trace && go tool trace request.trace

打开 trace 后，先按任务找到 order-request，再按时间顺序查看 cache-read、async-compute 和 result-write。如果找不到同一任务下的阶段，优先检查上下文是否传进了 goroutine；如果阶段有开始没有结束，检查是否漏掉了 End。

用两个小实验确认标记没有误导自己

把异步阶段拆成两个 goroutine

让缓存读取和结果写回分别运行在不同 goroutine，但仍传入同一个 Task 上下文。这样能验证任务关系不等于单个 goroutine；它表达的是同一个逻辑操作。

故意制造提前返回

让 loadConfig 返回错误，观察 defer region.End() 是否仍然闭合阶段，再用 Log 记录失败原因。这个实验能抓住最常见的缺陷：正常路径有结束，错误路径没有结束。

清理文件与总结

rm -f request.trace

实际排查时，先用 Task 划出一次请求的边界，再用 Region 表达有持续时间的阶段，最后用 Log 补充离散状态。三者职责分开，trace 才能回答“哪个请求、哪个阶段、发生了什么”。

相关问题

Region 可以替代所有耗时统计吗？

不可以。Region 是追踪标记，适合解释一次 trace 中的阶段关系；长期聚合的延迟、吞吐和错误率仍应由指标系统负责。

为什么 Log 里不应该塞整段业务对象？

Log 会增加 trace 体积，也可能把隐私字段带入采集文件。只记录能帮助判断状态的短值，例如命中、失败或就绪。

采集结束前能直接读取 trace 文件吗？

不建议。先让 trace.Stop 完成，再关闭文件，之后再打开查看，才能避免拿到未完整写入的采集结果。