Go trace 怎样关联任务阶段

Go trace 关联任务阶段，最小写法是先用 trace.NewTask 得到携带任务信息的新 context，再把这个 context 传给各阶段的 trace.WithRegion。逻辑任务可以跨多个 goroutine；每个 region 的开始和结束则必须在同一个 goroutine 中。等相关子工作完成后调用 task.End，才能让任务区间符合你想观察的业务范围。

官方地址：https://pkg.go.dev/runtime/trace；阅读工具说明：https://pkg.go.dev/cmd/trace。下面只讨论任务标记与阅读边界，示例和采集命令均未执行，不提供虚构耗时、压测结果或 trace 截图。

先定义要观察的任务与阶段

假设一次文本处理包含拆分、规范化和拼接，只知道总耗时还不能判断时间属于哪个业务阶段。第一步不是随意包住所有函数，而是定义一次 label-job 任务，以及 split、normalize、join 三个稳定的阶段名。阶段名代表工作类型，不要为每个请求拼接一个新名字。

没有采集数据时，基线应写成待测问题：任务耗时分布怎样，哪个阶段的墙钟区间更长，长区间里是执行还是等待？这些问题不能预先填入“优化前 100 毫秒、优化后 20 毫秒”。标记本身增加的是可解释性，不能当成加速动作。

用 task context 把阶段标记关联起来

下面保存为 stage.go，使用独立的 stagedemo 包。重点是使用 NewTask 返回的 ctx，而不是继续给 region 传原始 parent。后者可能没有当前任务信息，阶段虽然存在，却未按预期关联到本次任务。

package stagedemo

import (
    "context"
    "runtime/trace"
    "strings"
)

// Run 把一次文本处理关联为任务；返回前等待异步阶段结束。
func Run(parent context.Context, input string) string {
    ctx, task := trace.NewTask(parent, "label-job")
    defer task.End()

    var fields []string
    trace.WithRegion(ctx, "split", func() {
        fields = strings.Fields(input) // 只标记当前 goroutine 中的这段工作。
    })

    ready := make(chan []string, 1)
    go func(taskCtx context.Context) {
        var upper []string
        trace.WithRegion(taskCtx, "normalize", func() {
            upper = make([]string, len(fields))
            for i, field := range fields {
                upper[i] = strings.ToUpper(field)
            }
        })
        ready 

WithRegion 的作用域就是给定函数执行的那段区间，它适合边界集中、能够用闭包表达的小阶段。需要在现有函数内分开写开始和结束时，可以使用 StartRegion，并在同一个 goroutine 内安排 End。不要为了跨 goroutine 表达同一个操作，把 region 对象传给另一个 goroutine 结束。

task.End 只结束追踪标记，不会取消 context、停止 goroutine 或帮你等待子任务。这个示例通过 ready 通道等待 normalize 完成；如果真实任务还有其他子工作，必须把它们的完成协议也纳入任务生命周期。

异步阶段必须传 context 并等待收尾

normalize 位于子 goroutine，但创建和结束该 region 的代码都在子 goroutine 内。传入的是 ctx，关联任务跨越 goroutine，而不是把某个 region 拉长到另一条 goroutine 上。这是 task 与 region 最值得记住的区别。

示例中的 fields 在启动 goroutine 后不再修改，结果通过通道交回。真实业务仍要按自己的数据所有权进行同步；trace 标记不会为普通变量增加锁。这里也没有取消功能，若要支持取消，应另行设计任务处理和通道等待的取消分支，不能把追踪用 context 误认为自动完成了取消逻辑。

采集与对照应保持同一业务负载

在同目录保存 stage_test.go。下面测试只核对功能输出，并提供一条能够触发任务的测试入口；它不是性能基准。

package stagedemo

import (
    "context"
    "testing"
)

// TestRun 供 go test 的 trace 采集使用，不在测试里重复 trace.Start。
func TestRun(t *testing.T) {
    got := Run(context.Background(), "alpha beta")
    if got != "ALPHA-BETA" {
        t.Fatalf("输出不符合预期: %q", got)
    }
}

在已有 go.mod 的该包目录中，读者可以执行以下命令。没有模块时需先在自己的演示目录初始化合适的模块；文件中不要混入另一个包名。

# 运行指定测试并采集，count=1 避免复用缓存结果。
go test -run '^TestRun$' -count=1 -trace=task.trace .
# 读取刚生成的追踪文件；界面以本机 Go 工具链为准。
go tool trace task.trace

本例由 go test 负责启动采集，不要在测试里再次 trace.Start。独立程序也能用 trace.Start 和 trace.Stop 管理采集，但应与测试入口方案二选一。没有启用采集，单纯添加 task 与 region 不会自动生成 task.trace。

短字符串示例只用于认识关联机制，无法支撑性能结论。要比较真实任务，应固定输入规模、并发、工具链和采样范围，再分别记录任务耗时分布、阶段区间以及调度或阻塞证据。改动前后都采集，才能谈结果差异；追踪本身也有开销，不能把带追踪和不带追踪的两次耗时直接当成业务优化幅度。

读图结论与常见边界

任务时长与 CPU 时间不是同一指标。并发阶段可能重叠，嵌套 region 也包含子区间，所以不要把所有 region 的耗时相加当作端到端延迟。一个阶段区间很长，应继续看其间的运行、阻塞和调度信息，再提出瓶颈假设。

采样窗口如果只包含任务的一部分，就不能把不完整标记当成完整任务统计。任务要有明确的开始与结束，采集范围也要覆盖你想研究的工作；不能根据一次短 trace 断言所有请求的尾延迟原因。

为什么能看到阶段却找不到对应任务？

先看传入的是否为 NewTask 返回的 ctx，以及子函数是否把它换成了 Background。相同阶段名不等于同一个任务，任务关联依赖 context 中的标记信息。

日志需要把业务数据都写进去吗？

不需要。确有区分需求时可添加少量受控 Log 信息，但不要把 token、用户原文、私有路径或大量高基数字符串写入追踪文件。文件应按诊断材料管理访问范围。

task.End 能结束所有子 goroutine 吗？

不能。它不是 WaitGroup，也不是 cancel。先通过业务同步机制等待应归属该任务的工作结束，再结束任务标记。

把 task 作为逻辑关联单位，把 region 作为单个 goroutine 的阶段区间，把业务同步作为生命周期约束，就能让追踪记录回答具体问题，而不是只增加一组看似详细的标签。