Go pprof 标签怎样把 goroutine 归属到租户维度

如果一个 Go 服务同时承载多个租户，看到 goroutine profile 中某段后台工作很慢时，只看函数名往往还不够。更实用的做法是把低敏的租户维度放进 pprof.Labels，再用 pprof.Do 包住请求或单次任务。这样，在标签支持的 CPU 与 goroutine profile 中，调用栈就多了一条可筛选的归属线索。

官方地址：https://pkg.go.dev/runtime/pprof

我在实际排查中最容易踩的坑有两个：把标签写成了敏感的原始用户标识，以及让长驻 worker 永久保留第一个任务的标签。下面按接口语义把传播、读取和边界拆开。

• 传播：优先用 pprof.Do，它会在回调期间设置标签，并让回调中创建的 goroutine 继承标签。
• 读取：goroutine profile 的文本调试输出可以把标签行和调用栈放在一起观察，但它不是访问控制。
• 边界：租户值应低敏、低基数；Go 1.27 及以上模块的 goroutine traceback 还可能带标签，需要单独评估隐私。

租户标签应该放在请求上下文的哪一层

先把“租户归属”当作 profiling 维度，而不是把整个请求对象塞进标签。适合放入标签的通常是经过规范化的短值，例如内部租户分组或脱敏后的稳定代码；邮箱、手机号、订单号、Token 和原始请求参数都不应该进入 profile。

请求入口拿到租户信息后，可以把业务上下文和 pprof 标签放在同一个上下文链上。pprof.WithLabels 负责返回带标签的新 context，pprof.Do 则负责在一段边界内临时设置当前 goroutine 的标签：

func handleTenant(ctx context.Context, tenantKey string) {
    // 标签只保留低敏、稳定的租户维度，不写入原始用户资料。
    labels := pprof.Labels("tenant", tenantKey)

    // Do 会在回调期间设置标签；回调内新建的 goroutine 会继承它。
    pprof.Do(ctx, labels, func(labeled context.Context) {
        go func() {
            // 业务 context 继续向下传递，便于取消和超时。
            runAsyncJob(labeled)
        }()
    })
}

Do 的重要语义是“临时边界”：回调返回后，外层 goroutine 会恢复原来的标签。标签值相同的键会覆盖父 context 中的旧值，所以中间层不要无意中把上游租户改成空字符串。需要查看标签时，可用 pprof.Label 读取单个键，或用 pprof.ForLabels 遍历当前 context。

跨租户 worker 为什么要按任务包住

请求型 goroutine 通常跟着请求结束，标签边界比较直观；队列消费者则不同。一个长驻 worker 会连续处理租户 A、租户 B 的任务，如果只在 worker 启动时调用一次 SetGoroutineLabels，后续样本就可能一直带着 A 的标签。这个 API 是低层能力，应该只在确实需要给“当前 goroutine”设标签时使用。

更稳妥的写法是在每次任务处理处创建临时边界，让标签和任务生命周期一致：

func worker(ctx context.Context, jobs 

如果必须在已经存在的 goroutine 上切换标签，才考虑 SetGoroutineLabels，并把恢复动作写成同一段生命周期的一部分。不要把它当成“给 goroutine 永久贴身份”的注册表；它描述的是 profiling 时当前执行边界的标签。

怎样从 goroutine profile 看出租户归属

标准库文档说明，目前 CPU profile 和 goroutine profile 会使用 labels 信息。排查时可以取得名为 goroutine 的 profile，并以 debug=1 写出文本，观察标签行与调用栈的对应关系。下面的代码只展示采集方式，不给出固定行号或固定样本数：

func writeGoroutineProfile(w io.Writer) error {
    // goroutine profile 的文本调试输出便于人工查看标签和调用栈。
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return errors.New("goroutine profile unavailable")
    }

    // debug=1 请求可读文本；生产环境仍要控制输出的保存和访问范围。
    return profile.WriteTo(w, 1)
}

在文本结果里，标签行适合回答“这段栈属于哪个租户维度”，不适合回答“谁有权查看这段栈”。profile 可能包含函数名、路径和业务结构信息，导出前仍要遵守监控系统的访问控制和保留策略。若用图形化工具分析，也应先确认工具链对标签的展示方式，不要把没有标签的样本强行归到某个租户。

隐私和高基数边界要先写进设计

租户维度不是越细越好。把每个请求 ID 当成标签，会制造几乎不可聚合的维度；把真实租户名称、邮箱或合同信息写进去，则会扩大 profile 泄露面。实践中可以只保留内部租户组、经过不可逆处理的短标识，或者在采集入口做采样和白名单。

还要注意 Go 版本带来的额外出口：Go 1.27 的发布说明提到，go 指令为 1.27 或更高的模块，goroutine traceback 的头部会包含 runtime/pprof labels；可以用 GODEBUG=tracebacklabels=0 关闭 traceback 中的标签。这个设置只控制 traceback 展示，不等于删除 profile 中已经采集的标签，因此 profile 的授权、落盘和传输仍要单独处理。

把接口取舍落成一张小清单

如果目标只是把慢栈按租户分组，优先采用“低敏标签 + pprof.Do + 每任务边界”的组合。只有在特殊的当前 goroutine 场景下才使用 SetGoroutineLabels，并明确恢复责任。

• 入口是否已经把租户值规范化并限制了基数？
• 标签是否包住了真正的任务，而不是只包住 worker 启动？
• profile 文本、图形化分析文件和 traceback 是否有不同的访问策略？
• 是否把无标签样本、公共后台任务和租户任务分开解释？

常见问题

pprof.Do 会修改传入的 context 吗？

不会。它使用带附加标签的 context 调用回调，并在回调结束后恢复外层 goroutine 的标签。业务代码仍应把回调参数继续向下传递。

长驻 worker 能只调用一次 SetGoroutineLabels 吗？

不建议。它会让后续处理继续带着旧标签；跨租户 worker 应在每个任务边界使用 pprof.Do，让标签随任务切换。

标签能替代租户权限控制吗？

不能。标签用于 profile 归因和分析，profile 本身仍可能含有敏感运行信息，必须由独立的鉴权和脱敏策略保护。

参考：https://pkg.go.dev/runtime/pprof；https://go.dev/src/runtime/pprof/label.go；https://go.dev/doc/go1.27。