Go runtime/trace 怎样按任务标记跟踪区间

我第一次给一条跨 goroutine 的请求链加执行跟踪时，最容易犯的错是把所有耗时点都写成日志。结果日志很多，却看不出“这一批工作”何时开始、哪些 goroutine 属于同一个操作。runtime/trace 的 task、region 和 Log 分工不同：task 表示一项逻辑操作，region 表示某个 goroutine 内的一段区间，Log 只补充一个离散事件。

官方资料：https://pkg.go.dev/runtime/trace

如果你的问题是“同一个请求拆到多个 goroutine 后，执行跟踪里怎样仍然按业务任务聚合”，推荐从 trace.NewTask 开始，再把返回的 Context 传给协作 goroutine；不要把 task 当成单个函数的计时器。

先判断该用 task、region 还是 Log

排查现场可以先做一个简单判断：需要跨 goroutine 观察一项逻辑工作，用 task；只想标出当前 goroutine 的连续代码区间，用 region；需要记录“遇到某个分支”或“拿到某个业务标识”，用 Log。三者可以叠加，但不应该把每个循环迭代都变成一种新的标记类型。

官方文档特别强调，region 的开始和结束必须在同一个 goroutine 中，并且同一 goroutine 内的 region 要保持嵌套。task 则通过 Context 让分析工具识别参与同一逻辑操作的 goroutine。

把一次逻辑操作放进 Context

下面的示例把订单处理抽成一个 task。代码只演示标记关系，真正的业务函数可以替换成查询、计算或 RPC 调用。

package main

import (
    "context"
    "runtime/trace"
)

func handle(ctx context.Context, orderID string) {
    // NewTask 返回携带任务信息的新 Context，供后续 goroutine 继续使用。
    taskCtx, task := trace.NewTask(ctx, "order.process")
    defer task.End() // 统一在任务收尾处结束，避免提前结束统计区间。

    trace.Log(taskCtx, "order", orderID) // 只记录少量可筛选的业务标识。

    done := make(chan struct{})
    go func() {
        defer close(done)
        trace.WithRegion(taskCtx, "load-data", func() {
            loadData(taskCtx, orderID)
        }) // region 在创建它的 goroutine 内闭合。
    }()

    trace.WithRegion(taskCtx, "assemble-result", func() {
        assembleResult(taskCtx, orderID)
    })
    

这里真正重要的不是函数名，而是三条关系：taskCtx 被传入 goroutine；每个 region 在所属 goroutine 内结束；task.End 等所有协作工作结束后再调用。若 goroutine 仍在运行就结束 task，跟踪里的任务延迟会被截短。

区间标记的粒度和结束方式

对可以重复出现的阶段，使用稳定的 regionType，例如 load-data、assemble-result。region 类型过多会让过滤和聚合变得困难；订单号这类动态值更适合放进 trace.Log，而不是拼进 region 类型。

func decode(ctx context.Context, data []byte) error {
    // StartRegion 适合需要显式控制生命周期的代码段。
    region := trace.StartRegion(ctx, "decode-payload")
    defer region.End() // 必须在当前 goroutine 中结束，且保证异常路径也能闭合。

    return decodePayload(data)
}

func decodePayload([]byte) error { return nil }

简单区间也可以直接使用 trace.WithRegion(ctx, "decode-payload", fn)。如果区间可能提前返回或出现错误，优先用 defer 结束，避免只在成功分支调用 End。

从 go test 到 go tool trace 怎么接上

测试和基准可以直接让 go test 写出跟踪文件：

# 为当前包的测试写出执行跟踪文件。
go test -trace=trace.out ./...

# 用 Go 自带工具打开跟踪文件，查看任务、区间和运行时事件。
go tool trace trace.out

独立程序则可以把输出文件交给 trace.Start，在程序退出前调用 trace.Stop。生产排障时，建议先在测试或短时灰度中确认标记粒度，再决定是否长期保留相关代码；跟踪是诊断工具，不是业务日志替代品。

如果看不到预期任务，优先检查 Context 是否真的传入了协作 goroutine，以及 task.End 是否早于最后一段工作。若区间报错或结构异常，再检查同一 goroutine 中 region 的嵌套关系。

常见问题

region 能在另一个 goroutine 调用 End 吗？不能。用 StartRegion 创建的 region 必须在同一个 goroutine 结束；跨 goroutine 的逻辑关联应使用 task。

Log 可以记录任意高基数 ID 吗？可以记录必要的消息，但 category 和 region/task 类型应保持有限、稳定。高频动态信息不要无限扩展标记类型。

task 一定要覆盖整个请求吗？不一定。它应覆盖你需要观察的逻辑操作；范围过大难定位，范围过小又失去跨 goroutine 聚合价值。

我的取舍是：先用一个稳定 task 描述业务动作，再用少量 region 标出阶段，最后用 Log 补充可筛选信息。这样执行跟踪既能回答“这项工作整体花了多久”，也能继续定位“是哪一段 goroutine 内的区间拖慢了它”。