Go runtime/trace 如何定位 goroutine 阻塞：trace.NewTask、Logf 与时间线筛选

线上接口偶发卡住时，单看日志往往只看到“请求开始”而没有“请求结束”。Go 的 runtime/trace 可以把一次逻辑任务、任务内的标记和 goroutine 调度时间线放在同一份 trace 文件里，适合回答“卡在任务哪一段”这个问题。关键是先用 trace.NewTask 建立边界，再用 trace.Logf 记录可检索的阶段，最后用任务延迟和阻塞区间交叉验证。

先把业务请求包装成 task，并保证 task.End() 一定执行；trace 只能告诉你时间线上的等待与调度事实，具体根因还要回到阶段日志和代码。

请求卡住时，先把“这一单”标成 task

假设一个批处理接口会启动后台 goroutine 读取两段数据，偶尔在客户端等待很久。没有任务边界时，执行追踪里会混着很多 goroutine；有了 task，分析工具可以按任务类型聚合延迟。taskType 不要拼接订单号，保持为少量稳定类别，例如 batch-request，否则筛选结果会失去意义。

这张图对应本节的调用链：先启动运行时追踪，再创建任务；任务 context 传给阶段函数，最后由 task.End 收口。

用最小采集器留下 trace.out

采集器应该只包住要复现的那次实验，避免把无关的长时间运行都写进文件。trace.Start 接受一个 io.Writer，启动失败时要立刻关闭文件并返回；成功后用 defer trace.Stop() 保证函数离开时收尾。

package main

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

func main() {
    f, err := os.Create("trace.out")
    if err != nil {
        panic(err)
    }
    defer f.Close()
    if err := trace.Start(f); err != nil {
        panic(err)
    }
    defer trace.Stop()

    ctx, task := trace.NewTask(context.Background(), "batch-request")
    defer task.End()
    trace.Logf(ctx, "phase", "blocked")
    loadChunk(ctx)
}

func loadChunk(ctx context.Context) {
    trace.Logf(ctx, "phase", "task latency")
}

这段程序的可核对节点是 trace.Start、trace.NewTask、trace.Logf、task.End。它不会凭空制造业务请求，只是在现有代码周围补上追踪边界。

跨 goroutine 传递 context，别只传一个裸函数

NewTask 返回的 context 才携带任务信息。把它传入 goroutine 后，在子 goroutine 中调用 trace.Logf，阶段日志仍会归到同一个 task；如果重新使用 context.Background()，日志就失去这条关联。

ctx, task := trace.NewTask(ctx, "batch-request")
defer task.End()

done := make(chan struct{})
go func() {
    defer close(done)
    trace.Logf(ctx, "phase", "goroutine")
    loadChunk(ctx)
}()

采集结果里如果 task latency 明显大于正常请求，先看 goroutine 是否长期处于等待，再对照 phase 日志出现的先后。图中的状态转换只表达“任务从运行进入 blocked，再回到结束”，不把等待原因强行归类。

从时间线筛选证据，而不是凭颜色猜根因

复现后可以用 Go 自带的 trace 分析入口查看 trace.out。先按 batch-request 找到任务，再看 trace.Logf 记录的 phase 顺序和 goroutine 阻塞区间。若阻塞发生在日志“读取数据”之后，才值得继续检查读取函数对应的网络、锁或下游调用；若 task 在某个阶段前就结束，说明猜测方向不对。

这里有三个容易混淆的边界：

• task latency 不是接口耗时仪表盘。它反映 task 创建到第一次 task.End 的时间，采样范围和业务统计口径可能不同。
• blocked 不是根因名称。它说明 goroutine 在某段时间没有继续运行，原因仍需结合代码和其他证据。
• 日志类别要稳定。phase 这类少量类别适合筛选，不要把无限变化的标识拼进 category。

收尾检查：采集结束后再下结论

先确认 trace.Stop 已返回、trace.out 文件大小稳定，再打开分析页面。把一次异常任务与一次正常任务并排比较：异常样本看起来是等待更长，还是阶段顺序改变？只有当时间线、trace.Logf 阶段和业务代码指向同一位置，才可以把它列为修复候选。

相关问题

trace.NewTask 可以在多个 goroutine 中使用吗？

可以，把返回的 context 传给参与同一逻辑任务的 goroutine；Task 的结束动作要明确由一个收口位置负责。

trace.Logf 会替代普通业务日志吗？

不会。它服务于执行追踪中的阶段关联，普通日志仍负责长期留存、检索和业务审计。

只看到 blocked 就能判断是锁竞争吗？

不能。blocked 只是一种时间线现象，还要结合代码位置、阶段日志和锁或下游调用的独立证据。

小结

定位 goroutine 偶发阻塞时，先用 trace.NewTask 画出任务边界，用 trace.Logf 留下少量稳定阶段，再用 task.End 收口。trace.out 呈现的是调度和任务时间线；它最有价值的用法，是把“感觉卡住了”变成可复查的时间区间，而不是替你直接宣布根因。