Go pprof goroutine 泄漏剖析的采样方法

Go 用 pprof 排查 goroutine 泄漏时，可靠的采样方式是：在相同负载阶段保存至少两份二进制 goroutine profile，观察同一组阻塞堆栈是否持续净增长；再用 debug=1 的聚合文本或 debug=2 的完整栈确认阻塞位置。单次看到 goroutine 数量很高，只能说明当时并发多，不能直接证明泄漏。

先保留“时间、版本、负载、profile 文件”四项证据，再判断泄漏。真正值得追踪的是流量回落后仍不下降、且同一阻塞堆栈反复增长的 goroutine。

保护资产：先把 pprof 放在受控边界内

pprof 会暴露运行时和函数堆栈信息，不应直接绑定公网地址。更稳妥的部署方式是单独监听 127.0.0.1 或仅运维网可达的地址，再通过跳板机、服务网格或带身份认证的内部代理采样。业务端口与剖析端口分离，也便于单独设置超时和访问审计。

package debugserver

import (
    "log"
    "net/http"
    "net/http/pprof"
    "time"
)

func Start() {
    mux := http.NewServeMux()
    // 只注册索引与 goroutine profile，减少不必要的调试面。
    mux.HandleFunc("/debug/pprof/", pprof.Index)
    mux.Handle("/debug/pprof/goroutine", pprof.Handler("goroutine"))

    server := &http.Server{
        Addr:              "127.0.0.1:6060", // 仅本机可达，不直接暴露公网。
        Handler:           mux,
        ReadHeaderTimeout: 3 * time.Second,
    }

    go func() {
        if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            // 启动失败必须记录，避免误以为剖析端点已经可用。
            log.Printf("pprof server failed: %v", err)
        }
    }()
}

使用自定义 ServeMux 时需要显式注册处理器。若直接匿名导入 net/http/pprof，它会把端点注册到默认复用器；大型服务通常更适合独立复用器和独立监听地址。

泄漏路径：先保存两份可比较的二进制样本

选择业务已经稳定运行、请求量可记录的窗口。先保存基线，再在固定间隔后保存第二份样本。文件名带上时间和发布版本，避免之后把不同实例或不同版本混在一起。

# 保存第一个二进制 goroutine profile，默认 debug=0。
curl -fsS -o goroutine-before.pb.gz \
  'http://127.0.0.1:6060/debug/pprof/goroutine'

# 这里的间隔应与业务观察窗口一致，并同时记录请求量。
sleep 60

# 保存第二个样本，文件必须与基线来自同一实例和版本。
curl -fsS -o goroutine-after.pb.gz \
  'http://127.0.0.1:6060/debug/pprof/goroutine'

# 分别查看两个样本中累计最多的 goroutine 堆栈。
go tool pprof -top goroutine-before.pb.gz
go tool pprof -top goroutine-after.pb.gz

# 用基线与后续样本做差，优先观察持续净增长的位置。
go tool pprof -top -base goroutine-before.pb.gz goroutine-after.pb.gz

-base 适合辅助比较，但仍要结合负载解释结果：请求量翻倍时，等待网络、连接池或限流器的 goroutine 同步增加可能是正常容量行为。流量恢复后同一堆栈仍不下降，才更接近泄漏信号。

风险分级：用增量采样缩小增长堆栈

当前 net/http/pprof 文档允许 goroutine profile 使用 seconds=N 返回 delta profile。它在一个请求里完成窗口对比，适合减少人工保存两份文件时的时间误差。

# 在 60 秒窗口内采集 goroutine 增量 profile。
curl -fsS -o goroutine-delta.pb.gz \
  'http://127.0.0.1:6060/debug/pprof/goroutine?seconds=60'

# 查看窗口内净增长最明显的堆栈分组。
go tool pprof -top goroutine-delta.pb.gz

# 进入交互模式后，可用 list 查看目标函数对应的源码位置。
go tool pprof goroutine-delta.pb.gz

风险可按证据分成三档：只在峰值出现且会回落的是暂时阻塞；随负载线性变化但能稳定回收的是容量问题；在流量回落后仍持续累积，并集中于无法完成的 channel、锁等待或 I/O 路径，才是高优先级泄漏候选。

防护控制：用 debug 文本栈确认阻塞语句

二进制 profile 适合聚合和排序；定位到函数后，再取一份文本栈确认 goroutine 状态。debug=1 输出带函数与行号说明的聚合文本，适合快速查同栈数量；debug=2 输出所有 goroutine 的完整栈，信息更多，也更容易产生大文件。

# 聚合文本适合搜索重复堆栈和数量。
curl -fsS \
  'http://127.0.0.1:6060/debug/pprof/goroutine?debug=1' \
  -o goroutine-summary.txt

# 完整栈只在需要区分单个 goroutine 状态时采集。
curl -fsS \
  'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2' \
  -o goroutine-full.txt

常见可疑位置包括没有接收者的 channel 发送、永远等不到关闭的 channel 接收、缺失取消传播的后台任务，以及没有超时或关闭路径的网络读写。堆栈只能告诉你“卡在哪里”，还需要回到资源生命周期判断“为什么再也无法解除”。

审计记录：把采样与负载和版本绑定

普通 goroutine profile 包含所有当前 goroutine，它不能天然区分“永久泄漏”和“暂时阻塞”。在支持的较新 Go 版本中，专门的 goroutineleak profile 能识别一部分被证明无法解除的 channel 与 sync 阻塞；但网络 I/O、自定义同步方式和仍被全局引用的同步原语可能不在其判定范围内，因此常规趋势采样仍有价值。

验证清单：修复后按原窗口复测

• pprof 端点只在本机或受控运维网络可达，并有访问记录。
• 样本来自同一实例、同一发布版本和可比较的负载阶段。
• 至少比较两份二进制样本，或使用 seconds=N 增量 profile。
• 高优先级候选同时满足“同栈增长”和“负载回落后不下降”。
• 已用文本栈确认源码行，并检查 channel、context、锁和 I/O 的退出路径。
• 修复后重复同一时长与负载的采样，确认目标堆栈不再净增长。

常见问题

goroutine 数量高就是泄漏吗？

不是。高并发、连接池、工作队列和暂时阻塞都可能让数量升高，必须结合负载回落后的趋势与堆栈位置判断。

为什么不只看 debug=2？

完整栈适合确认细节，但文件大、重复信息多。先用二进制 profile 聚合排序，再按目标栈取文本通常更高效。

block profile 能代替 goroutine profile 吗？

不能。block profile 关注同步阻塞事件并需要采样率配置；goroutine profile 是当前 goroutine 堆栈快照，两者回答的问题不同。