Go execution trace 为什么看不到自定义任务区域

如果 go tool trace 里看不到自己写的“任务区域”，最常见的原因不是查看器丢数据，而是这段标注没有进入正在采集的 trace，或者 Region 使用的 Context 没有携带 Task。先记住一个判断：Region 描述单个 goroutine 上的一段时间，Task 才是可以借助 Context 关联多个 goroutine 的逻辑操作。

要让自定义任务区域可见，必须在 trace.Start 与 trace.Stop 的窗口内创建标注；跨 goroutine 的场景要把 trace.NewTask 返回的 Context 传下去，并在查看器中进入用户任务或区域相关视图。

本文解决：判断采集入口、Context 传递和查看范围三个环节到底是哪一环出了问题。

速查：Region 看同一 goroutine 的区间；Task 看一类逻辑操作的延迟；Log 只是附着在 Context 上的瞬时事件。

先分清 Task 和 Region 的可见范围

自定义标注有三个层次。trace.WithRegion 或 trace.StartRegion 记录调用它的 goroutine 的时间区间，开始和结束必须落在同一个 goroutine；trace.NewTask 则返回新的 Context 和 Task，可以把一个请求或业务操作的多个 goroutine 归到同一逻辑任务。trace.Log 是带类别和消息的瞬时标记。

因此，下面这类写法容易造成错觉：在主 goroutine 创建了 Region，却在另一个 goroutine 里期待它覆盖异步工作。Region 不会自动跨 goroutine 延伸；异步工作应共享 Task Context，并在实际执行函数内部重新建立 Region。

先确认 trace 文件真的包含用户标注

第二个断点是采集窗口。标准库的用户标注只有在 execution trace 开启期间才会写入文件。测试或命令行程序可以用 go test -trace=trace.out，独立程序则要检查 trace.Start 的错误，并用 defer trace.Stop() 保证收尾。

package main

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

func main() {
    f, err := os.Create("trace.out")
    if err != nil {
        log.Fatal(err) // 文件创建失败时没有可分析的 trace
    }
    defer f.Close() // 先关闭文件，让 trace 数据完整落盘

    if err := trace.Start(f); err != nil {
        log.Fatal(err) // 重复启动或初始化失败时立即停止
    }
    defer trace.Stop() // Stop 会等待剩余 trace 写入完成

    ctx, task := trace.NewTask(context.Background(), "checkout")
    defer task.End() // Task 的结束时间决定该逻辑操作的延迟范围
    trace.WithRegion(ctx, "load-cart", func() {
        // Region 绑定当前 goroutine；异步函数要继续传递 ctx
        loadCart(ctx)
    })
}

func loadCart(ctx context.Context) {
    trace.Log(ctx, "stage", "cart-loaded") // Log 依附于 ctx 携带的 Task
}

这里的关键不是把所有函数都包上标注，而是让标注位于真实的采集区间内。若先执行了业务、后调用 trace.Start，或程序在异步 goroutine 完成前就退出，文件中自然不会出现预期区域。

把自定义任务区域接到正确的 Context

如果区域只在同步调用中出现，先用 WithRegion(ctx, ...) 就够了；如果业务跨 goroutine，创建 Task 后要把返回的 ctx 作为参数传入，而不是重新使用 context.Background()。否则区域仍可能被记录，却不会归属到你正在查找的用户任务。

排查时可以按这个顺序看：一是 trace.Start 是否返回错误；二是 NewTask 的 Context 是否传入真正执行工作的 goroutine；三是 task.End 是否可能过早调用；四是 Region 是否在同一 goroutine 内开始和结束。尤其不要把 task.End 放在启动异步工作后立即执行，否则任务可能已经结束，后续区域就失去预期的任务范围。

查看方式与边界

生成文件后使用 go tool trace trace.out 打开分析工具，再进入与用户任务、区域或 goroutine 关联的视图。不同 Go 版本的界面布局可能变化，但数据关系不变：Task 负责逻辑操作的生命周期，Region 负责单 goroutine 区间，Log 负责瞬时线索。

还要确认你分析的是 execution trace，而不是 pprof 的 CPU、堆或 goroutine profile。后者可以解释热点和资源占用，却不会呈现同一套用户任务区域。长时间运行的服务则应控制采集窗口，必要时使用近期版本提供的 flight recorder 思路，避免生成难以处理的超大文件。

常见误区

• 只创建 Region，却希望它跨 goroutine 自动关联：改用 Task Context，并在每个实际执行 goroutine 中建立区域。
• 把 task.End 当成 goroutine 启动标记：它代表逻辑任务完成，应放在最后一个必要工作完成的位置。
• 用旧 trace 文件验证新代码：文件是一次采集的结果，修改标注后必须重新生成。
• 把界面没看到当成数据没写入：先确认采集入口和时间窗口，再切换到用户任务或区域关联视图。

相关问题

为什么区域名称能看到，但任务延迟没有统计？通常只写了 Region，没有创建并结束 Task；区域是区间标注，不会替代任务生命周期。

异步函数应该传哪个 Context？传 trace.NewTask 返回的子 Context，或继续传递已经携带该 Task 的上游 Context，不要在中途重置为背景 Context。

只想看某个阶段，必须创建 Task 吗？不必。单 goroutine 的阶段用 Region 即可；只有需要跨 goroutine 聚合逻辑操作时，才需要 Task。

按“采集是否开启、Context 是否正确、生命周期是否完整、查看范围是否匹配”四项复查，通常就能定位自定义任务区域消失的真正原因。