pprof采集堆与CPU剖面

Go 采集 CPU 剖面时，应在目标工作负载开始前调用 pprof.StartCPUProfile，工作结束后调用 pprof.StopCPUProfile，最后关闭输出文件。堆剖面可用 pprof.WriteHeapProfile 保存。CPU 剖面描述采集期间的 CPU 活动，堆剖面描述内存分配相关样本，两者需要分别选择采集时机和分析指标。

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

背景：先分清时间与内存问题

某段批处理耗时变长时，CPU 剖面可以帮助观察采样栈集中在哪些函数。如果问题是对象占用越来越多，则应观察堆剖面中的存活对象指标。CPU 占用低而响应慢，还可能涉及等待、锁或外部服务；仅靠 CPU 文件不能解释全部墙钟时间。

本文采用显式写文件的方式，适合命令行任务和可控制开始、结束的复现负载。对于持续运行的服务，也可使用 net/http/pprof，但需要另外配置诊断入口。本次做法属于采集代码的组织建议，不涉及某个新版本改变了 pprof 的语义。

常见遗漏：采集窗口和文件收尾

一种容易误导分析的写法，是先运行关键工作，再启动 CPU 采集。这样得到的文件可能主要反映程序收尾。另一种遗漏是直接关闭 CPU 文件，却没有先停止采集。StopCPUProfile 会等待该剖面的写入完成，因此输出文件应当保持打开，直到它返回。

还要注意采集范围是当前进程，而不是某一次函数调用专属。传入一个工作函数只是限定时间窗口，其他并发 goroutine 在这段时间的 CPU 活动仍可能进入样本。同一进程已经开启 CPU 采集时，再次 StartCPUProfile 会返回错误，不能忽略这个错误继续宣称采集已开始。

用显式采集函数保存两个剖面

以下代码保存为项目中的 profiling 包。调用方传入会正常返回的工作函数，以及两个不同的输出路径。文件使用独占创建和 0600 权限，已有文件会报错，避免覆盖上一份采样。输出目录需提前存在。代码使用 errors.Join，因此工具链需要 Go 1.20 或更高版本。

package profiling

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

// Capture 先包围工作负载采集 CPU，再保存堆样本。
// collectAfterGC 为 true 时主动触发一次 GC，会影响采集现场。
func Capture(cpuPath, heapPath string, collectAfterGC bool, work func() error) error {
    if work == nil {
        return errors.New("工作函数不能为空")
    }
    if err := captureCPU(cpuPath, work); err != nil {
        return err
    }
    if collectAfterGC {
        runtime.GC()
    }
    return saveHeap(heapPath)
}

func captureCPU(path string, work func() error) (err error) {
    f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
    if err != nil {
        return err
    }
    // 关闭错误与已有错误合并，不覆盖工作函数返回的原因。
    defer func() { err = errors.Join(err, f.Close()) }()

    if err = pprof.StartCPUProfile(f); err != nil {
        return err
    }
    // 后注册的 defer 先执行，保证停止采集后才关闭文件。
    defer pprof.StopCPUProfile()
    return work()
}

func saveHeap(path string) (err error) {
    f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
    if err != nil {
        return err
    }
    defer func() { err = errors.Join(err, f.Close()) }()
    return pprof.WriteHeapProfile(f)
}

调用时可使用 profiling.Capture("cpu.pprof", "heap.pprof", true, runBatch)，其中 runBatch 是签名为 func() error 的业务函数。若它启动后台任务，应等待相关任务完成再返回，否则采集窗口会提前结束。工作函数返回错误时，CPU 仍会收尾，但本例直接返回错误，不再生成堆文件；这是示例明确选择的失败策略。

这个函数没有承诺两个文件原子生成。CPU 文件创建成功后，启动采集仍可能失败；堆文件写入也可能失败。出现错误时应保留错误信息，将可能不完整的文件与成功采样分开，不要只凭文件名存在就认定采集成功。os.Exit、进程崩溃或强制终止也不保证执行 defer。

选择 CPU 与堆的分析指标

堆剖面通常以最近完成的垃圾回收为统计观察点，近期分配可能尚未完整反映。为便于比较存活对象，可以在受控实验中选择主动 GC 后采集，但这会改变现场并增加停顿，不能把它当成零成本动作。若要保留某个业务对象供堆分析，调用方也要确保对象仍有可达引用；已经释放的工作集不能靠采样函数重新保留。

# 使用与采样进程匹配的二进制查看 CPU 热点。
go tool pprof -top ./app cpu.pprof

# 分别观察存活内存和累计分配，避免使用不同指标直接比较。
go tool pprof -top -inuse_space ./app heap.pprof
go tool pprof -top -alloc_space ./app heap.pprof

其中 app 表示实际构建并用于采样的程序。不要拿其他提交或其他构建产物替代。这里提供的是读者可使用的命令，没有给出虚构热点排名或性能改进数字。CPU 窗口太短或没有代表性负载时，样本可能很少；应先改善复现条件，再讨论热点排序。

兼容和采用建议

已有服务若采用 net/http/pprof，应确认处理器注册到实际使用的 ServeMux。CPU 的 profile 入口可通过 seconds 指定采集时长，heap 入口可通过 gc 参数选择采集前触发 GC。不要把 CPU 与 heap 的 seconds 参数都解释成相同的采样窗口：heap 的该参数用于请求差分剖面。

诊断入口应限制访问范围并按运维授权使用。写文件方式不需要开放 HTTP 端口，更适合本地复现或批处理。无论采用哪种方式，都应同时记录代码版本、负载规模、并发条件和采集方式，比较相同条件下的剖面。采集动作本身会影响程序，先获得可解释的样本，再尝试优化并重新观察。

CPU 文件能说明内存泄漏吗？

它主要反映 CPU 活动。判断对象是否持续滞留，应结合多次可比的堆剖面和对象生命周期。

WriteHeapProfile 会自动先执行 GC 吗？

该函数负责写出 heap 剖面，示例将主动 GC 作为单独可选动作，没有依赖它自动触发。

为什么 alloc_space 很大，inuse_space 却很小？

可能存在频繁分配且很快释放的对象。两种指标关注的时间语义不同，需要结合具体调用栈解释。

官方参考：https://pkg.go.dev/runtime/pprof；HTTP 入口及参数：https://pkg.go.dev/net/http/pprof。