Go 怎样导出 goroutine 堆栈定位卡住位置

Go 服务最难受的一类故障是“进程还活着，但请求像被按了暂停键”：没有明显 panic，CPU 也不一定打满，连接却迟迟不返回。遇到这种情况，我通常先导出 goroutine profile，而不是马上打开 CPU 或内存分析。它给出的不是一条抽象指标，而是当前所有 goroutine 的调用栈和等待位置。

官方资料：https://pkg.go.dev/runtime/pprof　HTTP 处理器：https://pkg.go.dev/net/http/pprof

需要定位“谁在等、等在哪里、是不是很多 goroutine 都卡在同一条调用链”时，读取 runtime/pprof.Lookup("goroutine") 并用 debug=2 写出文本堆栈，通常是最短路径。

一、先选对要导出的 profile

我第一次处理这类问题时，最容易犯的错是把“卡住”直接等同于 CPU 慢。goroutine profile 的职责是展示当前 goroutine 的堆栈；它适合回答“执行停在什么地方”。如果要统计锁或 channel 等待时间，再考虑 block profile；如果要看锁竞争，再考虑 mutex profile。不要因为页面都叫 pprof，就把几种数据混成一种结论。

Go 官方把预置的 goroutine profile 定义为当前所有 goroutine 的堆栈集合。WriteTo 的 debug=0 适合 pprof 工具读取，debug=1 是可读的旧式文本，针对 goroutine profile 使用 debug=2 时，会输出更接近程序未恢复 panic 时的 goroutine 堆栈格式。

二、通过受控 HTTP 入口快速导出

服务已经有管理端口时，最省事的方式是导入 net/http/pprof，然后请求 goroutine 端点。这个包默认把处理器注册到 DefaultServeMux，路径都以 /debug/pprof/ 开头；当前文档还特别注明这些路径使用 GET 请求。

package main

import (
    "log"
    "net/http"

    // 只为注册 /debug/pprof/ 下的标准诊断处理器。
    _ "net/http/pprof"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        // 健康检查与诊断入口分开，便于后续限制访问范围。
        w.WriteHeader(http.StatusOK)
    })

    // 诊断端口只绑定本机；生产环境还应叠加鉴权或网络隔离。
    log.Fatal(http.ListenAndServe("127.0.0.1:6060", mux))
}

如果你使用自定义 mux，上面的匿名导入不会自动把处理器接到这个 mux 上。更稳妥的做法是显式注册需要的处理器，避免把整个 DefaultServeMux 暴露给管理端口：

mux.Handle("/internal/pprof/goroutine", pprof.Handler("goroutine"))

// 只开放 goroutine profile，避免无意间暴露其它诊断入口。
log.Fatal(http.ListenAndServe("127.0.0.1:6060", mux))

对应的读取命令可以保存为文本，便于先在事故目录里快速检索：

# debug=2 让 goroutine profile 输出可读的完整堆栈
curl --fail --silent --show-error \
  'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2' \
  > goroutine-$(date +%Y%m%d-%H%M%S).txt

想保留 pprof 的压缩数据供工具分析时，去掉 debug=2，直接把端点保存为文件，再交给 go tool pprof。文本适合第一眼找等待状态，二进制 profile 适合后续工具化处理。

三、没有 HTTP 时用信号触发文件导出

有些服务没有额外管理端口，或者卡住时 HTTP 处理链本身也不可靠。这时可以让进程接收一个约定信号，在进程内部调用同一个 profile API 写文件。信号接收循环只负责把事件交给导出 goroutine，文件写入不要塞进信号分发逻辑里。

package main

import (
    "fmt"
    "os"
    "os/signal"
    "path/filepath"
    "syscall"
    "time"

    "runtime/pprof"
)

func dumpGoroutines(dir string) error {
    // debug=2 输出每个 goroutine 的可读堆栈和等待信息。
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return fmt.Errorf("goroutine profile is unavailable")
    }

    if err := os.MkdirAll(dir, 0o750); err != nil {
        return err
    }
    name := filepath.Join(dir, "goroutine-"+time.Now().Format("20060102-150405")+".txt")
    file, err := os.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640)
    if err != nil {
        return err
    }
    defer file.Close() // 写完后立即关闭，避免诊断文件句柄泄漏。

    return profile.WriteTo(file, 2)
}

func waitForDumpSignal() {
    signals := make(chan os.Signal, 1)
    // SIGUSR1 仅作为示例；请按部署平台选择不会被业务占用的信号。
    signal.Notify(signals, syscall.SIGUSR1)
    defer signal.Stop(signals)

    for range signals {
        if err := dumpGoroutines("./diagnostics"); err != nil {
            fmt.Fprintln(os.Stderr, "goroutine dump failed:", err)
        }
    }
}

这个示例故意使用独占创建文件，避免同一秒收到两次信号时覆盖前一份现场。实际服务还应限制诊断目录的权限、控制文件保留数量，并把导出失败写入现有日志系统。不要把堆栈原文直接返回给不可信的 HTTP 调用方，因为其中可能包含业务路径、函数名和参数上下文。

四、从堆栈里的等待状态找卡点

拿到文本后，我不会只搜索某一个函数名，而是先看 goroutine 数量和状态是否集中，再看每个簇最靠近业务代码的那一帧。常见线索可以这样理解：

文本堆栈更适合发现“大家都在等什么”，但不能单独证明根因。例如看到很多 goroutine 都停在同一个读取函数，只能说明等待点集中，还要结合调用方是否设置超时、下游是否恢复以及同一时刻的请求日志来判断。这里的堆栈是现场快照，不是自动生成的因果证明。

五、入口收紧后再决定是否继续取样

诊断端点和信号都应该是运维能力，不应成为公开业务 API。HTTP 方案至少绑定内网地址，或挂在独立管理 mux 后增加认证、访问控制和速率限制；信号方案要写进部署文档，避免被平台的停止或重载信号误触发。导出的文件可能暴露源码路径、内部服务名和调用关系，保存周期与权限也要纳入事故处理规范。

如果一份 goroutine 快照已经看出大量锁等待，再转向 block 或 mutex profile；如果关心的是调度、系统调用和 GC 事件，再考虑 execution trace。Go 官方诊断文档也提醒，不同诊断工具可能互相影响，生产环境应一次收集一种主要 profile，并估算采集开销。

我自己的判断顺序是：先用一份 debug=2 快照确认“卡在哪里”，短时间后再取第二份确认“是否仍在同一位置”，最后才决定要不要扩大采集范围。两份堆栈都聚集在相同业务帧，通常比单次看到一个熟悉函数名更有价值。

相关问题

为什么不用 runtime/debug.Stack 代替 goroutine profile？

debug.Stack 更适合快速拿到当前 goroutine 的调用栈；要系统查看所有当前 goroutine，优先使用 runtime/pprof 的 goroutine profile。

debug=0 和 debug=2 应该怎么选？

需要交给 pprof 工具时使用 debug=0 的默认格式；事故现场想直接阅读全部 goroutine 状态时使用 debug=2。

导出堆栈后就能确定 goroutine 泄漏吗？

不能。快照能显示数量和调用栈的异常集中，是否泄漏还要用多个时间点、请求生命周期和退出条件一起确认。