Go runtime/pprof把请求标签写入 CPU Profile的分析方法

同一份 Go CPU Profile 里同时包含搜索、详情和后台任务时，单看函数名只能知道“哪里耗 CPU”，很难回答“哪类请求在耗 CPU”。做法是把低基数的请求分类信息放进 runtime/pprof 标签，再让 CPU Profile 记录这些标签。入口处使用 pprof.Do，采集时用 StartCPUProfile，分析时使用 go tool pprof 的标签命令即可。

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

CPU Profile 标签解决的不是日志关联

日志通常按请求记录一行或多行文本，而 CPU Profile 是采样得到的调用栈集合。pprof.Labels 生成键值对，标签会随 Profile 样本保存；它适合回答“route=search 的 CPU 样本集中在哪些函数”。这类标签应当是低基数分类，例如 route=search、tenant_group=pro、job_kind=export，而不是每个请求都不同的 ID。

标签只描述采样时 goroutine 所处的分类，并不会替代 trace、日志或业务指标。Profile 没采到某个短请求时，也不能据此断定该请求没有消耗 CPU。

先把 CPU Profile 的采集窗口控制住

StartCPUProfile 只能在当前进程没有其他 CPU Profile 时启动；启动失败必须保留错误。停止时使用 StopCPUProfile，它会等待 Profile 写入完成。示例只演示采集边界，不代表需要在每个请求中重复开关 Profile：

package main

import (
    "log"
    "os"
    "runtime/pprof"
)

func captureCPUProfile(run func()) error {
    // 文件只承载本次采样，避免把多个窗口混在一起。
    file, err := os.Create("cpu.pprof")
    if err != nil {
        return err
    }
    defer file.Close()

    // 同一进程同时只能有一个 CPU Profile，必须处理启动错误。
    if err := pprof.StartCPUProfile(file); err != nil {
        return err
    }
    defer pprof.StopCPUProfile() // 等待缓冲内容写完再返回

    run()
    return nil
}

func main() {
    if err := captureCPUProfile(runWork); err != nil {
        log.Fatal(err) // 采集失败时不要把空文件当成有效 Profile
    }
}

func runWork() {
    // 这里放要观察的服务负载或测试负载。
}

生产服务通常通过管理入口或独立采样进程控制窗口，避免让 Profile 文件长期覆盖或让采样开关成为请求路径的一部分。采样结束后再分析同一份文件，结论更容易和流量窗口对齐。

在请求入口使用 pprof.Do 注入低基数标签

关键点是让标签和请求处理的生命周期一致。pprof.Do 接收父 context、LabelSet 和回调；回调结束后标签会恢复，回调中创建的新 goroutine 会继承增强后的标签。路由值应来自有限集合，租户可以先归并成等级或区域，避免标签数量随请求数增长。

func handleSearch(w http.ResponseWriter, r *http.Request) {
    labels := pprof.Labels(
        "route", "search",
        "tenant_group", classifyTenant(r),
    )

    // pprof.Do 让本次请求及其内部新建 goroutine 带上分类标签。
    pprof.Do(r.Context(), labels, func(ctx context.Context) {
        // 把带标签的 ctx 继续传给下游，而不是重新使用 Background。
        result, err := querySearch(ctx, r.FormValue("q"))
        if err != nil {
            http.Error(w, "query failed", http.StatusInternalServerError)
            return
        }
        renderSearch(w, result)
    })
}

func classifyTenant(r *http.Request) string {
    // 只返回有限的业务分组，不把原始租户 ID 写进 Profile。
    if r.Header.Get("X-Tenant-Tier") == "pro" {
        return "pro"
    }
    return "standard"
}

如果只是需要构造带标签的 context，也可以用 pprof.WithLabels；它返回新 context，但不会像 Do 那样自动把当前 goroutine 的标签设置到回调范围。SetGoroutineLabels 是更底层的手段，只有在明确管理 goroutine 生命周期时才考虑。

用 go tool pprof 把标签变成可读的分析维度

先确认 Profile 中确实出现了标签，再缩小观察范围。下面的命令是分析示例，标签名和值要换成代码里实际写入的内容：

# 列出 Profile 中已有的标签和值
go tool pprof ./server cpu.pprof
(pprof) tags

# 只保留 route=search 的样本，再查看文本热点
go tool pprof -tagfocus='route=search' ./server cpu.pprof
(pprof) top

# 把 route 标签作为调用图根部的伪栈帧，比较不同路由
go tool pprof -tagroot=route ./server cpu.pprof
(pprof) top

tagfocus 适合先回答“目标分类是否集中在某个函数”；tagroot 和 tagleaf 适合把标签放入调用关系的两端，观察分类与函数的组合。没有标签时不要直接猜原因：先检查 pprof.Do 是否覆盖真正的 CPU 工作区间，以及下游是否丢弃了带标签的 context。

三个容易让结论失真的边界

还要注意同名标签的覆盖规则：后加入的值会覆盖之前的同名键。若中间层把 route 改成了内部阶段名，Profile 里看到的就不再是入口路由。建议固定标签键的归属，在请求边界只设置一次，内部模块另用不同键名。

常见问题

为什么 tags 看不到请求标签？

通常是标签没有覆盖真实 CPU 工作，或者只创建了带标签 context 却没有使用 pprof.Do / SetGoroutineLabels 设置当前 goroutine。先确认回调确实包住了目标代码，再检查异步任务是否在回调内创建。

WithLabels 和 Do 应该怎么选？

需要在一个明确的函数范围内临时设置 Profile 标签时优先用 Do；只需要向下游传递一个带标签 context 时用 WithLabels，并确保下游确实接收并使用这个 context。

把租户 ID 写进 CPU Profile 可以吗？

不建议。高基数标签会让 Profile 维度膨胀，也可能把敏感标识带入分析文件。先按套餐、区域或业务线归组，单租户调查使用日志和 trace 做关联。

可以把这套检查固定成采样前清单：标签是否低基数、pprof.Do 是否覆盖热点、异步 goroutine 是否继承 context、Profile 是否覆盖可比的负载窗口，以及分析命令是否先用 tags 确认数据存在。这样得到的不是“某函数永远最慢”，而是更接近“哪一类请求在当前采样窗口里把 CPU 花在了哪里”。