Go goroutine 泄漏剖析怎么接入持续性能采样

Go 1.27 已经把 goroutineleak 作为正式 profile 放进 runtime/pprof，也能通过 net/http/pprof 的 /debug/pprof/goroutineleak 入口采集。要接入持续性能采样，重点不是每次把所有 goroutine 数量都上报，而是固定入口、采样规则和比较维度：保存 profile，找出持续出现的泄漏栈，再结合代码修复。

官方资料：https://go.dev/doc/go1.27

最小落地方案是给已有 pprof 服务保留 goroutineleak endpoint，由采集端按固定周期拉取 profile，再用 go tool pprof 按函数或栈比较；结果只代表运行时能证明永久阻塞的那一部分泄漏。

把 goroutineleak 入口接到现有 pprof 服务

如果服务已经匿名导入 net/http/pprof 并使用默认 http.DefaultServeMux，Go 1.27 会自动注册这个 profile，不需要再写一个自定义 handler。下面的最小示例只展示接入关系；生产环境应把诊断端口放在受控网络或鉴权代理之后。

package main

import (
    "log"
    "net/http"

    // 导入后注册默认 pprof 路由，包括 goroutineleak profile。
    _ "net/http/pprof"
)

func main() {
    go func() {
        // 诊断服务只绑定本机；生产环境按网络隔离方案暴露。
        if err := http.ListenAndServe("127.0.0.1:6060", nil); err != nil {
            log.Printf("pprof server stopped: %v", err)
        }
    }()

    // 这里放置真实业务启动逻辑；示例保持进程持续运行。
    select {}
}

不要把这个示例中的本地监听地址直接当成生产方案。真正需要确认的是运行时版本、路由是否注册，以及采集端能否访问目标实例。对于自定义 mux 的服务，也要确保 pprof handler 被明确挂载到受控诊断入口。

用固定采样规则保存并比较 profile

采集端可以定期请求 profile 文件，再交给 go tool pprof 查看泄漏函数。周期不必追求越短越好；官方说明指出，只要泄漏在一次运行中已经可观察，后续通常仍可观察，因此可以用较低频率降低额外开销。实际周期要结合实例数量、profile 大小和故障响应时间决定，例如先从每 4 小时一次开始。

# 拉取某个实例的 goroutine 泄漏 profile，保存时间由调度器注入。
curl --fail --silent --show-error \
  http://127.0.0.1:6060/debug/pprof/goroutineleak \
  --output leak-20261005T1200Z.prof

# 进入 pprof 后按函数名查看泄漏栈，避免只看总 goroutine 数。
go tool pprof leak-20261005T1200Z.prof
# 在交互提示符中执行：top、list、web（按环境选择）

持续采样的关键是比较同一口径。建议至少保存实例标识、Go 版本、采样时间、profile 文件校验值和采集失败原因；文章或监控系统不必把完整 profile 内容直接塞进指标标签。对比时先看同一函数的出现次数和栈位置，再看泄漏是否随着相同业务压力重复出现。

先看 profile 能覆盖哪些泄漏

goroutineleak 不是“所有卡住的 goroutine”列表。它依靠运行时和垃圾回收器判断某个阻塞原语是否还可能被活动 goroutine 访问，因此更适合发现永久阻塞在 channel、阻塞 select、sync.Mutex、sync.RWMutex、sync.WaitGroup 或 sync.Cond 等原语上的泄漏。

网络或文件 IO、直接系统调用、依赖自定义自旋锁的等待，不应因为没有出现在该 profile 中就被判定为健康。同样，如果阻塞原语始终能从全局变量或可运行 goroutine 到达，运行时可能认为它仍有生命力。遇到这类情况，要结合普通 goroutine profile、block profile、日志和请求生命周期继续查。

• 能看到泄漏栈：优先检查发送方是否早退、接收方是否提前返回、channel 是否应该关闭，以及 Start/Stop 是否成对。
• 看不到但怀疑泄漏：先确认是否属于 IO、系统调用或全局可达原语，再换用其他诊断手段。
• 数量随压力增长：同时保存压力窗口，区分业务设计中的暂时阻塞和永远没有解除条件的阻塞。

相关问题

普通 goroutine profile 能替代 goroutineleak 吗？

不能。普通 profile 擅长展示当前 goroutine 的栈，但通常需要人工判断哪些阻塞是设计行为；goroutineleak 专门筛选运行时能证明不会再解除的那部分。

为什么 profile 里没有网络 IO 阻塞？

该 profile 的判定范围集中在 Go 的一等并发原语。网络 IO、文件 IO 和直接系统调用属于另一类阻塞，需要用其他指标和现场剖析确认。

采样越频繁越好吗？

不一定。先固定一个能覆盖故障响应时间的周期，控制 profile 保存数量和采集开销；比起高频抓取，更重要的是用相同版本、实例和压力口径做比较。

把 goroutineleak 接入监控时，入口只是第一步。真正有价值的是让 profile 文件和部署版本、实例压力、代码栈保持可关联，并把运行时的检测边界写进告警说明，避免把“未发现可证明的泄漏”误读成“系统不存在泄漏”。