Go pprof 怎样给 CPU 采样设置窗口

我第一次把 Go CPU profile 接到业务压测里时，最容易犯的错不是不会调用 pprof，而是没有把“采样多久”当成一个明确的边界。采样一启动就覆盖整个进程，文件也一直保持打开，最后得到的 profile 很难对应到某个业务窗口。

更稳妥的做法是把 pprof.StartCPUProfile 和 pprof.StopCPUProfile 紧紧包住目标函数：开始前创建文件，停止后再关闭文件。官方文档说明，采样期间数据会写入传入的 io.Writer，而 StopCPUProfile 返回时，profile 的写入已经完成。

官方资料：https://pkg.go.dev/runtime/pprof

先划定 CPU 采样窗口

可以把采样窗口理解成一条很具体的边界：StartCPUProfile 之前的准备工作不进入本次 profile，StopCPUProfile 之后的清理工作也不应被当作目标业务热点。窗口越贴近要观察的函数，后续读图时越容易把热点和场景对应起来。

// 只在目标业务函数运行期间采样，避免把准备阶段混进 profile。
if err := pprof.StartCPUProfile(profileFile); err != nil {
    return fmt.Errorf("启动 CPU profile 失败: %w", err)
}

runBusinessWindow()

// StopCPUProfile 返回后，profile 数据才算写入完成。
pprof.StopCPUProfile()

这里的关键不是把窗口写成固定的几秒，而是让它对应一个可解释的业务范围。短任务可以按一次调用包住；持续服务则可以由管理接口或信号触发开始与停止，但同一进程同时只能保持一个 CPU profile。

让 profile 写入独立文件

StartCPUProfile 接受的是 io.Writer，因此文件创建、权限错误和路径选择都属于采样前的准备阶段。创建失败时不要启动采样；启动失败时也要关闭已经创建的文件，避免留下无用句柄。

// 文件只承载本次 profile，失败时立即把错误交给调用方。
profileFile, err := os.Create("cpu.prof")
if err != nil {
    return fmt.Errorf("创建 profile 文件失败: %w", err)
}

if err := pprof.StartCPUProfile(profileFile); err != nil {
    // 采样还没有开始，先释放文件资源，再返回原始错误。
    _ = profileFile.Close()
    return fmt.Errorf("启动 CPU profile 失败: %w", err)
}

文件名不必追求复杂，重要的是让它能和一次采样任务对应起来。临时分析可以用 cpu.prof，自动化任务则可以把业务名和采集时间放进文件名，但不要把“文件存在”误认为“采样内容完整”。完整性取决于停止采样后的写入是否已经结束。

用 defer 保证停止与关闭顺序

我更推荐在启动成功后立刻登记清理动作，但要把动作顺序写清楚：先停止 CPU profile，再关闭文件。因为 StopCPUProfile 负责等待 profile 写入结束；如果先关闭 writer，采样器还可能没有完成对它的写入。

// 启动成功后登记逆序清理：先 Stop，再 Close。
defer func() {
    pprof.StopCPUProfile()
    // Stop 返回后再关闭文件，确保 writer 仍可接收收尾数据。
    _ = profileFile.Close()
}()

runBusinessWindow()

如果需要把关闭错误也传递出去，可以把函数改成命名返回值并在 defer 中合并错误；普通排查脚本则至少不要吞掉“启动 profile 失败”的原始原因。还要注意，清理函数只应在启动成功后登记，否则没有活动 profile 时调用停止逻辑会掩盖真正的准备错误。

处理重复启动，再用工具打开文件

官方 API 在 profile 已经启用时会让再次调用 StartCPUProfile 返回错误。因此不要在多个 goroutine 里无保护地开启采样，也不要把一个采样窗口嵌套到另一个窗口里。可以由上层持有一个互斥状态，或者把采样入口收敛成单一管理函数。

// 这个命令只负责读取已经生成的 profile，不会重新采样。
// top 先查看热点摘要，便于确认窗口里记录的是目标业务。
// go tool pprof cpu.prof
// (pprof) top

查看时使用 go tool pprof cpu.prof，进入交互界面后再执行 top 等命令。这里的 profile 文件是采样窗口的离线产物，不等于完整的性能结论；它只能说明这段窗口内采到的调用栈分布。

几个容易忽略的边界

• 采样窗口必须覆盖真正想观察的业务函数，否则结果会被初始化或清理阶段稀释。
• 启动失败和文件创建失败要分别返回，不能把空文件当作有效 profile。
• StopCPUProfile 返回后再关闭 writer，文件生命周期才和写入完成语义一致。
• 同一进程不要并发开启多个 CPU profile；要把开始、停止和状态管理放在同一个控制边界内。

相关问题

CPU profile 一定要采样固定秒数吗？不一定。固定时长适合临时排查，按一次业务调用或一段明确任务包围则更容易解释。

为什么生成了 cpu.prof 却打不开？先确认启动没有报错，并确保停止采样已经返回后才关闭文件；过早关闭 writer 会破坏文件的完整写入过程。

可以同时采集两个 CPU profile 吗？标准库的 CPU profile 入口不支持在同一进程中重复启用，应该复用一个窗口或把任务拆开采集。