Go pprof 标签怎么让同一服务的 CPU 数据按租户拆分

同一个 Go 服务进程里，CPU profile 默认看到的是整个进程的采样热点；如果请求来自多个租户，单看函数名很难回答“到底是谁把 CPU 用高了”。解决办法不是为每个租户启动一个 profiler，而是在请求边界给 profiling context 加上租户标签，再用带标签的 profile 做切片。

标准库 runtime/pprof 提供了这条路径：pprof.Labels 先构造键值集合，pprof.Do 在回调期间把它附加到上下文。回调中新建的 goroutine 会继承增强后的标签，但最终仍然是一份进程级 profile，标签只是额外的诊断维度。

pprof 标签与 CPU profile 的关系

先把三个概念分开：StartCPUProfile 控制一次进程级 CPU 采样，pprof.LabelSet 描述采样上下文，profile 工具再利用标签对样本进行归类。标签不会把一个 Go 进程变成多个文件，也不会自动替每个租户保存独立 profile。

官方文档还特别说明，目前 CPU 和 goroutine profile 会利用标签信息。因此，如果你正在看 heap、allocs 或其他 profile，却期待同样的租户标签维度，先确认 profile 类型，不要先改业务代码。

用 pprof.Do 在请求边界加入租户标签

把标签写入 HTTP handler 或 RPC 入口最容易控制范围。示例只保留一个稳定的租户字段，并把 pprof.Do 回调给出的 ctx 传进真正的业务函数：

func serveTenant(ctx context.Context, tenantID string, payload []byte) {
    // 只使用经过认证和长度限制的租户标识，避免把任意输入变成高基数标签。
    labels := pprof.Labels("tenant_id", tenantID)

    pprof.Do(ctx, labels, func(profileCtx context.Context) {
        // 关键点：后续调用必须接收 profileCtx，不能继续使用外层 ctx。
        processRequest(profileCtx, payload)
    })
}

func processRequest(ctx context.Context, payload []byte) {
    // 这里启动的 goroutine 会继承创建它的 profileCtx 标签。
    go func(childCtx context.Context) {
        _ = childCtx
        decodeAndStore(payload)
    }(ctx)
}

Labels 要接收偶数个字符串，按 key、value 成对解释；上例的 tenant_id 是键，tenantID 是值。不要把邮箱、完整 URL 或未截断的请求参数当标签值，否则 profile 的维度会迅速膨胀。

检查 goroutine 继承与同名标签覆盖

pprof.Do 会在回调期间临时增强父上下文，回调返回后恢复原来的标签集合。回调里新建的 goroutine 会继承创建者的标签；若嵌套调用再次写入同一个 key，后写的值覆盖先前的值。需要确认结果时，可以用 pprof.Label 读取单个键，用 pprof.ForLabels 遍历当前集合：

func inspectLabels(ctx context.Context) {
    // Label 返回值和存在标志，空字符串不等于键不存在。
    tenant, exists := pprof.Label(ctx, "tenant_id")
    if exists {
        log.Printf("tenant label=%s", tenant)
    }

    // ForLabels 适合记录有限的诊断字段；发现敏感值时不要写入普通日志。
    pprof.ForLabels(ctx, func(key, value string) bool {
        log.Printf("profile label %s=%s", key, value)
        return true // 返回 false 可提前停止遍历。
    })
}

需要显式构造派生上下文时可以用 pprof.WithLabels；它返回一个新 context，不会就地修改旧 context。调试时最常见的误区是把新 ctx 丢掉，或者在异步闭包里重新取了未标记的背景上下文。

租户标签上线前的基数和采样边界

租户标签最适合作为一次性能调查的切片条件，而不是永久暴露在指标系统里的维度。上线前可以按下面的清单收口：

• 命名：固定使用 tenant_id 这类稳定键，避免同一含义出现 tenant、customer 两套名字。
• 基数：租户数量很大时先使用白名单、哈希桶或临时采样名单；不要让每个用户输入都成为长期标签。
• 窗口：采集前明确 CPU profile 的开始和结束时间；没有覆盖目标请求的窗口，标签再正确也看不到样本。
• 解释：profile 的标签只说明样本上下文，不等于租户耗时、请求数或计费数据。需要长期趋势时，另用低基数 metrics。

如果标签没有出现，先检查四件事：当前看的是否为 CPU 或 goroutine profile；是否真的执行到了 pprof.Do 回调；业务调用是否使用回调传入的 ctx；标签值是否在采样窗口内出现。这样比盲目增加 profiler 数量更快定位问题。

常见问题

为什么 CPU profile 还是只有一个文件？

因为标签是 profile 内的上下文信息，不会按租户拆成多个文件。用 pprof 工具分析同一份采样数据时，再按标签筛选或归类。

后台 goroutine 为什么没有 tenant_id？

只有从带标签的 ctx 创建出来的 goroutine 才能继承标签。不要在异步函数里丢弃参数，重新使用 context.Background() 或外层未标记的 ctx。

能不能把每个用户都写成一个标签值？

短时、受控的诊断可以，但长期采集不建议。高基数会让 profile 解读、存储和下游工具都变复杂；优先白名单或桶化。