Go pprof profile duration 参数如何理解

Go pprof 中的 seconds 参数要先看 profile 类型再解释。对 /debug/pprof/profile，它表示 CPU 采样持续多久；对 /debug/pprof/trace，它表示执行跟踪持续多久；对 allocs、block、goroutine、heap、mutex 和 threadcreate，它表示取两个时间点之间的差值剖面。也就是说，seconds=10 不一定意味着处理器会被观察十秒后才返回。

官方文档地址：https://pkg.go.dev/net/http/pprof

排查 CPU 热点时，把 seconds 当采样窗口；排查内存分配、阻塞或协程变化时，把它当差值窗口。先确认 profile 名称，再决定是否需要等待。

先确认 pprof 端点和 profile 文件来源

net/http/pprof 通过 HTTP 端点提供运行时剖面。常见的 CPU 端点是 /debug/pprof/profile，执行跟踪端点是 /debug/pprof/trace，而运行时 profile 则使用 /debug/pprof/heap、/debug/pprof/allocs 等路径。它们最终都返回供工具分析的 profile 数据，不是普通业务日志。

package main

import (
    "log"
    "net/http"

    // 只为注册 /debug/pprof/ 相关处理器而导入。
    _ "net/http/pprof"
)

func main() {
    // 使用独立监听地址承载剖面端点，实际项目应按部署边界保护它。
    log.Fatal(http.ListenAndServe("127.0.0.1:6060", nil))
}

如果服务使用自定义 ServeMux，还需要显式注册对应处理器；这一步只决定端点是否可访问，不会改变 seconds 的语义。

区分 seconds 的两种语义

Go 官方文档把参数分成两组：CPU profile 和 trace 使用 seconds=N 进行持续采样；allocs、block、goroutine、heap、mutex、threadcreate 使用它返回 delta profile。后者会先收集一个起点，再等待窗口结束，收集终点并计算差值，因此重点是窗口内的变化量，而不是把当前累计值原样导出。

因此，不能只看到参数名就套用“等待 N 秒”的解释。持续采样端点会主动保持请求一段时间；差值 profile 的重点是两个快照之间的变化，服务端会对正整数参数做窗口采集和差值计算。

理解 CPU profile 的响应时间

访问 /debug/pprof/profile?seconds=10 时，处理器会启动 CPU profile，等待约十秒，再停止采样并把结果写入 HTTP 响应。客户端拿到的 profile 文件通常在采样窗口结束后才完整可用，所以请求耗时接近采样窗口加上处理和网络传输开销，而不是立即返回一个“未来十秒的任务”。

# 采集 10 秒 CPU profile，并把二进制结果保存到文件。
curl -o cpu-10s.pprof "http://127.0.0.1:6060/debug/pprof/profile?seconds=10"

# 文件拿到后再交给 pprof 工具分析，不把它当作文本日志读取。
go tool pprof cpu-10s.pprof

这里的“约十秒”不是严格的业务计时器承诺。服务端上下文取消、写超时配置、调度和网络传输都会影响客户端看到的总时长；但 seconds 的核心作用仍然是控制 CPU 采样窗口。

处理 trace 和非法参数

trace 使用同一个参数名，但默认值不同。当前 net/http/pprof 实现中，CPU profile 没有有效的 seconds 时按 30 秒处理，trace 没有有效值时按 1 秒处理。对这两个端点，非正数或无法解析的值会回退到各自默认值，因此不能用 seconds=0 表示“马上返回”。

# 采集 5 秒执行跟踪，结果交给 go tool trace。
curl -o trace-5s.out "http://127.0.0.1:6060/debug/pprof/trace?seconds=5"
go tool trace trace-5s.out

# CPU profile 与 trace 都是持续采样型端点，但分析工具不同。
curl -o cpu-5s.pprof "http://127.0.0.1:6060/debug/pprof/profile?seconds=5"

差值型 profile 的错误边界不一样。对 heap?seconds=10 这类端点，seconds 必须是正整数；无法解析或小于等于零时，处理器会返回参数错误，而不是静默回退到默认窗口。差值型 profile 还不支持与 debug 文本输出组合使用。

保存并分析 profile 文件

保存命令应明确文件用途和对应工具：CPU profile 使用 go tool pprof，trace 使用 go tool trace。如果要比较某个时间窗口内的堆、阻塞或分配变化，就在请求中带上正整数 seconds，再分析返回的差值文件。

# 先保存差值 profile，文件名标出 profile 类型和窗口。
curl -o heap-delta-30s.pprof "http://127.0.0.1:6060/debug/pprof/heap?seconds=30"

# 用 pprof 打开差值文件；不要把差值结果和全量快照混为一谈。
go tool pprof heap-delta-30s.pprof

文件名只是管理习惯，不会改变文件内容。真正决定语义的是请求路径和参数：同样写成 seconds=30，CPU profile 表示持续采样三十秒，heap 则表示三十秒窗口前后的差值。

建立参数选择表

窗口选择要和问题持续时间匹配。窗口太短可能只看到偶然样本，窗口太长则会让 CPU profile 请求等待更久，并把多个阶段混在同一个文件里。线上排障还要把端点访问边界、请求取消和服务写超时纳入计划。

常见疑问

为什么 profile 请求没有马上返回？因为 CPU profile 和 trace 会在请求处理期间持续采样，响应要等采样结束后才完整返回。请求总时长还包含序列化和网络传输。

heap?seconds=10 会固定等待十秒吗？不能这样理解。它的目标是计算窗口差值，具体处理还包括起止采集、差值合并和写响应；它与 CPU profile 的持续采样语义不同。

seconds=0 能拿到当前快照吗？对 profile 和 trace，非正数会回退到默认持续时间；对支持差值的运行时 profile，非正数会被拒绝。要拿当前快照，直接请求不带 seconds 的 profile 端点。

为什么同样的秒数生成的文件大小不同？采样窗口只控制观察范围，不保证样本数量、事件数量或文件大小相同。业务负载、采样类型和运行时状态都会影响结果。

记住一句话：先看端点，再解释 seconds。CPU profile 和 trace 把它当持续采样窗口；allocs、heap、block 等 profile 把它当差值窗口。这样才能正确预估响应时间，也不会把不同含义的 profile 文件放在一起比较。