Go 1.25 runtime/pprof Label 控制采样范围：Do、ForLabels 与 goroutine 归因

线上 CPU profile 里看到某个 handler 很忙，下一步通常不是立刻改代码，而是先回答一个更具体的问题：忙的是导入任务、图片处理，还是普通查询？runtime/pprof 的标签 API 可以把这层业务归因补进 profile。用 pprof.Do 包住请求或任务，创建的 goroutine 会继承标签；再用 ForLabels 或 Label 检查上下文，就能把采样结果和任务类型对应起来。

标签解决的是“这段 CPU 消耗属于谁”的问题，不会自动改变采样范围，也不会替代 profile 本身。优先在任务入口用 pprof.Do 建立边界，只有需要底层控制当前 goroutine 时才考虑 SetGoroutineLabels。

CPU profile 有热点，但还缺少任务归因

假设一个 Go 服务同时处理 import 和 query 两类请求。profile 能显示函数调用栈，却未必能直接告诉你同一个函数分别被哪类任务调用。此时把标签放在最靠近业务入口的位置，比在底层通用函数里到处判断更稳定。

func handler(w http.ResponseWriter, r *http.Request) {
    kind := r.URL.Query().Get("kind")
    labels := pprof.Labels("task", kind)
    pprof.Do(r.Context(), labels, func(ctx context.Context) {
        go loadWork(ctx)
        loadWork(ctx)
    })
}

这里的 http.Handler 先读取任务类型，再进入 pprof.Do。回调中的 goroutine 与当前同步调用都拿到同一组标签；真正采集 profile 时，标签才有机会帮助工具区分调用归属。空的 kind 也应在入口处处理，否则 profile 里会出现难以解释的空分组。

把标签放在入口，先确认继承和覆盖规则

pprof.Do 接受父上下文、LabelSet 和一个回调。它会创建带标签的子上下文，并在回调结束后恢复外层状态。相同键会按传入顺序覆盖之前的值，所以标签名应保持稳定，值则尽量使用有限集合，例如 import、query 和 unknown。

func runTask(ctx context.Context) {
    outer := pprof.Labels("task", "import")
    pprof.Do(ctx, outer, func(ctx context.Context) {
        inner := pprof.Labels("task", "query")
        pprof.Do(ctx, inner, func(ctx context.Context) {
            value, ok := pprof.Label(ctx, "task")
            fmt.Println(value, ok)
        })
    })
}

内层 pprof.Do 读取到的是 query，因为同名键被覆盖；内层回调返回后，外层仍是 import。这条规则适合表达阶段变化，但不适合把每个订单号、请求 ID 都塞进标签：高基数值会让分析结果变得嘈杂。

用 ForLabels 和 Label 做现场检查

归因问题排查时，先在任务函数里打印一次标签，比猜测 profile 分组更快。Label 用于判断某个键是否存在；ForLabels 会按当前标签集合回调键值，并允许用返回值提前停止遍历。

func inspect(ctx context.Context) {
    task, ok := pprof.Label(ctx, "task")
    if !ok {
        task = "unknown"
    }
    fmt.Println("task:", task)

    pprof.ForLabels(ctx, func(key, value string) bool {
        fmt.Println(key, value)
        return true
    })
}

如果 Label 返回 ok=false，不要把它误判成 profile 失效，它只说明当前上下文没有这个键。把未知值归并到 unknown，再检查任务入口是否漏掉了 pprof.Do，通常比在所有下游函数补标签更容易定位。

采样结果怎么和标签检查对上

标签不是一个独立的 CPU 计数器。现场应先确认 profile 采集动作和任务流量同时存在，再用 pprof.Lookup 找到对应 profile，最后把标签检查日志与采样时间对齐。若只打印标签而没有采样，不能据此判断热点已经按任务拆开。

需要把标签设置到当前 goroutine 时，标准库还提供 SetGoroutineLabels。它是更底层的入口；普通任务优先使用 pprof.Do，这样标签和上下文的关系更清楚，也更容易在测试里复现。

常见问题：标签不是业务上下文的万能替代物

标签键可以随意拼接吗？

不建议。键和值应该是可控的枚举或低基数维度；把用户输入、订单号等高基数数据放进去，会降低 profile 的可读性。

为什么子 goroutine 没有预期标签？

先确认它是否在 pprof.Do 的回调期间创建，并检查传入的上下文是否被替换。不要只看变量名，沿着创建点检查上下文来源。

ForLabels 能修改标签吗？

不能。它只遍历当前上下文中的键值；需要改变标签集合时，应创建新的 LabelSet 并进入新的 pprof.Do。

什么时候用 SetGoroutineLabels？

只有当确实需要直接设置当前 goroutine 的标签时再用它。大多数业务入口场景用 pprof.Do 已足够。

把归因验证留在发布后的复盘清单里

上线前用测试覆盖三件事：入口标签是否存在、内层同名键是否按预期覆盖、回调结束后外层值是否恢复。上线后再把采样窗口、任务量和 pprof.Lookup 的 profile 结果放在同一张记录里。这样看到热点时，能区分“某个函数普遍变慢”和“只有 import 任务在消耗 CPU”，后续回滚或限流才有依据。