Go pprof.Lookup 找不到自定义 Profile 的排查方法

如果 pprof.Lookup("your-name") 返回 nil，它只说明当前进程里没有名称完全匹配的 Profile。最常见的原因不是 pprof 失效，而是自定义 Profile 尚未用 NewProfile 注册、查找字符串有细微差异，或者查找发生在注册逻辑之前。先把“注册名”和“查找名”收敛成一个常量，再用 Profiles() 列出当前已知对象，排查会快很多。

先把注册名和查找名固定下来

自定义 Profile 的最小闭环是：用一个稳定名称注册，业务代码把条目加入 Profile，诊断代码再用同一个名称取回它。名称最好集中定义，不要在不同文件里手写几遍。官方文档还建议使用类似 import/path. 的前缀建立命名空间，名称不要包含空格。

package monitor

import (
    "runtime/pprof"
)

const requestProfileName = "example.com/checkout.requests"

var requestProfile = pprof.NewProfile(requestProfileName)

func trackRequest(requestID string) func() {
    // Add 记录当前调用栈；requestID 必须能作为 map 的键。
    requestProfile.Add(requestID, 0)
    return func() {
        // 请求结束时移除条目，避免把已结束请求长期留在 Profile 中。
        requestProfile.Remove(requestID)
    }
}

func findRequestProfile() *pprof.Profile {
    // 只能使用与注册时逐字一致的名称，找不到时返回 nil。
    return pprof.Lookup(requestProfileName)
}

这里的 requestProfile 在包级初始化时注册，因此诊断函数调用时已经存在。若把 NewProfile 放进每次请求的函数里，第二次调用会因同名注册而 panic；若业务入口和诊断入口各自声明不同字符串，Lookup 就会稳定返回 nil。

从名称、注册时机和命名空间三处排查

遇到“找不到自定义 Profile”，建议按下面的表逐项核对。不要先改成 heap 或 goroutine 试图证明接口可用，那些是预定义 Profile，不能替代你的自定义对象。

如果 Profile 来自另一个包，名称前缀也是接口的一部分。example.com/checkout.requests 和 checkout.requests 是两个不同名称；不要为了“短一点”在查找处删掉前缀。

用 Profiles 和 Count 确认问题在哪

当日志只告诉你“查不到”时，可以先枚举名称，再判断数量。Profiles() 返回所有已知 Profile 并按名称排序；它能证明注册状态，但不能证明自定义条目已经被加入。

package main

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

func dumpProfile(name string) error {
    // 先枚举名称，确认问题是“未注册”还是“查找字符串不一致”。
    for _, profile := range pprof.Profiles() {
        fmt.Printf("profile=%s count=%d\n", profile.Name(), profile.Count())
    }

    profile := pprof.Lookup(name)
    if profile == nil {
        // nil 只表示名称不存在，不代表其他预定义 Profile 也不可用。
        return fmt.Errorf("profile %q is not registered", name)
    }

    file, err := os.Create("custom-profile.pb.gz")
    if err != nil {
        return err
    }
    defer file.Close() // 文件句柄由当前导出函数负责关闭。
    // debug=0 写出压缩的 pprof 数据；需要人读的文本可考虑 debug=1。
    return profile.WriteTo(file, 0)
}

这段诊断要分成两个结论：列表里没有目标名称，说明注册或命名有问题；列表里有目标名称但 Count() 为零，说明 Profile 存在，只是当前没有活动条目。若条目在请求结束时立即 Remove，导出时为零也可能是正确结果。

自定义 Profile 与预定义 Profile 的边界

自定义 Profile 适合记录需要显式结束的资源，例如文件、连接或请求；Add 和 Remove 应该成对出现。预定义 Profile 会自行维护，不能对它们直接调用这些方法。CPU profile 也不是普通 Profile，它通过 StartCPUProfile 和 StopCPUProfile 把数据流写入指定 Writer。

如果目标是在线查看标准诊断数据，可以导入 net/http/pprof 暴露的 HTTP 处理器；如果目标是验证自定义对象，优先保留名称常量、枚举列表和 Count 日志，这三项足以把“没注册”“名称错”和“没有活动条目”区分开。

相关问题

为什么 NewProfile 重复调用会 panic？

Profile 名称必须唯一。把注册放到包级变量或单次初始化中，业务请求只负责 Add 和 Remove。

Profiles 能否替代 Lookup？

不能。Profiles 适合枚举和诊断，Lookup 适合按确定名称取得对象；两者返回的是不同层次的信息。

Count 为零是否代表 Profile 失效？

不一定。它只代表当前没有记录条目，还要结合 Add/Remove 生命周期判断；只要 Name 能回读且对象在 Profiles 列表中，注册本身就是成功的。