Go pprof Profile.WriteTo 怎样控制 debug 输出级别

如果你在 Go 里调用 runtime/pprof.Profile.WriteTo 后发现文件打不开、终端里看不到可读文本，通常不是 Profile 没有采样，而是把 debug 当成“日志详细程度”了。它实际决定输出格式：0 适合保存为 pprof 数据供工具分析，1 适合直接阅读，goroutine profile 还对 2 定义了 panic 风格的堆栈输出。

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

最小判断可以记成：要交给 go tool pprof，用 debug=0；要在工单或终端里快速看函数和行号，用 debug=1；只有查看 goroutine 堆栈时，再考虑它专门定义的 debug=2。

先把 debug 当成输出格式开关

WriteTo 的签名是 WriteTo(w io.Writer, debug int) error。第一个参数决定写到哪里，第二个参数决定怎么写。它不是通用的采样倍率，也不会让 Profile 自动收集更多样本。

因此，“输出为空”与“输出不可读”要分开处理：前者先看 Profile 是否选对，后者先看是否把二进制的 debug=0 当成纯文本打开。

最小配方：保存可分析的 pprof 文件

默认推荐从 debug=0 开始。这个模式保留了 pprof 工具需要的结构，适合先落盘再分析，而不是把分析结果过早变成字符串。

package main

import (
    "log"
    "os"
    "runtime/pprof"
)

func saveProfile(path string) error {
    // 以二进制 pprof 格式保存，后续可以交给 go tool pprof。
    file, err := os.Create(path)
    if err != nil {
        return err
    }
    defer func() {
        // 关闭文件，避免采样文件句柄泄漏。
        _ = file.Close()
    }()

    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return nil
    }
    // debug=0 不是“最少采样”，而是标准压缩协议输出。
    return profile.WriteTo(file, 0)
}

func main() {
    if err := saveProfile("goroutine.prof"); err != nil {
        log.Fatal(err)
    }
}

这里的 goroutine.prof 不应该用文本编辑器判断内容是否正常。它的用途是继续执行类似 go tool pprof goroutine.prof 的分析操作；如果只是想在终端里读堆栈，见下一节。

需要人读时，用 debug=1 输出文本

debug=1 会输出旧式文本格式，并把地址翻译成函数名和行号注释。它适合把一次采样附在问题单里，也适合临时写入 bytes.Buffer 后打印。

package main

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

func printGoroutines() error {
    var buf bytes.Buffer
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return fmt.Errorf("goroutine profile is unavailable")
    }

    // debug=1 产生面向人的文本，便于排查调用栈和行号。
    if err := profile.WriteTo(&buf, 1); err != nil {
        return err
    }
    // 只在写入成功后输出，避免把不完整快照误当成完整结果。
    fmt.Print(buf.String())
    return nil
}

func main() {
    if err := printGoroutines(); err != nil {
        log.Fatal(err)
    }
}

这个模式的代价是输出更适合阅读，却不再是你保存给 pprof 工具的首选载体。实际排障时可以同时保留两份：一份 debug=0 原始文件，一份 debug=1 文本摘要。

goroutine profile 的 debug=2 不是通用“更详细”

预定义 Profile 可以给不同 debug 值定义自己的含义。对 goroutine 而言，debug=2 会按 Go 程序发生未恢复 panic 时接近的形式打印 goroutine 堆栈。因此它是某个 Profile 的特殊约定，不应该套用到 heap、allocs 或 block 等其它 Profile 上。

func writeGoroutineStacks(w io.Writer, level int) error {
    profile := pprof.Lookup("goroutine")
    if profile == nil {
        return fmt.Errorf("goroutine profile is unavailable")
    }

    // 只有 goroutine profile 使用 level=2 表达 panic 风格堆栈。
    if level != 1 && level != 2 {
        return fmt.Errorf("unsupported goroutine debug level: %d", level)
    }
    return profile.WriteTo(w, level)
}

如果你要的是机器分析文件，仍然应使用 0；如果你要的是人能快速定位阻塞位置的堆栈，1 或 2 才有意义。不要因为数字更大，就把它理解为采样更充分。

几个容易踩到的边界

• debug=0 输出不是损坏文件。它是压缩协议数据，应该交给 pprof 工具处理。
• WriteTo 的错误要保留。Writer 返回错误时，快照可能不完整，不能只看已经写出的前几行。
• Profile 类型决定特殊级别。不要把 goroutine 的 debug=2 规则推广到所有 Profile。
• 输出格式不等于采样质量。Profile 的内容还取决于所选 Profile、采样开关和采集时机。
• 调试输出和生产采集分开考虑。Go 的诊断工具可能带来开销，生产环境应单独评估采集频率和并发影响。

完整选择建议

可以把调用前的判断压缩成三句话：准备交给工具分析，就写 debug=0；准备让人直接读，就写 debug=1；只有明确处理 goroutine 堆栈，并且需要 panic 风格时，才写 debug=2。如果同时需要可追溯性，保留一份原始 pprof 文件，再生成一份文本副本，排查和复盘会更稳。

相关问题：

• 为什么用文本编辑器打开 debug=0 是乱码？因为它是 gzip 压缩的 pprof 协议缓冲，不是纯文本。
• debug=1 会不会增加采样数量？不会，它只改变写出时的表达形式。
• heap profile 能不能直接使用 debug=2？不要这样假设；特殊 debug 值要以具体 Profile 的文档约定为准。