Go runtime/trace.StartRegion 怎样标记关键代码区间

如果已经用 runtime/trace.Start 打开 Go execution trace，想把某一段业务代码标成可识别的区间，可以调用 trace.StartRegion(ctx, "regionType")。它返回 *trace.Region，最稳妥的写法是立刻用 defer region.End() 收尾。需要记住三条边界：Region 必须在启动它的同一个 goroutine 中结束；同一 goroutine 内的 region 要按嵌套顺序结束；跨 goroutine 的逻辑操作应考虑 trace.NewTask，而不是把 Region 交给另一个 goroutine。

这类标记描述的是“这段代码在 trace 中属于哪个时间区间”，不等于性能结论本身。真正的耗时判断仍要结合 trace 数据和业务上下文。

把 StartRegion 放到需要观察的代码边界

StartRegion 适合包住一个有明确开始和结束点的同步函数。下面的示例同时展示 trace 文件的启动与关闭；示例只说明 API 的组织关系，不代表已经在本机运行过。

package main

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

func main() {
    f, err := os.Create("trace.out")
    if err != nil {
        log.Fatal(err)
    }
    // 文件是 trace 的输出目标，退出前要关闭文件资源。
    defer func() {
        if err := f.Close(); err != nil {
            log.Print(err)
        }
    }()

    // Start 只负责打开执行追踪，Stop 负责等待追踪数据写完。
    if err := trace.Start(f); err != nil {
        log.Fatal(err)
    }
    defer trace.Stop()

    processOrder(context.Background())
}

func processOrder(ctx context.Context) {
    // 立即登记 End，避免中途 return 时遗漏结束标记。
    defer trace.StartRegion(ctx, "process-order").End()
    // 这里放需要在 trace 中按区间观察的同步业务代码。
    loadOrder()
}

func loadOrder() {}

这里的 regionType 是用于归类的字符串，建议使用少量稳定名称，例如 process-order、load-config。如果每个请求都拼接唯一订单号，标记种类会快速膨胀，阅读 trace 时反而难以聚合。

理解 regionType、嵌套和 goroutine 约束

一个 region 可以包含更小的 region，但结束顺序必须像栈一样：先结束内层，再结束外层。用 defer 声明时，后登记的清理动作会先执行，正好符合这个规则。

func rebuildIndex(ctx context.Context) {
    // 外层区间和内层区间都在当前 goroutine 中建立与结束。
    outer := trace.StartRegion(ctx, "rebuild-index")
    defer outer.End()

    func() {
        // 内层先结束，不能把 outer.End 放到别的 goroutine。
        defer trace.StartRegion(ctx, "read-source").End()
        readSource()
    }()
}

func readSource() {}

不要把 *trace.Region 当作可以跨 goroutine 传递的任务句柄。官方语义要求 End 在启动该 region 的同一个 goroutine 中调用；如果把结束动作交给异步 worker，区间的生命周期就越过了 API 的约束。跨 goroutine 的一个业务操作，可以用 task context 把多个 goroutine 关联到同一个逻辑任务，再在各自 goroutine 中记录局部 region。

按场景选择 StartRegion、WithRegion 或 NewTask

三个 API 的关注点不同：

如果只是想给一个同步函数打标签，WithRegion 往往更短；如果需要把结束点放在函数中间，使用 StartRegion。如果关注的是“同一个请求”如何跨 goroutine 传播，则应先设计 task 的边界，再在各个执行单元里记录局部区间。

常见问题

StartRegion 不调用 trace.Start 还能看到区间吗？

它可以创建 API 层面的 region，但只有执行追踪处于启用状态时，这些标注才有可供分析的 trace 输出。通常先处理 trace.Start 的输出目标和 trace.Stop 的收尾，再添加 region。

regionType 应该写成每次请求的唯一 ID 吗？

一般不应该。regionType 更适合表示稳定的代码区间类型；请求 ID 等实例信息应通过任务上下文或日志标记表达，否则区间分类会失去聚合价值。

小结：用 StartRegion 标记同步代码段，用 defer ...End() 保证收尾；嵌套区间遵守后进先出；跨 goroutine 的业务关联使用 NewTask，不要跨 goroutine 结束同一个 Region。