Go pprof.Labels 怎样给请求附加可筛选的性能标签

如果你只把请求信息写进普通日志，性能采样里往往只剩下函数名和调用栈，很难回答“哪个路由、哪个租户、哪类后台任务更慢”。Go 的 runtime/pprof 提供了一组标签 API，可以把业务维度放进 context，再让 CPU 或 goroutine profile 带上这些标签。

最实用的组合是：用 pprof.Labels 构造键值对，用 pprof.WithLabels 派生带标签的 context；如果只想把标签限制在一次调用范围内，则用 pprof.Do。标签不是普通业务字段，也不是所有 profile 都会读取，使用前要先确定采样对象。

pprof.Labels、WithLabels 和 Do 分别负责什么

这三个名字容易混在一起，但职责并不重复。Labels 接收成对的字符串并返回 LabelSet；WithLabels 在父 context 上增加标签，返回一个新的 context；Do 则在回调期间临时加入标签，并在回调结束后恢复原来的标签上下文。

可以把它们放在同一张关系图里理解：业务请求先拥有自己的 context.Context，标签 API 再把业务维度接到 context，最终由 profile 读取能够识别的标签。这里的图是静态结构说明，不是运行截图。

package main

import (
    "context"
    "runtime/pprof"
)

func handle(ctx context.Context) {
    // Labels 只负责构造标签集合，键和值必须成对出现。
    labels := pprof.Labels("route", "/orders", "tenant", "acme")

    // WithLabels 返回派生 context；不要假设父 context 被原地改变。
    labeledCtx := pprof.WithLabels(ctx, labels)

    // Do 适合把标签限制在一次回调内，回调结束后作用域会收回。
    pprof.Do(labeledCtx, pprof.Labels("job", "order-list"), func(scoped context.Context) {
        _ = scoped
        // 将真实业务调用放在这里，采样器才有机会看到该标签上下文。
    })
}

在服务端代码里，更常见的是把 labeledCtx 继续传给下游函数，而不是把标签单独放进一个全局变量。这样标签的生命周期和请求生命周期一致，也不会让并发请求互相覆盖。

HTTP 请求怎样挂上可筛选的业务维度

请求标签应该选择稳定、低基数的维度，例如路由模板、租户分组或任务类型。不要把完整 URL、用户 ID、订单号这类高基数值直接当标签，否则 profile 的切片会迅速变得难以阅读。

func serveOrder(ctx context.Context, route, tenant string) {
    // 只放低基数维度，避免每个用户或订单都生成独立标签值。
    labels := pprof.Labels("route", route, "tenant", tenant)
    ctx = pprof.WithLabels(ctx, labels)

    // 下游函数沿用同一个 context，标签才能跟着请求边界传递。
    queryOrders(ctx)
}

func queryOrders(ctx context.Context) {
    // 这里应继续把 ctx 传给真正的查询或业务函数。
    _ = ctx
}

如果你的路由已经有统一的请求 context，就在进入业务层时派生一次；如果只需要标记一段短暂的重计算，则用 Do 更容易看出作用范围。标签 API 解决的是 profile 的关联维度，不能替代 trace、日志或指标系统。

Do 的作用范围与后台 goroutine 继承关系

pprof.Do 会用带标签的 context 调用回调，回调期间启动的 goroutine 可以继承这个标签集合。关键是把回调接收到的 context 传下去；如果后台任务自行使用 context.Background()，就切断了父 context 的标签关系。

func runJob(parent context.Context) {
    // Do 将 job 标签限定在本次回调，避免影响调用方的长期 context。
    pprof.Do(parent, pprof.Labels("job", "rebuild-index"), func(ctx context.Context) {
        go func() {
            // 后台 goroutine 使用回调传入的 ctx，才能继承 job 标签。
            rebuild(ctx)
        }()
    })
}

func rebuild(ctx context.Context) {
    // 重名 key 时，新派生的标签会覆盖父 context 中的同名值。
    _ = ctx
}

这里有一个工程上的取舍：如果 goroutine 会在回调返回后继续运行，就不要把“回调结束即失效”误解成 goroutine 立刻停止。context 的取消、任务的生命周期和 pprof 标签是三件不同的事；标签用于采样关联，不负责停止任务。

标签能用于哪些 profile，什么时候不该用

官方 runtime/pprof 文档说明，目前只有 CPU 和 goroutine profile 使用标签信息。因此，看到标签能在某类 profile 中筛选，并不意味着堆 profile 也能按同样的业务维度解释。

还有两个容易忽略的边界：Labels 的参数必须是偶数个字符串，否则会触发参数错误；标签 key 要保持稳定，避免同一含义在不同请求里出现多个拼写。profile 的标签是分析索引，不是越多越好。

用一张表决定选哪个 API

可以按作用范围快速选择：

常见问题

pprof.Labels 会自动给所有 goroutine 加标签吗？

不会。它只创建标签集合。需要通过 WithLabels 或 Do 把标签接到 context，并把这个 context 传给目标调用或新 goroutine。

为什么我加了标签，却在 profile 里找不到？

先确认采样对象是否支持标签，再确认业务调用是否使用派生后的 context；继续传父 context 或在任务内部重新使用 context.Background() 都会切断关联。

标签值应该放用户 ID 吗？

通常不建议。用户 ID、订单号等高基数值会让 profile 维度膨胀。优先选择路由模板、租户等级、任务类型等稳定分组。

pprof 标签能替代 trace 吗？

不能。标签适合给性能采样增加筛选维度；请求链路、单次调用耗时和跨服务传播仍应由 trace、日志或指标承担。

把 pprof 标签当成“采样上下文的索引”会更容易做对：先选择低基数业务维度，再用 WithLabels 传递或用 Do 限定作用域，最后根据 CPU/goroutine profile 的能力解释结果。这样既能定位慢请求，也不会把性能分析 API 误当成通用业务上下文系统。