Go pprof 看不到短函数的采样解释

在 Go pprof 里找不到一个“明明执行过、而且很短”的函数，通常不是函数没有运行，而是 CPU profile 没有在它活跃的那几个瞬间采到它。pprof 记录的是离散采样时刻的调用栈，不是把每次函数调用都登记下来。因此，短函数执行时间短、调用次数少，或者只在很短的请求窗口里出现时，都可能没有形成独立排名。

官方地址：https://pkg.go.dev/runtime/pprof

这篇只处理 CPU pprof 的“短函数看不到”问题：先判断采样边界，再同时看 flat 和 cumulative，最后用源码定位命令复查。不要把 CPU profile 的空白直接解释成业务代码没有执行，也不要拿 heap、block 或 mutex profile 的结果替代 CPU 结论。

先确认：pprof 看到的是采样，不是调用清单

CPU profile 可以理解为在运行期间定期观察当前正在消耗 CPU 的调用栈。一次观察没有落在目标函数身上，就不会为这个函数增加样本。函数即使被调用过，只要单次执行很短，且没有足够多的重复工作，最终列表里也可能看不到它。

下面这段示例只用于说明采样对象的关系，不代表本文在本机运行过。真正排查时，先让同一类请求持续产生稳定负载，再看 profile 的统计结果。

package main

import (
	"os"
	"runtime/pprof"
)

func handleRequest() {
	// 业务调用链里包含一个执行很快的函数。
	shortFunction()
}

func shortFunction() {
	// 函数执行时间短，不等于 CPU profile 一定会命中它。
	_ = 1 + 1
}

func collectProfile(file *os.File) error {
	// 采样结束时必须停止 profile，确保缓冲数据写入文件。
	if err := pprof.StartCPUProfile(file); err != nil {
		return err
	}
	defer pprof.StopCPUProfile()
	return nil
}

示例展示的是 profile 的生命周期：开始采集，保持业务负载，结束时停止采集。短函数的“消失”首先是统计可见性问题，而不是由列表为空直接证明代码没有执行。

同时看 flat 和 cum，别只盯着一个排名

pprof 的 flat 更接近“采样时刻正落在这个函数自身”的数量；cum 则把这个函数作为调用链祖先时，下面调用栈产生的样本也纳入。一个短函数自身耗时很少，flat 可能接近零，但如果它调用了较重的下游逻辑，cum 仍然可能明显。

# 先看自身耗时，确认短函数是否直接被采到
go tool pprof -top profile.pb.gz

# 再看调用链累计耗时，避免漏掉“自己很短、下游很重”的函数
go tool pprof -top -cum profile.pb.gz

# 在交互界面里按函数名查看源码行和累计样本
go tool pprof app profile.pb.gz
# pprof> list shortFunction
# pprof> weblist shortFunction

如果 -cum 能看到上层函数，而 flat 看不到短函数，先把结论写成“短函数没有形成足够的自身样本”，不要写成“短函数没有执行”。如果两种视角都没有它，再继续检查采样窗口、负载是否命中目标路径以及函数名是否被内联或拆分显示。

把采样窗口和有效负载拉长

短函数最常见的排查误区，是只采集一次很短的请求。更稳妥的做法是固定同一组请求，让业务路径重复出现，并把 CPU profile 的观察窗口延长到足以覆盖多个请求周期。窗口越短，越容易把偶然的“未命中”误读成“未执行”。

# 采集固定窗口的 CPU profile，窗口内保持同一类请求
curl -o profile.pb.gz "http://127.0.0.1:6060/debug/pprof/profile?seconds=30"

# 用源码函数名过滤，减少无关调用链对观察的干扰
go tool pprof -focus='shortFunction|handleRequest' app profile.pb.gz

# 只调低显示阈值，帮助观察小样本节点；它不会制造新的样本
go tool pprof -nodefraction=0 app profile.pb.gz

过滤参数只改变展示范围，不能把没有采到的函数补进 profile。-nodefraction=0 也只是降低图或列表的显示门槛，所以它适合做复查，不是提高采样概率的开关。若请求本身很少，优先增加可重复的工作量，再讨论显示参数。

从排名追到源码行

采样窗口稳定后，按“排名—函数—源码行”的顺序复查最省时间：先用 top 找到相关调用链，再用 list 看函数源码行的 flat/cum 分布，最后用 weblist 把源码和汇编级热点关联起来。短函数不出现在前几名时，不代表它绝对没有样本，可能只是被默认阈值或排名截断隐藏了。

# 先把输出范围扩大到前 20 个调用点
go tool pprof -top -nodecount=20 app profile.pb.gz

# 对指定函数查看源码行的 flat 与 cumulative 样本
go tool pprof -list=shortFunction app profile.pb.gz

# 需要源码和指令关联时再使用 weblist
go tool pprof -weblist=shortFunction app profile.pb.gz

这一步的检查点是：目标函数是否出现在调用栈、它的 flat 是否很小、它的 cum 是否来自下游调用，以及源码行是否与预期路径一致。只有这些信息都对不上时，才需要回到业务入口确认请求是否真的经过了该函数。

最后确认：不要看错 profile 类型

CPU profile 关注正在消耗 CPU 的调用栈；heap 关注内存分配样本；block 和 mutex 关注阻塞或锁竞争。短函数在 CPU profile 里不可见，并不能用 heap profile 的结果补证。Go 官方诊断文档也建议把不同 profile 分开采集，因为某些诊断工具会相互影响。

可以用下面的速查表收尾：

常见问题

短函数调用次数很多，为什么仍然看不到？

调用次数多不等于累计 CPU 时间足够。若每次都在两个采样时刻之间完成，或者请求窗口太短，命中数仍可能很少；先让相同负载持续更久，再用 -cum 和 list 复查。

把 -nodefraction=0 打开后，能保证短函数出现吗？

不能。它只降低显示过滤条件，不会改变已经采集的样本。真正影响可见性的优先级是：profile 类型正确、目标路径确实被重复执行、采样窗口足够长，最后才是显示参数。