runtime/trace 任务日志如何与 trace region 对齐

排查一次跨 goroutine 的慢任务时，单独看 log.Printf 往往只能得到几行时间戳，无法知道这些消息属于哪段工作。runtime/trace 的做法是把“逻辑任务”放进 context.Context，再用 trace.WithRegion 标记同一 goroutine 内的时间区间，并用 trace.Log 写入一次性诊断事件。这样，region 和日志就能挂到同一个 task 上。

对齐的关键不是让日志文本包含某个神奇前缀，而是把同一个带 task 的 ctx 同时传给 trace.WithRegion 与 trace.Log。跨 goroutine 时继续传递这个 ctx；不要在子 goroutine 里重新用 context.Background()，否则关联会断开。

本文只讨论任务、region 和 trace 日志之间的静态关系，图片是原创结构说明图，不是终端截图或运行证据。

先把四种标记的职责分开

这类问题最容易出错的地方，是把普通日志和执行 trace 当成同一种输出。普通日志写入应用配置的输出端；trace.Log 是 trace 中的一次性事件；trace.WithRegion 记录当前 goroutine 执行某个区间的开始与结束；trace.NewTask 则表示一个可能跨多个 goroutine 的逻辑操作。

用带 task 的 context 贯穿一段任务

如果任务只在一个 goroutine 中完成，可以直接在入口创建 task，再把返回的 ctx 传入 region 和日志。如果任务会拆成多个 goroutine，仍然使用同一个 task ctx，并在每个 goroutine 内创建自己的 region。官方语义中，region 的开始和结束发生在调用它的 goroutine；task 才是跨 goroutine 的逻辑容器。

package main

import (
    "context"
    "runtime/trace"
)

func handleOrder(parent context.Context, orderID string) {
    // task 表示一次业务操作，ctx 负责把关联信息传给后续工作。
    ctx, task := trace.NewTask(parent, "handle-order")
    defer task.End()

    trace.WithRegion(ctx, "load-order", func() {
        // category 保持稳定，动态值放在 message 中，避免类别数量失控。
        trace.Log(ctx, "order", "load-start:"+orderID)
        loadOrder(ctx, orderID)
    })

    // 子 goroutine 继续使用同一个 ctx，region 仍记录各自 goroutine 的区间。
    done := make(chan struct{})
    go func(taskCtx context.Context) {
        defer close(done)
        trace.WithRegion(taskCtx, "reserve-stock", func() {
            trace.Log(taskCtx, "order", "reserve-start:"+orderID)
            reserveStock(taskCtx, orderID)
        })
    }(ctx)
    

这里的重点有两个：task.End() 只负责结束逻辑任务，不能替代 region 的结束；而 WithRegion 的闭包返回后，当前 region 才结束。跨 goroutine 的工作必须显式接收并使用 ctx，不能只复制一个订单号就把追踪上下文丢掉。

在 region 内记录能定位问题的 trace.Log

trace.Log(ctx, category, message) 写入的是一次性事件。为了让日志和 region 对齐，通常把它放在对应 region 的闭包内，并让两者接收同一个 ctx。category 应该是少量稳定值，例如 order、cache 或 storage；订单号、分片号等变化内容放到 message。

func writeSnapshot(ctx context.Context, shard string, data []byte) error {
    var err error
    trace.WithRegion(ctx, "write-snapshot", func() {
        // 记录阶段性事实，message 携带本次调用的业务标识。
        trace.Log(ctx, "storage", "shard="+shard)
        err = saveSnapshot(data)
        if err != nil {
            // 错误也作为一次事件记录，真正的错误仍由函数返回。
            trace.Log(ctx, "storage", "write-error")
        }
    })
    return err
}

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

不要把每个请求 ID 都拼进 category，也不要把完整对象、用户输入或大段堆栈塞进 message。前者会制造大量类别，后者会让 trace 变得难以检索；稳定类别加短消息更适合作为区间内的定位标记。

出现日志对不上 region 时先查这三个根因

如果 trace 中看到了日志，却找不到预期的 region，通常不是文本匹配失败，而是关联边界没有设计好。

• 传错 context：region 使用了带 task 的 ctx，但日志调用拿的是 context.Background() 或另一个请求的 ctx，结果自然不会落在同一个任务下。
• 把 region 当成跨 goroutine 容器：WithRegion 只包住启动 goroutine 的语句，并不会自动覆盖新 goroutine 中的工作；应在子 goroutine 内再次创建 region。
• 命名过于动态：把 ID 拼到 regionType 或 category 中，会让同一类工作分裂成大量名字。固定阶段名，动态值只出现在短 message 中。

另一个常见误区是期待普通 log.Printf 自动出现在 runtime/trace 任务链。它们可以同时保留：普通日志适合线上检索，trace.Log 适合在执行 trace 中标出关键时点，二者不要互相冒充。

相关问题

WithRegion 能跨 goroutine 自动延长吗？

不能。它关联调用自己的 goroutine，并在闭包返回时结束；需要跨 goroutine 归属时传递 task ctx，并在每个 goroutine 内建立自己的 region。

为什么 trace.Log 看起来没有和业务日志合并？

因为它们属于不同输出体系。要让事件进入 runtime/trace 的任务关联链，必须调用 trace.Log 并传入正确的 ctx；普通日志仍按自己的 handler 输出。

小结：用 NewTask 建立逻辑边界，用同一个 ctx 连接 WithRegion 和 trace.Log，用稳定的 regionType 与 category 表达阶段，动态业务信息只放进短 message。这样任务日志才真正和 trace region 对齐。