Go pprof.Lookup 怎样读取 goroutine profile 文本

排查 Go 服务的 goroutine 数量时，不一定要先接入 HTTP 调试端点。只要在进程内拿到运行时自带的 profile，就可以把当前 goroutine 的调用栈写入一个 io.Writer。最直接的入口是 pprof.Lookup("goroutine")，然后调用 WriteTo(writer, 1) 读取适合人查看的文本。

官方文档：https://pkg.go.dev/runtime/pprof

要读取 goroutine profile 文本，关键不是自己解析运行时结构，而是先 Lookup 内置的 goroutine profile，再让 WriteTo 根据 debug 参数选择输出格式。人工排查通常用 debug=1，程序交给 pprof 工具继续处理时用 debug=0。

先把 Lookup 和 WriteTo 的职责拆开

runtime/pprof 预先维护了一组 profile，其中 goroutine 表示当前 goroutine 的调用栈集合。pprof.Lookup 只负责按名称取回 profile，真正把快照写出去的是 Profile.WriteTo。这两个动作分开后，输出目标可以是内存缓冲区、文件或网络响应，而不需要改变 profile 本身。

如果目标是先在代码里拿到字符串，可以用 bytes.Buffer。下面的示例只展示调用关系和错误处理，输出内容会随着进程当时的 goroutine 状态变化。

package main

import (
    "bytes"
    "fmt"
    "runtime/pprof"
)

// goroutineText 获取当前 goroutine profile 的可读文本。
func goroutineText() (string, error) {
    // 内置 profile 名称必须写成 goroutine，找不到时不能继续调用方法。
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return "", fmt.Errorf("goroutine profile not found")
    }

    var buf bytes.Buffer
    // debug=1 选择 legacy 文本，并把函数名、文件名和行号写进结果。
    if err := profile.WriteTo(&buf, 1); err != nil {
        return "", fmt.Errorf("write goroutine profile: %w", err)
    }
    return buf.String(), nil
}

这里的 WriteTo 读取的是一个 profile 快照。它不是把某个 goroutine 固定下来持续监听，也不会替调用方判断“哪条栈是泄漏”。要做泄漏分析，还要结合采集时机、数量趋势和业务生命周期来判断。

debug 参数决定你拿到什么输出

WriteTo 的第二个参数很容易被误读成“日志详细程度”。对预定义的 goroutine profile，它更接近输出格式选择：

因此，若接口返回值要给人直接阅读，使用 debug=1 更符合目标；若要保存成标准 profile 文件，不能把 debug=1 的字符串当作压缩协议数据，应该把 debug=0 的字节直接写入文件或响应体。

// writeProfile 按 debug 参数把 profile 写到指定 Writer。
func writeProfile(w io.Writer, debug int) error {
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return fmt.Errorf("goroutine profile not found")
    }
    // debug=0 保留 pprof 的机器可读格式，debug=1 才是可读文本。
    if err := profile.WriteTo(w, debug); err != nil {
        return fmt.Errorf("write profile with debug=%d: %w", debug, err)
    }
    return nil
}

这个函数的调用方需要自己决定 Writer 的生命周期。例如写文件时要负责关闭文件，写 HTTP 响应时要处理响应头和客户端断开；这些资源责任不由 Profile.WriteTo 自动接管。

把读取动作封装成一次性诊断入口

实际排障中，我更倾向于把“抓取一次 profile”和“决定是否打印”分开。这样既可以把文本交给日志系统，也可以限制输出长度，避免在 goroutine 数量异常时把一整份栈信息重复写入业务日志。

package diagnose

import (
    "bytes"
    "fmt"
    "io"
    "runtime/pprof"
)

// SnapshotGoroutines 将一次 goroutine 快照写入调用方提供的 Writer。
func SnapshotGoroutines(w io.Writer, panicStyle bool) error {
    if w == nil {
        return fmt.Errorf("profile writer is nil")
    }
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return fmt.Errorf("goroutine profile not found")
    }

    debug := 1
    if panicStyle {
        // goroutine profile 的 debug=2 使用更接近 panic 的堆栈布局。
        debug = 2
    }
    return profile.WriteTo(w, debug)
}

// TextSnapshot 适合测试或短期诊断，不负责把结果写入长期日志。
func TextSnapshot() (string, error) {
    var buf bytes.Buffer
    if err := SnapshotGoroutines(&buf, false); err != nil {
        return "", err
    }
    return buf.String(), nil
}

并发调用不需要额外给同一个 profile 加业务锁；官方文档说明 Profile 的方法可以由多个 goroutine 同时调用。真正需要控制的是你的日志体积、采集频率和敏感信息落盘策略。

常见误区与边界

• 把 debug=1 当成标准 profile 文件。它是给人读的 legacy 文本，不能直接替代 debug=0 的协议缓冲区。
• 把 goroutine profile 当成泄漏结论。它展示采集时刻的栈；是否泄漏，要结合重复采样、数量趋势和业务退出条件。
• 忽略写入错误。文件空间不足、网络客户端断开或自定义 Writer 出错时，WriteTo 会返回对应错误，不能只看已经写出的部分。
• 把 pprof.Lookup 与 HTTP 端点混为一谈。直接使用包 API 不会自动安装 /debug/pprof/ 路由；HTTP 入口需要按 net/http/pprof 的方式单独接入。

常见问题

为什么 Lookup("goroutine") 不是自己创建的 profile？

因为 goroutine 是 runtime/pprof 预定义的 profile 名称，运行时负责维护它。自定义 profile 应使用 pprof.NewProfile，不能拿预定义 profile 调用用于自定义数据的 Add 或 Remove。

想把 goroutine profile 写到文件，应该用哪个 debug 值？

如果文件要交给 pprof 工具继续处理，使用 debug=0 并直接把字节写入文件；如果文件只是给人打开阅读，使用 debug=1。两者的消费方式不同。

WriteTo 返回 nil 就代表没有 goroutine 问题吗？

不代表。返回 nil 只说明 Writer 没有报告写入错误。profile 是否显示异常、是否存在泄漏，需要由读者比较多次快照并结合服务生命周期分析。

总结

读取 Go 的 goroutine profile 文本可以固定成一条小路径：pprof.Lookup("goroutine") 获取内置 profile，检查 nil，再调用 WriteTo。人工阅读选 debug=1，工具处理选 debug=0，需要 panic 风格堆栈时再考虑 debug=2。最后把 Writer 错误、输出大小和重复采样策略交给调用方管理，才能把一次快照变成可靠的性能诊断入口。