pprof.Labels 将租户标签带入性能采样的实现方式

在 Go 中将租户标签带入性能采样，需要先用 pprof.Labels("tenant", tenant) 构造标签集，再用 pprof.Do 包住实际执行工作的函数。Labels 只创建标签，不会自动开启采样。对于已有工作协程，应在消费任务的位置建立标签作用域；仅给提交方的 context 添加标签，不会自动改变另一个已存在 goroutine 的采样标签。

模式命名：以任务作用域归属 CPU 样本

这个模式把租户信息附着到任务执行作用域，而不是附着到函数名。多个租户可能运行完全相同的计算函数，调用栈本身并没有租户标识；标签提供额外的分析维度，帮助在同一份采样资料中观察不同归属的样本。

优先使用 Do 管理作用域，比在各处直接调用 SetGoroutineLabels 更容易表达进入和恢复。Do 在回调期间设置标签，并在返回后恢复；回调取得的新 context 也带有标签，便于把同一任务的上下文继续传下去。

适用压力：共享调用栈难以区分租户

适合的问题是“CPU 热点来自哪个租户或哪类任务”，而不是“某租户有多少请求”。请求计数、耗时和错误仍需要相应的指标或追踪；标签只能给采样中存在的数据增加归属，不会凭空生成一份完整请求账本。

标签值应从已经确认的租户归属取得，避免直接使用未经处理的任意请求字段。若租户规模非常大，可按分析目标选择有限的租户组或经过筛选的内部标识，控制不同值的数量，也避免把个人信息、令牌或完整业务内容写进采样文件。

同一个键后设置的值会覆盖先前值，因此应用应约定 tenant、operation 等键由哪一层负责。不要把同一租户的大小写、别名和展示名称混用，否则分析时会把它们当成不同标签值。

典型实现：在实际执行工作的 goroutine 内标记

下面是完整程序：顺序处理两个示例租户，在每个任务的 Do 中执行 CPU 负载，并保存进程级 CPU profile。代码使用 errors.Join 合并文件关闭错误，需要 Go 1.20 或更高版本；这不是标签 API 的引入版本要求。

package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "runtime/pprof"
    "time"
)

var sink uint64

func work(ctx context.Context, duration time.Duration) error {
    deadline := time.Now().Add(duration)
    x := uint64(1)
    for time.Now().Before(deadline) {
        // 简单 CPU 负载仅用于演示采样，不代表真实业务性能。
        for i := 0; i 

将代码保存为 main.go 后，可在自己的本地目录使用下列命令。本文没有执行这些命令，也没有展示虚构的样本比例或 CPU 占比；短任务可能没有足够样本，不应预设采样结果一定出现每个标签。

# 构建保存为 main.go 的示例；这里不采集线上服务。
go build -o labeldemo main.go
# 使用一个尚不存在的本地文件名。
./labeldemo cpu.pprof
# 列出采样中实际出现的标签，不预设每个租户一定有样本。
go tool pprof -tags ./labeldemo cpu.pprof
# 只分析 tenant 标签值精确为 team-a 的样本。
go tool pprof -top -tagfocus='tenant=^team-a$' ./labeldemo cpu.pprof

StartCPUProfile 为当前进程开启采样，不是每个请求各开一个采样器。若采样已开启，调用会返回错误。StopCPUProfile 等待 profile 写入完成后返回，因此示例先停止采样再关闭文件；不要在每个租户回调里反复启动、停止进程级采样。

反例：只给提交方上下文贴标签

WithLabels 返回带标签的 context，但不会单独把当前 goroutine 的运行标签切换过去。已有工作池也不会因为收到一个带标签的任务对象就自动切换标签。应该让任务携带 ctx 与可信租户字段，在 worker 真正调用处理函数的位置执行 Do，并将回调得到的 labeled context 交给处理函数。

在 Do 回调期间新建的 goroutine 会继承创建者当时的标签。这个规则针对创建时刻，不是跨队列传播协议。提前启动的 worker 没有“重新出生”，需要逐任务设置；任务处理完成后返回 Do，才能为下一个任务提供清楚的作用域恢复。

如果在租户请求内启动一个长期后台 goroutine，它可能继续带着创建时的租户标签，父回调结束不会自动清掉子 goroutine 自己的标签。长期共享后台工作不应被随意归属于某个请求租户；应定义独立的后台归属，并在实际任务边界重新建立作用域。

Do 也不负责等待子 goroutine 结束，更不会自动取消它们。任务的生命周期、取消与等待仍由业务代码处理；把标签传播误认为执行生命周期管理，容易造成归属看似正确但工作已经脱离请求边界。

后果：标签筛选不是精确成本结算

当前 runtime/pprof 文档说明 CPU 和 goroutine profile 使用标签信息。不要因此承诺 heap、allocs、mutex 或 block profile 都能按同样方式提供租户标签分析。先选对资料类型，再判断标签是否存在；不能用缺少标签的内存资料推断租户没有分配内存。

CPU profile 反映采样窗口内取得的 CPU 样本，等待 I/O 的时间、未被采到的短任务、公共后台开销不一定能归到某个租户。筛选后看到的热点用于定位，不等于可以直接用作精确账单、配额消耗或隔离强度证明。

标签值很多时，分析资料可能更碎，观察单租户的样本量也可能不足。应同时保留原始采样文件和采样窗口信息，再结合流量、任务数量等指标解释。示例两个租户负载时长相同，也不能据此承诺样本严格各占一半。

判断清单与常见问题

同名标签会同时保留两个值吗？在本文的上下文标签合并规则中，后设置的同键值覆盖之前的值。应用要统一键的含义和负责设置的层次。

为什么能用 pprof.Label 读到值，profile 却看不到？读到 context 标签并不能证明实际执行 goroutine 已被设置标签。还需要看工作是否在 Do 内执行、资料类型是否支持标签、采样窗口是否覆盖该工作以及是否取得了样本。

需要直接使用 SetGoroutineLabels 吗？它是较底层的接口。能够表达成有限作用域的任务，优先 Do；手工切换时必须自己维护恢复责任，避免 worker 后续任务继承错误归属。

官方资料：https://pkg.go.dev/runtime/pprof#Labels、https://pkg.go.dev/runtime/pprof#Do、https://pkg.go.dev/runtime/pprof#SetGoroutineLabels、https://github.com/google/pprof/blob/main/doc/README.md。