一串裸 uint64,怎么攒成一份 pprof 文件?

一串裸 uint64、五张表,和那个把账本写成文件的抄账员

你大概用 go tool pprof 打开过一份 cpu.pprof,火焰图一展开,函数名、行号、耗时都在上面。但很少有人反过来问:从 pprof.StartCPUProfile(f) 到 StopCPUProfile() 之间,那个文件是怎么一个字节一个字节攒出来的 ?runtime 交到这一层的,不是结构体,也不是文本,而是一串光秃秃的 uint64------第一格写长度、第二格是时间戳、第三格是样本数、后面跟一摞 PC 地址。要把这串数字变成 go tool pprof 认得的档案,中间得经过三层翻译。

这篇文章从 go1.24.0 的 proto.go(766 行)、map.go(90 行)与 protobuf.go(141 行)出发,顺着源码讲清这件事:一个叫 profileBuilder 的「抄账员」,怎么把 runtime 的裸记录流按「栈 + 标签」去重累加,把每个栈翻译成 Location / Function / Mapping 三张表,再用一百多行手写的 protobuf 编码器把字节灌进 gzip,最后封成 gzip(protobuf(Profile))。为什么不直接用现成的 protobuf 库、长度前缀为什么要先写到尾部再搬回头部、内联展开的一串伪 PC 怎么折回一个 Location------这些反直觉的写法,全都有它非这么写不可的理由。

读法上先说好三件事:代码块右侧的 // ← 是逐行注释,行号都是 go1.24.0 的实际行号;每一节先给一张数据流画面(一个能放电影的比喻),再上源码逐行,最后拆本节对应的难点;文中 §2.4 这类写法只是本文自己的小节号 (第 2 节第 4 小节),「难点 A~J」是本文给十个最容易卡住的问题起的代号,每一个都做成带问题标题的小节、挂在讲它的那一节末尾------按名字找就行,不需要对照任何别的资料。源码块一条注释都不省,白话只是帮你把画面立起来。


本文会讲什么

文章按源码从上往下走,但可以记成四条线索:

  1. 档案与抄账员 :一份 Profile 的五张表、string_table 为什么单独一张,以及 profileBuilder 身上挂了哪些状态(§1~§2)
  2. 一笔账走完全程 :裸 uint64 记录流 → addCPUData 解析 → profMap 去重 → build 遍历封包(§3~§5、§9)
  3. 栈到表的四道翻译 :allFrames 展开、pcDeck 折叠内联、emitLocation 写 Location / Function、parseProcSelfMaps 找模块(§3、§6~§8)
  4. 字节与收束 :flush 的刷盘边界、varint 与三次 copy、gzip 收尾,再收成十条不变量、九个易错点和一张复述卡(§2、§10~§14)

卡住时可以直接查「黑话速查表」(§0.4),或按「行号对照表」(§0.5)跳到对应难点;想快速复习,直接翻「一页纸速查」(§12)和「五分钟复述卡」(§14)。


0 导读:先把画面立起来

0.1 先说结论:一句话、三句话、先给你半句答案

一句话 profileBuilder 就是那个「抄账员」:它把 runtime 吐出的一串裸 uint64 记录,先按「栈 + 标签」去重累加,再把每个栈翻译成 Location / Function / Mapping 三张表,最后用一百多行手写的 protobuf 编码器把字节灌进 gzip,封成一份 cpu.pprof。

拆成三句话:

  1. 输入不是文本,是流水账 :上游交来的是 [3+n]uint64 这样的裸记录流,第一格写长度、第二格是时间戳、第三格是样本数、后面是栈;本文这一层是消费端,第一件事就是按约定把数字重新切回语义。
  2. 中间全是「去重」 :函数名只存一份(string_table + stringIndex)、同栈样本即时合并(profMap)、内联展开的多个伪 PC 折回一个 Location(pcDeck)------三处去重,把「每秒上百条」压成一份能看的文件。
  3. 输出是手工字节,不是调用库 :runtime/pprof 不能依赖 protoc 生态,所以自己写了一个只「写」不「读」的编码器;长度前缀事后才知道,就用「尾部追加 + 三次 copy」把前缀挪到前面。

读到这里,你可能会冒出下面几个疑问。别急着弄懂------先把每问的半句答案摆在这儿,知道后面要解开什么就够了;每一问在后文都有同名的小标题,会把它拆开讲透。

你可能会问 先给你半句答案
一份 pprof 文件最外层是什么?Profile 里为什么要单独放一张 string_table? 最外层是 gzip 包住的 protobuf(Profile);单独放 string_table,是因为函数名重复率极高,登记一次后处处只写页码。
手写 protobuf 编码为什么不直接用现成的库?它只实现了哪一半? runtime/pprof 是标准库最里层之一,不能依赖带 reflect 的 protoc 生成链;这个编码器只「写」不「读」,解析交给 go tool pprof。
varint 和 field number 在字节里到底怎么摆? 字节里没有字段名,先写「字段号左移 3 位按位或 wire_type」的 key;值用 varint 按 7 位一组拆,小数字只占 1 字节。
长度前缀明明写在头部,为什么源码先把它追加到尾部? 长度是 varint、不定长,写完内容才知道占几字节,预留不是浪费就是放不下;所以先追加到尾部,再用三次 copy 搬回头部。
明明抓到的是「一长串 PC」,文件里怎么变成一个带 line[] 的 Location? pcDeck 把编译器给内联帧留的 NOP 伪 PC 按三条启发式折成一堆,emitLocation 定稿成一个 Location,line[] 里装内联链。
缓冲刷盘为什么非要等 nest == 0? nest 记录当前套在第几层消息里;不为 0 就有子消息写到一半、长度前缀还没回填,此时刷盘会把半截消息送进 gzip,文件就坏了。
首记录是样本吗?100Hz 换成多少纳秒?溢出记录怎么归账? 首记录不是样本,是周期元数据,100Hz 换成 10,000,000 纳秒就消费掉;溢出记录以 count==0 且栈长 1 认出,伪栈归到 lostProfileEvent 名下。
同栈样本靠什么即时合并?为什么不直接用 map[string]? 靠 profMap.lookup(stk, tag).count += count 对 []uint64 滚动哈希即时累加;用 map[string] 得先把栈序列化成字符串,每秒上百条光分配就吃不消。
新函数为什么要攒到 Location 写完才补写?缓存为什么要拷贝切片? 子消息内容区不能再开子消息,Function 插进去会被算进 Location 长度,所以先记进 newFuncs 后补写;deck 复位会复用底层数组,缓存不拷贝就被覆写。
/proc/self/maps 里为什么只留可执行段?读不到怎么办? PC 只可能落在代码上,所以按权限位第 3 位是不是 x 来筛;maps 读不到就加一个 fake mapping 全收所有地址,保证文件照样能生成。

关于「难点 A~J」 :它们不是另附的习题,就是后文十个小节的标题,例如「难点 J|三次 copy 杂技:长度前缀为什么先追加到尾部」。上面每一问都能按标题直接找到;§2.4 也只是本文的小节号,翻到那一节即可。

0.2 站在流水线的哪一段:抄账员,以及为什么难

先用四个角色给整条 CPU 剖析流水线对号入座,看看本文的舞台在哪儿:

text 复制代码
   ① 闹钟(内核定时器,每 10ms 一响)
           │
           ▼
   ② 被拍肩的工人(sigprof 抓下调用栈)
           │
           ▼
   ③ 环形账本 profBuf(无锁,写满就丢)
           │  read 借出 [3+n]uint64 记录流 + 平行的 tags
           ▼
   ┌───────────────────────────────────────────────┐
   │  ④ 抄账员 · profileBuilder(本文的舞台)       │
   │                                               │
   │    解析记录流 → profMap 按 (栈, tag) 去重累加    │
   │    build 遍历 → 栈转 Location / Function        │
   │    手工 protobuf 编码 → gzip → 一份 pprof 文件   │
   └───────────────────────────────────────────────┘
           │
           ▼
      cpu.pprof → go tool pprof → 火焰图

③ 那本账本在信号处理器里被写入,只写得进数字格子,既不能上锁、也不能构造 Go 结构体;所以跨过 ③→④ 边界的,只能是「一串 uint64 + 平行的标签指针」。本文只管框起来那一段:拿到账之后,怎么把它写成一份文件。

为什么这段读起来不直观 :因为它不是「一个算法」,而是三层翻译叠在一起,而且每层用的都是另一套语言。

层 手里是什么 要变成什么 对应源码
第一层 裸 uint64 记录流(runtime 的黑话) 结构化样本(栈、标签、计数) §4 addCPUData
第二层 PC 地址、内联展开帧 Location / Function / Mapping 三张表 §3、§6~§8
第三层 表里的字段 protobuf 字节 + gzip 流 §2、§10

再叠三个「环境限制」,代码就必然长得绕:

现实的麻烦 源码的对策
不能依赖 protoc 生成的 .pb.go(带 reflect / 初始化开销) 手写只「写」不「读」的编码器(§10、难点 B)
字符串重复率极高(函数名几万次) 全走 string_table,字段里只存索引(§1、难点 A)
样本流每秒上百条,不能每条都分配字符串 key profMap 直接对 []uint64 做滚动哈希(§9、难点 H)
gzip 要流式写,不能把整个文件攒在内存 flush 每 4KB 下刷一次、且只在消息边界刷(§2、难点 C)
编译器内联把一帧展开成好几个伪 PC pcDeck 状态机把它们折回去(§6、难点 E)

一句话记住 :这里不关心「怎么抓样本」,只关心「抓完之后,怎么把一串数字整理、去重、翻译、装箱」。难的不是某一行位运算,是上游是 runtime 的黑话、下游是 proto 的字节规范,中间还得一边去重一边流式输出。

0.3 全局地图:一份 pprof 文件是怎么攒出来的

把整份源码当成一条装配线看就不乱了:

text 复制代码
  profBuf.read  ──►  data []uint64 + tags
        │
        ▼
  ┌──────────────────────────────────────────────┐
  │  addCPUData(§4)                             │
  │   首记录解析周期 hz → period = 1e9 / hz        │
  │   逐条切出 count / stk / tag                   │
  │   溢出记录 → 归罪 lostProfileEvent             │
  │   b.m.lookup(stk, tag).count += count          │
  ├──────────────────────────────────────────────┤
  │  profMap(§9)按 (栈, tag) 去重累加            │
  │  all 链按插入序保存全部条目                     │
  ├──────────────────────────────────────────────┤
  │  build(§5)遍历 all 链                       │
  │    values[0]=count, values[1]=count×period    │
  │    appendLocsForStack:栈 → Location id 列表   │
  │      ├─ allFrames(§3)符号化展开              │
  │      ├─ pcDeck.tryAdd(§6)折叠内联            │
  │      └─ emitLocation(§7)写 Location/Function │
  │    pbSample → 写一条 Sample                    │
  │  写 Mapping / StringTable / 头部字段            │
  ├──────────────────────────────────────────────┤
  │  protobuf(§10)字节缓冲 + flush(§2)         │
  │    varint / length / packed / 三次 copy        │
  └──────────────────────────────────────────────┘
        │
        ▼
  gzip.Writer(BestSpeed)→ io.Writer → cpu.pprof

一句话读图 :左边进的是「一串数字」,右边出的是「一份压缩文件」;中间那个大方框里,上半段在去重、下半段在编码 ,build 是上下两半的分界线。读源码容易晕,很大程度是因为它按文件从上往下讲(先讲字段常量、再讲小工具、最后才讲编码器和 profMap),而人脑是按数据流动理解的------所以 §11 会先带你把一条记录跑完全程,再回头拆零件。

0.4 黑话速查表(读不下去时先翻这里)

用法:遇到不认识的词,先查「通俗解释」那一列,能继续读就不必深究;想追根问底再按第三列跳。

黑话 通俗解释 本文位置
Profile 一份剖析档案的最外层消息,pprof 工具读的就是它 §1
gzip(protobuf(Profile)) 文件最外层封装:先编码成字节,再整体压缩 §1、§5
五张表 sample_type / sample / mapping / location / function,档案的五张主表 §1
string_table 字符串字典:所有名字只登记一次,别处只写页码 §1
ValueType 列定义:一列数据叫什么、单位是什么 §1、§2
Location.line\[\] 一个栈帧里的「内联链」:一串函数 + 行号 §1、§7
sample.location_id 数据行只存 Location 的编号,不重复存栈 §1
protobuf wire format 字节层面的编码规矩:字段号 + 类型 + 值怎么摆 §10
varint / LEB128 变长整数:小数字占 1 字节,大数字才多占 §10
field number / tag 字段编号,proto schema 里写死的 1、2、3...... §1、§10
wire_type 这个字段的值怎么摆:0=单个数、2=带长度的一段 §10
packed 编码 一串数字打包成「一个 key + 总长度 + 连续值」 §10
tag 常量表 把 proto 字段号手抄成 Go 常量(70~129 行) §1
profileBuilder 抄账员本人:持有全部中间状态的那一个大结构 §1
start / end 构建开始与结束时间 → time_nanos / duration_nanos §1、§5
havePeriod / period CPU 专属:采样周期(纳秒),由首记录的 hz 换算 §1、§4
stringIndex 「字典登记员」:查不到就追加,返回页码 §2
stringMap 名字 → 页码的反查表,避免重复登记 §1、§2
flush / dataFlush=4096 缓冲满 4KB 就往 gzip 里灌一批 §2
nest 当前套了几层消息;不为 0 时禁止刷盘 §2、§10
pb* 三明治 startMessage → 写字段 → endMessage 的固定写法 §2
startMessage / endMessage 子消息开写 / 收尾回填长度前缀 §10
三次 copy 杂技 长度前缀先追加到尾部,再整体搬移回头部 §10
tmp 16byte 搬移时暂存 key + 长度的小草稿纸 §10
int64Opt / uint64Opt 值为 0 就干脆不写这个字段(省字节) §2、§10
allFrames 把一个 PC 展开成若干 frame(含内联链) §3
runtime.CallersFrames runtime 提供的 PC → 函数 / 文件 / 行号翻译器 §3
locInfo PC → Location 的缓存条目,命中就免符号化 §3、§7
firstPCFrames 缓存里叶 PC 的展开结果,喂给 deck 复用 §3、§6
pcDeck 把内联展开的多个伪 PC 折回一个 Location 的状态机 §6
NOP 伪 PC 编译器为每层内联留的空指令地址,混在栈里 §6
tryAdd 三判据 Func / Entry / Name 三条启发式,判断能否合并 §6
emitLocation 把 deck 里攒好的内容写成一个 Location 消息 §7
newFuncs 先攒着、Location 写完才补写的函数表新条目 §7
funcs 函数全名 → Function.ID 的表 §1、§7
mapping / memMap 加载进内存的模块(二进制 / 共享库)条目 §1、§8
parseProcSelfMaps 读 /proc/self/maps,只挑可执行段 §8
buildID 二进制构建指纹,pprof 据此配对符号 §1、§8
fake mapping 平台读不到 maps 时的兜底假条目,全收所有地址 §8
symbolizeFlag 符号化结果标记:lookupTried / lookupFailed §1、§3
readMapping 三种平台实现各自把模块表填进 b.mem §8
addCPUData 消费记录流、解析并去重累加的入口 §4
3+nuint64 记录 一条流水账:长度 / 时间 / 样本数 / 栈 §4
lostProfileEvent 自递归伪函数,溢出丢的样本记在它名下 §1、§4
溢出记录 count==0 且栈长 1 的特殊记录,是丢件补报 §4
profMap 按 (栈, tag) 去重累加的哈希表(map.go) §9
滚动哈希 / 乘 41 逐 PC 左旋 8 位再加 41 倍,算出桶号 §9
move-to-front 命中就把条目提到链头,热栈下次更快 §9
free / freeStk 成批分配的条目池与栈池,避免每条都 new §9
gzip.BestSpeed 压缩率换 CPU:剖析数据要写得快 §3
build 遍历去重表、翻译栈、封包、收尾 gzip §5

0.5 源码行号 ↔ 难点 ↔ 配图对照表

用法:读到某一节卡住,在这张表里找到它,先看「先看的白话」那一格,再回源码。「初读可跳过」打「可以」的,允许先糊弄过去,回头再补。

源码位置 在讲什么 先看的白话 配图 初读可跳过
§1 · 20~129 行 Profile 五张表、builder 字段、tag 常量表 §1.1「档案柜」、难点 A / B 图 10-1、图 10-2
§2 · 131~207 行 stringIndex / flush / pb* 三明治 §2.1「登记员与装箱工」、难点 C ---
§3 · 209~272 行 allFrames 单地址展开、locInfo 缓存 §3.1「单地址翻译器」 --- 可以
§4 · 274~345 行 addCPUData 首记录、主循环、溢出 §4.1「拆包裹」、难点 D ---
§5 · 347~392 行 build 遍历去重表、封包收尾 §5.1「交账」 ---
§6 · 394~580 行 appendLocsForStack、pcDeck 折叠 §6.1「折叠机」、难点 E 图 10-3
§7 · 582~657 行 emitLocation 写 Location / Function §7.1「定稿」、难点 F ---
§8 · 659~766 行 mapping 与 parseProcSelfMaps §8.1「查地图」、难点 G --- 可以
§9 · map.go 全文 profMap 去重哈希、池、MTF §9.1「减压阀」、难点 H --- 可以
§10 · protobuf.go 全文 varint / packed / 三次 copy §10.1「只带一把螺丝刀」、难点 I / J 图 10-4
§11 · 串讲 一条 CPU 记录走完全程 全节 图 10-2

1 认识这份档案与攒档案的人:Profile 五张表 + profileBuilder(20~129 行)

1.1 先建画面:一个档案柜、一本字典

把一份 .pprof 想成一个档案柜:柜子里有五张主表------sample_type 是列定义、sample 是数据行、mapping 是加载进内存的模块、location 是栈帧、function 是函数。柜子旁边还单独立着一本字典 string_table:所有函数名、文件名、单位名先登记进字典,拿到一个页码,五张表里凡是碰到名字的地方,一律只写页码,不写字母。

这么摆是有代价的:读表的人得来回翻字典。但回报更大------一个跑了几秒的程序,main.worker 这个名字可能在栈里出现几万次,写进字典只要一次,页码走 varint 编码通常只占一两个字节。而抄账员 profileBuilder,就是那个一边翻字典、一边往五张表里填格子、最后把整个柜子压缩封箱的人。

1.2 Profile 消息的五张表

一份 .pprof 文件 = gzip(protobuf(Profile)) 。把最外层那层 gzip 撕掉,里面是一个 Profile 消息,结构如下:

scss 复制代码
Profile
├── sample_type[]  ValueType{type,unit}        ← 列定义(如 samples/count + cpu/nanoseconds)
├── sample[]       Sample{location_id[], value[], label[]}   ← 数据行
├── mapping[]      Mapping{start,limit,offset,file,buildID}  ← 加载的模块(二进制/共享库)
├── location[]     Location{id, mapping_id, address, line[]} ← 栈帧(PC);line[] 是内联链!
├── function[]     Function{id, name, filename, start_line}
├── string_table[] string                      ★所有字符串先入表,字段里存索引
├── time_nanos / duration_nanos / period_type / period / default_sample_type
└── drop_frames / keep_frames / comment[]

图 10-1 Profile 消息结构与 gzip 封包:一份 .pprof = gzip(protobuf(Profile)),五张主表加一本 string_table 字典,函数名只登记一次、字段里存页码索引。

看图时抓三处:五张主表里 sample / location / function 怎么靠 id 互相引用、string_table 为什么单独成表、gzip 为什么包在最外层;对应 §1.2、§5 与难点 A / B。

三个设计要点,后面每一节几乎都在给它们打地基:

  1. 字符串全走 string_table------重复的函数名 / 文件名只存一份,字段只存 int 索引(varint 压缩后极小);
  2. Location.line 是列表 ------一串「函数 + 行号」表示一条内联链(a 被 b 内联,一个 Location 表达多层调用);
  3. sample.location_id 引用 location 表------同一栈的样本在 sample 里只出现一次(生产端已去重),pprof 工具按 id 组装火焰图。

1.3 profileBuilder:抄账员身上挂了什么

图 10-2 builder 攒文件流程:解析记录流 → profMap 按 (栈, tag) 去重累加 → build 遍历 → 栈转 Location → 手工编码 + gzip,前一半整理账、后一半装箱。

看图时抓三处:左边进的是裸 uint64 记录流、中间 profMap 是那只去重漏斗、右边 gzip.Writer 是唯一的出口;对应 §1.3、§4 与难点 A / B。

先看一个陪衬用的伪函数,再抄结构本身:

go 复制代码
// lostProfileEvent is the function to which lost profiling
// events are attributed.
// (The name shows up in the pprof graphs.)
func lostProfileEvent() { lostProfileEvent() }   // ← 23:伪函数------溢出丢样本记在它名下
                                                  //     (自递归防编译器内联掉;pprof 图里能看到它)
                                                  // ← 24
// A profileBuilder writes a profile incrementally from a
// stream of profile samples delivered by the runtime.
type profileBuilder struct {
	start      time.Time              // ← 28:构建开始(→ time_nanos)
	end        time.Time              // ← 29:结束(→ duration_nanos)
	havePeriod bool                   // ← 30:是否已从数据头解析出周期(CPU 专属)
	period     int64                  // ← 31:采样周期(纳秒)
	m          profMap                // ← 32:样本去重表(map.go,见 §9)
	                                                  // ← 33
	// encoding state
	w         io.Writer              // ← 35:最终输出
	zw        *gzip.Writer           // ← 36:gzip 层
	pb        protobuf               // ← 37:字节缓冲(见 §10)
	strings   []string               // ← 38:string_table 累积
	stringMap map[string]int         // ← 39:字符串 → 索引
	locs      map[uintptr]locInfo    // ← 40:PC → Location 信息缓存(命中免符号化)
	funcs     map[string]int         // ← 41:函数全名 → Function.ID
	mem       []memMap               // ← 42:mapping 表
	deck      pcDeck                 // ← 43:内联折叠状态机(见 §6)
}                                               // ← 44

把这 16 个字段翻成「行李清单」,就是抄账员随身带的全部家当:

字段 通俗解释:装的是什么
start / end 开工 / 收工时间,分别写进 time_nanos / duration_nanos
havePeriod / period CPU 剖析专属:有没有解析出周期、周期多少纳秒
m 样本去重表,§9 的主角
w 最终输出目的地(文件 / HTTP 响应)
zw gzip 压缩层,字节先过它
pb 未压缩的字节缓冲,§10 的主角
strings / stringMap 字符串字典与「名字 → 页码」反查表
locs PC → Location 缓存,命中免符号化
funcs 函数全名 → Function.ID
mem 模块表,Location 要指明自己属于哪个模块
deck 内联折叠状态机,一次只装一个 Location 的料

再往下是模块条目与符号化标记:

go 复制代码
type memMap struct {                     // ← 46:一个内存映射条目
	// initialized as reading mapping
	start   uintptr   // ← 48:模块加载起始地址
	end     uintptr   // ← 49:结束地址
	offset  uint64    // ← 50:文件内偏移
	file    string    // ← 51:文件路径
	buildID string    // ← 52:构建指纹(pprof 据此配对符号服务器)
	                                                   // ← 53
	funcs symbolizeFlag  // ← 54:该 mapping 的符号化结果
	fake  bool           // ← 55:true=伪造的映射(/proc/self/maps 不可用时兜底)
}                                                       // ← 56
                                                        // ← 58~62:symbolizeFlag 注释------0/试过/试过失败
type symbolizeFlag uint8                                // ← 63
                                                        // ← 64
const (                                                 // ← 65
	lookupTried  symbolizeFlag = 1 << iota              // ← 66:1
	lookupFailed symbolizeFlag = 1 << iota              // ← 67:2
)                                                       // ← 68

这里有三张「只增不减」的表值得先记一笔,后面会反复用到:

表 键 → 值 谁往里写 为什么敢只增不减
strings + stringMap 名字 → 页码 stringIndex 剖析时长有限,字典不会无限大
locs PC → locInfo emitLocation 见过的地址缓存起来,下次直接命中
m(profMap) (栈, tag) → profMapEntry addCPUData 只增不减,剖析时长有限,可接受

1.4 tag 常量表:把 schema 手抄成 Go

70~129 行是 proto 字段号常量表------与 pprof 格式约定的字段号一一对应,逐块列出(注释列即 proto 字段类型):

块 行号 字段(号 → 含义)
Profile 72~85 SampleType=1, Sample=2, Mapping=3, Location=4, Function=5, StringTable=6, DropFrames=7, KeepFrames=8, TimeNanos=9, DurationNanos=10, PeriodType=11, Period=12, Comment=13, DefaultSampleType=14
ValueType 88~89 Type=1, Unit=2(都是 string_table 索引)
Sample 92~94 Location=1(repeated uint64), Value=2(repeated int64), Label=3
Label 97~99 Key=1, Str=2, Num=3
Mapping 102~111 ID=1, Start=2, Limit=3, Offset=4, Filename=5, BuildID=6, HasFunctions=7, HasFilenames=8, HasLineNumbers=9, HasInlineFrames=10
Location 114~117 ID=1, MappingID=2, Address=3, Line=4
Line 120~121 FunctionID=1, Line=2
Function 124~128 ID=1, Name=2, SystemName=3, Filename=4, StartLine=5

不用背,只要知道它长这样:tagProfile_SampleType=1、tagSample_Location=1、tagLocation_Line=4、tagFunction_StartLine=5 这些常量,就是 proto schema 里写死的字段号,后面会被左移 3 位塞进每一个字节 key 里(§10、难点 I)。

手写字段号而不是用 .pb.go 生成代码------因为 runtime/pprof 不能依赖 protoc 生态,而且这个 encoder 只需要「写」一个方向。

1.5 难点 A|函数名只存一份,字段里为什么写的是页码

在纠结什么 :pbValueType、pbMapping、emitLocation 里到处是 b.stringIndex(...),为什么不直接把字符串写进字段?

通俗地说 :把它想成一本档案字典 。一个跑了几秒的程序,调用栈里 main.worker 可能出现几万次。要是每次都把这几个字母写进文件,既浪费字节,又让 pprof 工具没法按「同一个函数」聚合。做法是:所有字符串先登记进 strings 这张表,拿到一个页码(整数);后面所有字段只写页码。

stringIndex 就是这个登记员,逻辑只有三行(§2 的 130~141 行):

情况 动作
stringMap[s] 查到了 直接返回那个页码
没查到 id = len(b.strings) → append 进表 → 记进 stringMap → 返回

newProfileBuilder 里 strings: []string{""}、stringMap: map[string]int{"": 0} 不是多余:proto 惯例要求 0 号恒为空串 ,所以字典从第 1 页才开始放真名字。还有个连锁好处:页码是整数,走 varint 编码后通常只占 1~2 字节;而字符串本身几十字节。int64Opt 遇到 0 号(空串)干脆整个字段都不写。

最小例子 :假设字典是 ["", "samples", "count", "main.worker"]。写两列 ValueType 时,"samples" 返回 1、"count" 返回 2;后面再遇到 "main.worker",返回 3。整个文件里 main.worker 这十个字母只出现在最后那张字典表里一次。

一句话记住 :字典登记一次、全场只写页码;string_table 就是这份档案的「名词表」。

对应源码行 :§1.2 三个设计要点里的第 1 条「字符串全走 string_table」;§2 的 id = len(b.strings) 那一行。

1.6 难点 B|手写 protobuf 编码为什么不直接用现成的库

在纠结什么 :Go 生态有现成的 protobuf 库和 protoc 生成的 .pb.go,为什么 proto.go 偏要自己手写编码器、连字段号都抄成常量?

通俗地说:三个理由,一个比一个实际:

理由 通俗解释
依赖方向 runtime/pprof 是标准库最里层之一,不能反过来依赖 protoc 生成链 / 带 reflect 的运行时;§1.4 末尾那句注释直说「不能依赖 protoc 生态」
只需要「写」 生产端只负责把字节写出去,解析是 go tool pprof 的事;一个方向的活儿,没必要背整套生成代码
开销 生成代码带初始化、reflect、描述符,对一个「每 100ms 被叫醒一次」的后台泵来说都是白付的成本

所以这个编码器小得离谱:protobuf 结构只有 data []byte、tmp [16]byte、nest int 三个字段;能力也砍到只剩「写 varint / 写长度定界 / 写字符串 / 写 bool / 嵌套消息」,连「读」都没有(§10)。

最小例子(示意,不能直接编译;真实定义见 §10):

go 复制代码
type protobuf struct {
	data []byte
	tmp  [16]byte
	nest int
}

三个字段就撑起了整份文件的字节产出,没有 descriptor、没有 message 结构体、没有反射。

一句话记住 :不是造轮子,是环境只准带一把螺丝刀------只写、只依赖最底层、只付必要开销。

对应源码行:§1.4 结尾「手写字段号而不是用 .pb.go 生成代码」那句注释;§10 开头「protoc 生成的代码要带 reflect/初始化开销,这里手写一个只写的最小实现」。


2 编码小工具:stringIndex / flush / pb*(131~207 行)

2.1 先建画面:登记员与装箱工

这一节是抄账员手边最常用的一组小工具,可以想成两个人加一套固定动作:

  • 登记员 stringIndex :手上抱着 strings 字典和 stringMap 反查表,谁报一个名字,他查一下,有就回页码,没有就追加一页再回页码。
  • 装箱工 flush :面前是 pb 这个未压缩的字节筐,攒到 4KB 就往 gzip.Writer 里倒一批;但他有个死规矩------只在一件货完整封好之后才倒,绝不在半件货的中间下刀。
  • pb* 四个封装:是四种货(列定义、样本、标签、行、模块)各自的「三明治」打包法:起一个口、填字段、封口。

2.2 源码逐行:stringIndex 与 flush

go 复制代码
// stringIndex adds s to the string table if not already present
// and returns the index of s in the string table.
func (b *profileBuilder) stringIndex(s string) int64 {
	id, ok := b.stringMap[s]        // ← 134:查表
	if !ok {                        // ← 135:新字符串
		id = len(b.strings)     // ← 136:索引 = 当前表长
		b.strings = append(b.strings, s)  // ← 137:入表
		b.stringMap[s] = id     // ← 138:反查表
	}                                // ← 139
	return int64(id)                 // ← 140
}                                    // ← 141
                                     // ← 142
func (b *profileBuilder) flush() {   // ← 143:增量下刷------防止 pb 无限膨胀
	const dataFlush = 4096       // ← 144:阈值 4KB
	if b.pb.nest == 0 && len(b.pb.data) > dataFlush {  // ← 145:nest=0 保证不在消息中间切断!
		b.zw.Write(b.pb.data)    // ← 146:写进 gzip(消息边界对齐的字节流,gzip 可流式)
		b.pb.data = b.pb.data[:0]  // ← 147:复用底层数组
	}                                // ← 148
}                                    // ← 149

flush 里那个 b.pb.nest == 0 看着像多余的保险,其实是整份文件不被写坏的闸门------难点 C 专门拆它。dataFlush = 4096 与 b.pb.data = b.pb.data[:0] 是一对:前者定阈值,后者复用底层数组,避免每次刷盘都重新分配。

2.3 源码逐行:四个 pb* 三明治

四个 pb* 封装(151~207 行)都是「startMessage → 字段 → endMessage」三明治,逐行:

go 复制代码
// pbValueType encodes a ValueType message to b.pb.
func (b *profileBuilder) pbValueType(tag int, typ, unit string) {
	start := b.pb.startMessage()                          // ← 153:记长度前缀占位点
	b.pb.int64(tagValueType_Type, b.stringIndex(typ))     // ← 154:type 字段(字符串索引)
	b.pb.int64(tagValueType_Unit, b.stringIndex(unit))    // ← 155:unit 同上
	b.pb.endMessage(tag, start)                           // ← 156:回填长度前缀,挂到 tag 下
}                                                         // ← 157
                                                          // ← 159
// pbSample encodes a Sample message to b.pb.
func (b *profileBuilder) pbSample(values []int64, locs []uint64, labels func()) {
	start := b.pb.startMessage()                      // ← 161
	b.pb.int64s(tagSample_Value, values)              // ← 162:值列表(packed 编码)
	b.pb.uint64s(tagSample_Location, locs)            // ← 163:location id 列表(叶→根)
	if labels != nil {                                // ← 164:labels 延迟回调(用到时才编)
		labels()                                  // ← 165
	}                                                 // ← 166
	b.pb.endMessage(tagProfile_Sample, start)         // ← 167
	b.flush()                                         // ← 168:每样本刷一次(样本量大)
}                                                     // ← 169
                                                      // ← 171
// pbLabel encodes a Label message to b.pb.
func (b *profileBuilder) pbLabel(tag int, key, str string, num int64) {
	start := b.pb.startMessage()                  // ← 173
	b.pb.int64Opt(tagLabel_Key, b.stringIndex(key))   // ← 174:Opt=零值省略
	b.pb.int64Opt(tagLabel_Str, b.stringIndex(str))  // ← 175:字符串 label
	b.pb.int64Opt(tagLabel_Num, num)                 // ← 176:数值 label(heap 的 "bytes")
	b.pb.endMessage(tag, start)                      // ← 177
}                                                     // ← 178
                                                      // ← 180
// pbLine encodes a Line message to b.pb.
func (b *profileBuilder) pbLine(tag int, funcID uint64, line int64) {  // ← 181
	start := b.pb.startMessage()                    // ← 182
	b.pb.uint64Opt(tagLine_FunctionID, funcID)      // ← 183
	b.pb.int64Opt(tagLine_Line, line)               // ← 184
	b.pb.endMessage(tag, start)                     // ← 185
}                                                   // ← 186
                                                    // ← 188
// pbMapping encodes a Mapping message to b.pb.
func (b *profileBuilder) pbMapping(tag int, id, base, limit, offset uint64, file, buildID string, hasFuncs bool) {
	start := b.pb.startMessage()                        // ← 190
	b.pb.uint64Opt(tagMapping_ID, id)                   // ← 191
	b.pb.uint64Opt(tagMapping_Start, base)              // ← 192
	b.pb.uint64Opt(tagMapping_Limit, limit)             // ← 193
	b.pb.uint64Opt(tagMapping_Offset, offset)           // ← 194
	b.pb.int64Opt(tagMapping_Filename, b.stringIndex(file))    // ← 195
	b.pb.int64Opt(tagMapping_BuildID, b.stringIndex(buildID))  // ← 196
	// TODO: we set HasFunctions if all symbols from samples were symbolized ...(197~202:TODO------
	//     HasInlineFrames/HasLineNumbers 尚未区分设置)
	if hasFuncs {                                       // ← 203
		b.pb.bool(tagMapping_HasFunctions, true)    // ← 204:告诉 pprof"这份 mapping 自带符号"
	}                                                   // ← 205
	b.pb.endMessage(tag, start)                         // ← 206
}                                                       // ← 207

四个封装里藏着三处值得停一下的设计:

  • pbValueType 的 b.stringIndex(typ) 说明列定义的「列名 / 单位」也是字典里的页码,不是裸字符串;
  • pbSample 的 labels func() 是延迟回调 ------标签用到时才编,且它和 b.flush() 一起保证了「一条样本写完就刷一次」;
  • pbMapping 里那段 TODO 老实承认 HasInlineFrames / HasLineNumbers 还没细分设置,只按 hasFuncs 写了 HasFunctions。

startMessage / endMessage 的实体在 §10,这里先记住它们是一对:startMessage() 记下内容起点,endMessage(tag, start) 回填长度前缀并挂到 tag 下。

2.4 难点 C|缓冲刷盘为什么非要等 nest == 0

在纠结什么 :flush 的条件是 b.pb.nest == 0 && len(b.pb.data) > dataFlush,那个 nest 看着像多余的保险。

通俗地说 :dataFlush = 4096,意思很直白------字节缓冲攒到 4KB 就往 gzip 里灌一批,别让它无限膨胀。但灌的时机有讲究 :gzip 是流式的,字节可以分批写,可 protobuf 的一个消息不能被劈成两半。

nest 就是「现在套在第几层消息里」。startMessage() 进去时 nest++,endMessage() 出来时 nest--(§10)。只要 nest != 0,说明某个 Sample / Location / Function 正写到一半,前缀还没回填,这时候把 data 切走,等于把半句话发给了对方。

所以规矩是:只在「消息边界对齐」的地方刷盘 。pbSample 每写完一条样本就 flush() 一次,正是因为它刚 endMessage 出来,nest 回到 0;而 emitLocation 结尾也有一次 flush()(§7)。

违反了会怎样 :b.pb.data = b.pb.data[:0] 会复用底层数组,半截消息被送进 gzip 后,后续 endMessage 的三次 copy 会在一个已经被清空的缓冲上算 n1/n2/n3,字节彻底错乱------pprof 工具解析时直接报坏文件。

最小例子 :把 if b.pb.nest == 0 改成无条件刷,然后在 pbSample 的 endMessage 之前刚好攒够 4KB,就会把「Sample 内容已写、key+len 还没回填」的字节送出去。

一句话记住 :缓冲可以分批刷,消息不能半截刷 ;nest 就是那道「现在能不能切」的闸门。

对应源码行 :§2.2 的 142 行那个条件;§10 的 startMessage 里 b.nest++ 与 endMessage 里 b.nest--。


3 allFrames 与 locInfo:把 PC 翻成函数、并缓存下来(209~272 行)

3.1 先建画面:一台单地址翻译器

栈里是一串 PC 地址,pprof 文件里要的是「函数 + 文件 + 行号」。中间需要一台翻译器,而 allFrames 就是这台机器------但要特别注意:它一次只翻译一个地址,不是把整条栈丢进去。

为什么不整栈翻译?因为缓存的粒度是「地址」而不是「栈」:同一个 PC 会在成千上万条栈里反复出现,按地址缓存,第二次起就不用再问 runtime 了。locInfo 就是这台翻译器的缓存条目:记下这个 PC 定稿成了哪个 Location ID、覆盖了哪几个连续 PC、叶 PC 展开成了哪些 frame。

newProfileBuilder 则是一次性把抄账员的行李备齐:gzip 层、字典第 0 页的空串、三张空表,以及立刻去读一张「模块地图」。

3.2 源码逐行:allFrames

go 复制代码
func allFrames(addr uintptr) ([]runtime.Frame, symbolizeFlag) {
	// Expand this one address using CallersFrames so we can cache
	// each expansion. ...(209~213:单地址展开------按地址缓存,别整栈展开)
	frames := runtime.CallersFrames([]uintptr{addr})  // ← 214:单元素切片!
	frame, more := frames.Next()                      // ← 215
	if frame.Function == "runtime.goexit" {
		// Short-circuit if we see runtime.goexit ...(216~218:goexit 无信息------直接空)
		return nil, 0                                 // ← 219
	}                                                  // ← 220
	                                                   // ← 221
	symbolizeResult := lookupTried                     // ← 222:默认"试过"
	if frame.PC == 0 || frame.Function == "" || frame.File == "" || frame.Line == 0 {
		symbolizeResult |= lookupFailed                // ← 224:任一字段缺失 → 失败位
	}                                                  // ← 225
	                                                   // ← 226
	if frame.PC == 0 {
		// If we failed to resolve the frame, at least make up
		// a reasonable call PC. This mostly happens in tests.
		frame.PC = addr - 1                            // ← 230:造个合理的 call PC(addr-1)
	}                                                  // ← 231
	ret := []runtime.Frame{frame}                      // ← 232
	for frame.Function != "runtime.goexit" && more {   // ← 233:一个 addr 可能展开出多个 frame(内联链)!
		frame, more = frames.Next()                    // ← 234
		ret = append(ret, frame)                       // ← 235
	}                                                  // ← 236
	return ret, symbolizeResult                        // ← 237
}                                                      // ← 238

三处最要紧:

  • runtime.CallersFrames([]uintptr{addr}) 传的是单元素切片,这正是「按地址缓存」的落点;
  • frame.PC = addr - 1 是在符号化失败时造一个合理的 call PC(主要发生在测试里),不至于让整个 Location 缺地址;
  • for frame.Function != "runtime.goexit" && more 这个循环说明一个 addr 可能展开出多个 frame ------这就是内联链,也是 §6 pcDeck 要处理的原料。

symbolizeResult 默认置 lookupTried,只要 PC / 函数 / 文件 / 行号任一缺失就或上 lookupFailed。这个标记会一路传到 emitLocation,最后决定 mapping 能不能声明「自带符号」(§7、§8)。

3.3 源码逐行:locInfo 与 newProfileBuilder

go 复制代码
type locInfo struct {                     // ← 240:PC → Location 缓存条目
	// location id assigned by the profileBuilder
	id uint64                            // ← 242:已分配的 Location ID
	                                       // ← 244~246:pcs 注释------含 traceback 返回的内联伪 PC
	pcs []uintptr                         // ← 247:这个 Location 覆盖的连续 PC 段(栈匹配用)
	                                       // ← 249~251:firstPC* 注释
	firstPCFrames          []runtime.Frame  // ← 252:叶 PC 的展开结果(缓存)
	firstPCSymbolizeResult symbolizeFlag    // ← 253:其符号化结果
}                                          // ← 254
                                           // ← 255~258:构造器文档
func newProfileBuilder(w io.Writer) *profileBuilder {
	zw, _ := gzip.NewWriterLevel(w, gzip.BestSpeed)  // ← 260:★BestSpeed------压缩率换 CPU(剖析数据要快)
	b := &profileBuilder{
		w:         w,                              // ← 262
		zw:        zw,                             // ← 263
		start:     time.Now(),                     // ← 264:起始时间
		strings:   []string{""},                   // ← 265:string_table[0] 恒为空串(proto 惯例)
		stringMap: map[string]int{"": 0},           // ← 266
		locs:      map[uintptr]locInfo{},           // ← 267
		funcs:     map[string]int{},                // ← 268
	}                                              // ← 269
	b.readMapping()                                // ← 270:立刻读 /proc/self/maps(或平台等价)
	return b                                       // ← 271
}                                                  // ← 272

locInfo 里 pcs 那句「覆盖的连续 PC 段」先记牢:§6 的 appendLocsForStack 命中缓存时,会用 stk = stk[len(l.pcs):] 把整段一次性跳过。firstPCFrames / firstPCSymbolizeResult 则是「叶 PC 的展开结果」,缓存命中时直接喂给 deck 复用,省一次符号化。

3.4 本节拆解:两处容易被忽略的设计

为什么 gzip 用 BestSpeed 而不是默认级别? 剖析数据是在程序运行时后台写出的,每 100ms 被叫醒一次,压缩率换 CPU 是划算的:文件大一点无所谓,别拖慢被剖析的程序。这一行是 §1.3 那个「环境限制」表的直接落地。
为什么 strings 初始就要放一个空串? proto 惯例要求 string_table[0] 恒为空串,字典从第 1 页开始放真名字;对应地 stringMap 也预置了 "": 0。这条不变量列在 §12 第 2 条,违反它工具解析会错位。
readMapping() 为什么在构造器里就调? 因为模块表是全局背景信息,与具体样本无关,开工时一次读好即可;三种平台怎么读、读不到怎么兜底,是 §8 与难点 G 的内容。

本节没有独立编号的难点,但它给后面三处埋了线:allFrames 展开出的多个 frame 是难点 E(§6)的原料,locInfo 里那些切片为什么要拷贝是难点 F(§7)的关键,symbolizeResult 怎么汇总到 mapping 是难点 G(§8)的伏笔。


4 addCPUData:把 runtime 记录流切回语义(274~345 行)

4.1 先建画面:拆一个不透明的包裹

上游交来的 data 是 [3+n]uint64 记录流,tags 与之平行------一条记录配一个标签指针。这里就是消费端。

addCPUData 干的活像拆包裹:包裹上没有字段名、没有括号、没有逗号,只有一格一格的约定。第一格说「我这条一共占几格」,第二格是时间戳(明确忽略),第三格是这条记录代表几个样本,后面是一摞 PC。校验完,游标按第一格直接跳到下一条,不需要任何分隔符。整个函数只做两件事:把数字切回语义 ,然后交给去重表累加。

4.2 源码逐行:addCPUData

go 复制代码
// addCPUData adds the CPU profiling data to the profile. ...(275~277:
//     契约------data 必须是整条记录;len(tags)==记录数)
func (b *profileBuilder) addCPUData(data []uint64, tags []unsafe.Pointer) error {
	if !b.havePeriod {
		// first record is period                       // ← 279:首条记录是元数据
		if len(data) < 3 {
			return fmt.Errorf("truncated profile")  // ← 282:连头都凑不齐
		}                                            // ← 283
		if data[0] != 3 || data[2] == 0 {            // ← 284:长度≠3 或 hz=0
			return fmt.Errorf("malformed profile")  // ← 285
		}                                            // ← 286
		// data[2] is sampling rate in Hz. Convert to sampling
		// period in nanoseconds.
		b.period = 1e9 / int64(data[2])              // ← 289:100Hz → 10,000,000ns(采集器写入的 hz 元记录!)
		b.havePeriod = true                          // ← 290
		data = data[3:]                              // ← 291:消费掉头记录
		// Consume tag slot. Note that there isn't a meaningful tag
		// value for this record.
		tags = tags[1:]                              // ← 294:tag 同步消费
	}                                                    // ← 295
	                                                     // ← 296~311:大注释------记录格式与溢出约定:
	//   data[0]=3+n, data[1]=时间戳(忽略), data[2]=count, data[3:]=栈
	//   count==0 且栈长 1 → 溢出记录(栈[0]=丢失样本数)
	//   同栈样本多 → 立即用 b.m(profMap)去重
	for len(data) > 0 {                                 // ← 312:主循环
		if len(data) < 3 || data[0] > uint64(len(data)) {  // ← 313:声称长度超出剩余
			return fmt.Errorf("truncated profile")  // ← 314
		}                                                // ← 315
		if data[0] < 3 || tags != nil && len(tags) < 1 {  // ← 316
			return fmt.Errorf("malformed profile")       // ← 317
		}                                                 // ← 318
		if len(tags) < 1 {                                // ← 319
			return fmt.Errorf("mismatched profile records and tags")  // ← 320
		}                                                 // ← 321
		count := data[2]                                  // ← 322:本记录的样本数
		stk := data[3:data[0]]                            // ← 323:栈切片
		data = data[data[0]:]                             // ← 324:游标前进
		tag := tags[0]                                    // ← 325:对应 tag
		tags = tags[1:]                                   // ← 326
	                                                      // ← 327
		if count == 0 && len(stk) == 1 {                  // ← 328:溢出记录(缓冲写满时合成的丢件补报)
			// overflow record
			count = uint64(stk[0])                    // ← 330:栈[0] 是丢失数
			stk = []uint64{                           // ← 331:伪栈------归罪 lostProfileEvent
				// gentraceback guarantees that PCs in the
				// stack can be unconditionally decremented and
				// still be valid, so we must do the same.
				uint64(abi.FuncPCABIInternal(lostProfileEvent) + 1),  // ← 335:+1 保持 return-PC 语义
			}                                         // ← 336
		}                                                 // ← 337
		b.m.lookup(stk, tag).count += int64(count)        // ← 338:★去重累加(profMap,见 §9)
	}                                                     // ← 339
	                                                      // ← 340
	if len(tags) != 0 {                                   // ← 341:数据与 tag 数不符
		return fmt.Errorf("mismatched profile records and tags")  // ← 342
	}                                                     // ← 343
	return nil                                            // ← 344
}                                                        // ← 345

把这条函数读薄,只剩三个动作:

步 代码 发生了什么
1 !b.havePeriod 分支 首记录是元数据 :校验 data[0]==3 且 data[2]!=0,算 b.period = 1e9 / int64(data[2]),然后 data = data[3:]、tags = tags[1:] 消费掉
2 for len(data) > 0 主循环 切出 count := data[2]、stk := data[3:data[0]],游标 data = data[data[0]:] 前进,同步取 tag
3 b.m.lookup(stk, tag).count += int64(count) 查去重表、命中就累加、没命中就新建------整趟最核心的一句

溢出记录那段也值得单看:当 count==0 && len(stk)==1,说明这是一条「丢了 N 条样本」的补报,于是把 count 改成 stk[0](丢失数),把栈换成 lostProfileEvent 的伪 PC(+1 保持 return-PC 语义),让火焰图里能看见「丢了多少」。

一条具体记录长什么样(大注释给了格式):

位置 值 含义
data[0] 3+n 这条记录一共占几格
data[1] 时间戳 原注释明确写着「忽略」
data[2] count 这条记录代表几个样本
data[3:data[0]] 栈 一串 PC

4.3 难点 D|三层翻译:为什么输入是裸 uint64,不是现成的结构

在纠结什么 :addCPUData 开头一堆 if len(data) < 3、data[0] > uint64(len(data))、len(tags) < 1 的校验,像在拆一个不透明的包裹。为什么上游不直接给结构体?

通俗地说 :因为上游是那本不能上锁、不能分配内存的环形账本 。信号处理器往里写的时候,能写的只有「数字格子」,不可能构造 Go 结构体、更不可能塞字符串。所以跨过 ③→④ 边界的,只能是「一串 uint64 + 平行的标签指针」。本层第一件事就是按约定把数字重新切回语义。

那个约定是双方早就说好的暗号:

暗号 含义
第一格 = 整条长度 自带步长,读的时候直接跳这么多格
data[0] 必须 ≥ 3 长度字 + 时间 + 抬头,最少三格
count==0 且栈长 1 这不是普通样本,是「丢了 N 条」的补报
tags 与记录一一对应 一条记录配一个标签指针

最小例子 :一条 [5, 100, 1, 0xaa, 0xbb] 的读法------第一格说「我占 5 格」,第二格时间 100 忽略,第三格说「1 个样本」,后面 0xaa / 0xbb 是两层栈。校验完,游标直接 data = data[data[0]:] 跳到下一条,不需要任何分隔符。

一句话记住 :上游不是不肯给结构,是给不了;本层第一层工作就是按暗号把数字切回语义。

对应源码行 :§4.2 那段「data[0]=3+n, data[1]=时间戳(忽略), data[2]=count, data[3:]=栈」的注释,以及 count==0 && len(stk)==1 那个分支。


5 build:遍历去重表、封包、收尾 gzip(347~392 行)

5.1 先建画面:交账与装箱

addCPUData 是「来一条账、记一笔」,build 是「记完了,交账」:

  1. 先盖章------写起始时间、两列定义、时长、周期;
  2. 再按插入序 把去重表里的每一条样本取出来,把栈翻译成一串 Location 编号,写成一条 Sample;
  3. 最后把 Mapping 表、整本 string_table、剩余字节一次写完,关掉 gzip 流。

它是整条流水线的分界线:上半段(解析 + 去重)到此为止,下半段(翻译 + 编码)从这里开始。注意 for e := b.m.all; e != nil; e = e.nextAll 走的是 all 全量链而不是哈希桶------因为输出要的是插入序,不是哈希序。

5.2 源码逐行:build

go 复制代码
// build completes and returns the constructed profile.
func (b *profileBuilder) build() {                      // ← 348:profileWriter 的 eof 之后 / 各 write* 的收尾
	b.end = time.Now()                              // ← 349:结束时间
	                                                   // ← 350
	b.pb.int64Opt(tagProfile_TimeNanos, b.start.UnixNano())  // ← 351:采集起始(epoch ns)
	if b.havePeriod { // must be CPU profile          // ← 352:CPU 专属头部
		b.pbValueType(tagProfile_SampleType, "samples", "count")     // ← 353:列① 样本数
		b.pbValueType(tagProfile_SampleType, "cpu", "nanoseconds")   // ← 354:列② CPU 时间
		b.pb.int64Opt(tagProfile_DurationNanos, b.end.Sub(b.start).Nanoseconds())  // ← 355:时长
		b.pbValueType(tagProfile_PeriodType, "cpu", "nanoseconds")   // ← 356:周期单位
		b.pb.int64Opt(tagProfile_Period, b.period)                   // ← 357:周期(样本数×周期≈时长)
	}                                                   // ← 358
	                                                    // ← 359
	values := []int64{0, 0}                            // ← 360:两值样本缓冲
	var locs []uint64                                  // ← 361
	                                                    // ← 362
	for e := b.m.all; e != nil; e = e.nextAll {        // ← 363:遍历去重后的样本(插入序)
		values[0] = e.count                            // ← 364:列① 样本计数
		values[1] = e.count * b.period                 // ← 365:列② 样本×周期 = CPU 纳秒
	                                                    // ← 366
		var labels func()                              // ← 367:tag(pprof labels)→ sample.label
		if e.tag != nil {                              // ← 368
			labels = func() {                          // ← 369
				for _, lbl := range (*labelMap)(e.tag).list {  // ← 370:g.labels 就是 labelMap(采样时抄下的标签指针)
					b.pbLabel(tagSample_Label, lbl.key, lbl.value, 0)  // ← 371
				}                                      // ← 372
			}                                          // ← 373
		}                                              // ← 374
	                                                    // ← 375
		locs = b.appendLocsForStack(locs[:0], e.stk)   // ← 376:★栈 → Location id 列表(见 §6)
	                                                    // ← 377
		b.pbSample(values, locs, labels)               // ← 378:输出样本
	}                                                      // ← 379
	                                                       // ← 380
	for i, m := range b.mem {                              // ← 381:mapping 表
		hasFunctions := m.funcs == lookupTried // lookupTried but not lookupFailed  // ← 382:全部成功才声明有符号
		b.pbMapping(tagProfile_Mapping, uint64(i+1), uint64(m.start), uint64(m.end), m.offset, m.file, m.buildID, hasFunctions)  // ← 383
	}                                                      // ← 384
	                                                       // ← 385~387:两个 TODO(DropFrames/KeepFrames 未实现)
	b.pb.strings(tagProfile_StringTable, b.strings)        // ← 389:字符串表
	b.zw.Write(b.pb.data)                                  // ← 390:刷最后一批字节
	b.zw.Close()                                           // ← 391:结束 gzip 流(写 footer)
}                                                         // ← 392

labels 又是一处延迟回调:只有 e.tag != nil 才构造闭包,闭包遍历 (*labelMap)(e.tag).list 逐条 pbLabel。标签本来就贴在样本上(采样时抄下的 g.labels 指针),这里只是把它翻译成 proto 的 Label 消息。

5.3 本节拆解:两列值、两处时间、三条收尾

两列值不是一回事 :values[0] = e.count 是样本计数,values[1] = e.count * b.period 是样本数乘周期算出来的估计 CPU 纳秒,不是实测值。§13 第 5 条专门澄清这个误解。
两处时间也不是一回事 :tagProfile_TimeNanos 写的是 b.start.UnixNano()(epoch 起始),tagProfile_DurationNanos 写的是 b.end.Sub(b.start)(真实墙钟时长);而记录流里那个 data[1] 时间戳被明确忽略。文件里的时间全部来自 build 自己的时钟。
三条收尾一个都不能少 :b.pb.strings(...) 把整本字典写进 string_table;b.zw.Write(b.pb.data) 刷掉最后一批字节(flush 有 4KB 阈值,尾巴未必够阈值);b.zw.Close() 写 gzip footer------少了它工具读不出文件。这三条列在 §12 第 10 条。

hasFunctions := m.funcs == lookupTried 这句也顺手记一下:只有该 mapping 上所有符号化都「试过且没失败」,才敢向 pprof 声明「自带符号」;symbolizeResult 是怎么一层层汇总上来的,见 §7 与 §8。


6 appendLocsForStack 与 pcDeck:把摊平的内联折回去(394~580 行)

6.1 先建画面:一台折叠机

图 10-3 pcDeck / location 去重:traceback 展开出的多个 NOP 伪 PC,经三条启发式判据合成一个 Location,内含 line\[\] 内联链。

看图时抓三处:同一物理地址带出的三个 NOP 记号、tryAdd 的 Func / Entry / Name 三判据、折成一张卡片后背面写着的 line\[\] 三层函数名;对应 §6.2、§7.2 与难点 E / F。

问题 :runtime 的 traceback 已把内联展开 成独立帧------同一个物理地址 0x4553ee 会带出 a←b←main 三个 frame;而 proto 的规范是「一个 Location,内含 line[] 内联链」。两边对不上,pcDeck 就是把展开的帧折叠回去的状态机。

486~505 行的注释是不可多得的教学材料,原文复述:编译器为每层内联在外层函数里放一个 NOP (0x4553ec / 0x4553ed);traceback 把这些 NOP 地址当「伪 PC」混进栈里。信号恰好停在 MOVQ 上时,栈看起来是「0x4553ee 调用 0x4553ed 调用 0x4553ec」------其实是同一个物理位置的三个记号 。pcDeck 按叶→根顺序 tryAdd,把三者合成「地址 0x4553ee、line[]=[a,b,main] 的单个 Location」。

把它想成一台折叠机:牌堆 deck 一次只装一个 Location 的料,tryAdd 每来一个 PC 就问「能不能跟上一张叠在一起」;能就继续攒,不能就 emitLocation() 把这一堆定稿、再开一堆。

6.2 源码逐行:appendLocsForStack

go 复制代码
// appendLocsForStack appends the location IDs for the given stack trace ...(394~402:
//     输入是 return PC 或内联标记 PC;可能返回空(全是 goexit);会向 b.pb 输出------不能在消息编码中途调)
func (b *profileBuilder) appendLocsForStack(locs []uint64, stk []uintptr) (newLocs []uint64) {
	b.deck.reset()                                    // ← 404:折叠状态机复位
	                                                   // ← 405
	// The last frame might be truncated. Recover lost inline frames.
	origStk := stk                                    // ← 407:留原始栈(panic 信息用)
	stk = runtime_expandFinalInlineFrame(stk)         // ← 408:末帧若是被截断的内联链------补全(runtime 侧 linkname)
	                                                   // ← 409
	for len(stk) > 0 {                                // ← 410:主循环:叶→根逐 PC
		addr := stk[0]                                // ← 411
		if l, ok := b.locs[addr]; ok {                // ← 412:缓存命中!
			// ...(413~423:NOP 伪 PC 注释------命中缓存的 PC 可能是内联中间层,
			//     必须先试 deck 能否继续折叠,再决定是否当作独立 Location)
			if len(b.deck.pcs) > 0 {              // ← 424:deck 有未刷的内容
				if added := b.deck.tryAdd(addr, l.firstPCFrames, l.firstPCSymbolizeResult); added {  // ← 425:先当内联中间层试
					stk = stk[1:]             // ← 426:成功------是同一内联链的一部分
					continue                 // ← 427
				}                             // ← 428
			}                                     // ← 429
			                                    // ← 430
			// first record the location if there is any pending accumulated info.
			if id := b.emitLocation(); id > 0 {  // ← 432:deck 不再能吸收 → 刷掉(独立 Location)
				locs = append(locs, id)      // ← 433
			}                                     // ← 434
			                                    // ← 435
			// then, record the cached location.
			locs = append(locs, l.id)            // ← 437:缓存里的 Location 入列
			                                    // ← 438
			// Skip the matching pcs. ...(439~443:跳过该 Location 覆盖的整段 PC;
			//     expandFinalInlineFrame 已保证栈足够长)
			if len(l.pcs) > len(stk) {           // ← 444:覆盖段比剩余栈还长------数据不一致
				panic(fmt.Sprintf("stack too short to match cached location; stk = %#x, l.pcs = %#x, original stk = %#x", stk, l.pcs, origStk))  // ← 445
			}                                     // ← 446
			stk = stk[len(l.pcs):]                // ← 447:整段跳过
			continue                              // ← 448
		}                                             // ← 449
		                                              // ← 450
		frames, symbolizeResult := allFrames(addr)    // ← 451:缓存未命中------符号化展开
		if len(frames) == 0 { // runtime.goexit.       // ← 452
			if id := b.emitLocation(); id > 0 {   // ← 453:先刷 deck
				locs = append(locs, id)       // ← 454
			}                                     // ← 455
			stk = stk[1:]                         // ← 456:丢弃 goexit
			continue                              // ← 457
		}                                             // ← 458
		                                              // ← 459
		if added := b.deck.tryAdd(addr, frames, symbolizeResult); added {  // ← 460:试着折叠
			stk = stk[1:]                         // ← 461:成功
			continue                              // ← 462
		}                                             // ← 463
		// add failed because this addr is not inlined with the
		// existing PCs in the deck. Flush the deck and retry handling
		// this pc.
		if id := b.emitLocation(); id > 0 {           // ← 467:失败------deck 是完整内联链,先刷
			locs = append(locs, id)               // ← 468
		}                                             // ← 469
		                                              // ← 470
		// check cache again - previous emitLocation added a new entry
		if l, ok := b.locs[addr]; ok {                // ← 472:刚才 emitLocation 刚缓存了它!
			locs = append(locs, l.id)             // ← 473
			stk = stk[len(l.pcs):] // skip the matching pcs.  // ← 474
		} else {                                      // ← 475
			b.deck.tryAdd(addr, frames, symbolizeResult) // must succeed.  // ← 476:空 deck 必成功
			stk = stk[1:]                         // ← 477
		}                                             // ← 478
	}                                                     // ← 479
	if id := b.emitLocation(); id > 0 { // emit remaining location.  // ← 480:收尾刷最后的 deck
		locs = append(locs, id)                       // ← 481
	}                                                     // ← 482
	return locs                                           // ← 483
}                                                         // ← 484

主循环有四条路,看着绕,其实只是「缓存命中 / 未命中」×「deck 能不能吸收」的组合:

情形 动作
缓存命中,deck 还能折叠(412~428 行) tryAdd(addr, l.firstPCFrames, ...) 成功 → 当作同一内联链的中间层,继续
缓存命中,deck 折不动了(432~448 行) 先 emitLocation() 刷掉 deck,再把缓存里的 l.id 入列,stk = stk[len(l.pcs):] 整段跳过
缓存未命中,符号化为空(452~457 行) 是 runtime.goexit,先刷 deck 再丢弃
缓存未命中,tryAdd 失败(467~477 行) deck 是完整内联链,先刷;emitLocation 顺手缓存了当前 addr,于是再查一次缓存,命中就整段跳过,否则用空 deck 重试(必成功)

最容易看漏的一步 :缓存命中时源码不直接采用 l.id,而是先让 deck 试着继续折叠------因为命中的 PC 有可能正是内联链的中间层。折不动了才定稿、再把缓存里的 l.id 入列。

6.3 源码逐行:pcDeck 与 reset

go 复制代码
type pcDeck struct {              // ← 528(507~527 行注释:启发式三判据------见下)
	pcs             []uintptr  // ← 529:deck 里的原始 PC
	frames          []runtime.Frame  // ← 530:它们展开的 frame(可能多个/PC)
	symbolizeResult symbolizeFlag    // ← 531:聚合的符号化结果
	                                                   // ← 532
	firstPCFrames int                  // ← 535:首个(叶)PC 的 frame 数
	firstPCSymbolizeResult symbolizeFlag  // ← 538:其符号化结果(缓存命中时喂给 deck 用)
}                                                       // ← 539
                                                        // ← 540
func (d *pcDeck) reset() {                              // ← 541
	d.pcs = d.pcs[:0]                                // ← 542:长度清零,容量保留
	d.frames = d.frames[:0]                          // ← 543
	d.symbolizeResult = 0                            // ← 544
	d.firstPCFrames = 0                              // ← 545
	d.firstPCSymbolizeResult = 0                     // ← 546
}                                                       // ← 547

reset 里全是 d.xxx = d.xxx[:0]------长度清零、容量保留,下次 append 直接复用底层数组。这正是 §7 里缓存必须拷贝切片的原因:deck 会被复用,谁引用它的切片,谁的内容就会被下一轮覆写。

507~527 行注释给出的内联判定三判据(都不完美,合起来够用):

  1. Frame.Func == nil(内联帧没有独立 Func;非 Go 函数也这样);
  2. Frame.Entry 与入口函数帧相同(递归调用也这样);
  3. Frame.Name 与入口函数名不同(内联函数不能直接递归)。

6.4 源码逐行:tryAdd 与三条判据

go 复制代码
func (d *pcDeck) tryAdd(pc uintptr, frames []runtime.Frame, symbolizeResult symbolizeFlag) (success bool) {
	if existing := len(d.frames); existing > 0 {       // ← 553:deck 非空才判相容性
		// 'd.frames' are all expanded from one 'pc' ...(554~555)
		newFrame := frames[0]                       // ← 556:新 PC 的首个 frame
		last := d.frames[existing-1]                // ← 557:deck 尾 frame(入口函数)
		if last.Func != nil { // the last frame can't be inlined. Flush.  // ← 558:判据①
			return false                       // ← 559
		}                                           // ← 560
		if last.Entry == 0 || newFrame.Entry == 0 { // Possibly not a Go function. Don't try to merge.  // ← 561:判据②前置
			return false                       // ← 562
		}                                           // ← 563
		                                            // ← 564
		if last.Entry != newFrame.Entry { // newFrame is for a different function.  // ← 565:判据②
			return false                       // ← 566
		}                                           // ← 567
		if runtime_FrameSymbolName(&last) == runtime_FrameSymbolName(&newFrame) { // maybe recursion.  // ← 568:判据③
			return false                       // ← 569
		}                                           // ← 570
	}                                                   // ← 571
	d.pcs = append(d.pcs, pc)                           // ← 572:入 deck
	d.frames = append(d.frames, frames...)              // ← 573
	d.symbolizeResult |= symbolizeResult                // ← 574:聚合
	if len(d.pcs) == 1 {                                // ← 575:首个 PC
		d.firstPCFrames = len(d.frames)             // ← 576:记录其 frame 数
		d.firstPCSymbolizeResult = symbolizeResult  // ← 577
	}                                                   // ← 578
	return true                                         // ← 579
}                                                      // ← 580

代码里是「反过来判」的:四个 return false 分别对应三条判据(判据②拆成「Entry 为 0」的前置检查和「Entry 不等」两步):

判据 代码 排除什么
① last.Func != nil → false 非内联帧 / 非 Go 函数
② 前置 `last.Entry == 0 newFrame.Entry == 0` → false 可能不是 Go 函数,别硬合
② last.Entry != newFrame.Entry → false 不同函数
③ 两个 runtime_FrameSymbolName 相等 → false 递归(注释写着 maybe recursion)

全都通过,才 append 进 deck,并聚合 symbolizeResult;首个 PC 额外记下 firstPCFrames / firstPCSymbolizeResult,供缓存命中时复用。

6.5 难点 E|pcDeck:把展开的内联帧折回一个 Location

在纠结什么 :runtime 的 traceback 已经把内联展开 成了独立帧,可 proto 规范要求「一个 Location,里面用 line[] 装内联链」。两边对不上,pcDeck 就是来翻译的。

通俗地说 :想象编译器把 a 内联进 b、b 内联进 main。物理上只有一个地址,但为了在栈里保留层级,编译器会在外层函数里放几个 NOP 空指令 当「伪 PC」。486~505 行的注释复述了这个场景:信号恰好停在 MOVQ 上时,栈看起来像「0x4553ee 调用 0x4553ed 调用 0x4553ec」,其实是同一个物理位置的三个记号。

pcDeck 是个「暂存的牌堆」:按叶 → 根 的顺序对逐个 PC 调 tryAdd,能合并就继续攒,不能合并就 emitLocation() 把当前这堆定稿成一个 Location,再开一堆。

最小例子 :栈里连着三个伪 PC,tryAdd 全返回 true,deck 里攒下它们展开出的 a / b / main 三个 frame;emitLocation 定稿时,地址取叶 PC,而 line[] 按顺序写三层------一个 Location 表达了三层调用 。反过来,若中间夹了一个真正不同的函数,tryAdd 返回 false,deck 先刷出上一个 Location,再为这个新 PC 开一堆。

还有一层缓存要留意:appendLocsForStack 先查 b.locs[addr],命中说明这个 PC 以前定稿过。但源码不直接采用,而是先让 deck 试着继续折叠 (b.deck.tryAdd(addr, l.firstPCFrames, ...))------因为缓存命中的 PC 有可能正是内联链的中间层。折不动了才 emitLocation 刷掉、再把缓存里的 l.id 入列,并 stk = stk[len(l.pcs):] 整段跳过。

三条判据是启发式不是铁律:源码注释明说「都不完美,合起来够用」,单条都有反例(比如递归也会让 Entry 相同)。这一点列在 §13 第 8 条。

一句话记住 :traceback 把内联摊平 ,proto 要叠起来 ;pcDeck 就是那台折叠机,三条启发式是它的手感。

对应源码行 :§6.1 的 NOP 伪 PC 教学注释、§6.3 的三判据、§6.4 tryAdd 里四个 return false。


7 emitLocation:把 deck 定稿成 Location 与 Function(582~657 行)

7.1 先建画面:定稿台

pcDeck 攒够了一个 Location 的料,emitLocation 负责把它写到 proto 里,像一张定稿台:

  1. 取叶 PC 当 Location 地址,分配一个新 ID,顺手把「这个 PC 覆盖哪几个 PC」记进 locs 缓存;
  2. 开一个 Location 子消息,逐 frame 写 line[];
  3. 找一下这个地址属于哪个 mapping,把符号化结果汇总上去;
  4. 收尾 Location,再把本轮新发现的函数补写成独立的 Function 消息;
  5. 刷一次盘,deck 复位。

第 4 步那个「补写」是最反直觉的一处------明明在遍历 frame 时就发现了新函数,为什么不立刻写?难点 F 专门拆它。

7.2 源码逐行:emitLocation

go 复制代码
// emitLocation emits the new location and function information recorded in the deck
// and returns the location ID encoded in the profile protobuf. ...(583~585:
//     会向 b.pb 输出;调用后 deck 复位)
func (b *profileBuilder) emitLocation() uint64 {
	if len(b.deck.pcs) == 0 {              // ← 587:空 deck
		return 0                       // ← 588
	}                                          // ← 589
	defer b.deck.reset()                       // ← 590:无论如何最后复位
	                                                   // ← 591
	addr := b.deck.pcs[0]                            // ← 592:Location 地址 = 叶 PC
	firstFrame := b.deck.frames[0]                   // ← 593
	                                                   // ← 594~597:Location 消息中途不能写 Function------先攒后写
	type newFunc struct {                            // ← 598:待写函数的局部结构
		id         uint64                        // ← 599
		name, file string                        // ← 600
		startLine  int64                         // ← 601
	}                                                   // ← 602
	newFuncs := make([]newFunc, 0, 8)                   // ← 603
	                                                   // ← 604
	id := uint64(len(b.locs)) + 1                      // ← 605:新 Location ID(自增)
	b.locs[addr] = locInfo{                            // ← 606:入缓存
		id:                     id,                // ← 607
		pcs:                    append([]uintptr{}, b.deck.pcs...),  // ← 608:★拷贝!deck 的切片要复用
		firstPCSymbolizeResult: b.deck.firstPCSymbolizeResult,       // ← 609
		firstPCFrames:          append([]runtime.Frame{}, b.deck.frames[:b.deck.firstPCFrames]...),  // ← 610:同上
	}                                                   // ← 611
	                                                   // ← 612
	start := b.pb.startMessage()                       // ← 613:Location 消息开写
	b.pb.uint64Opt(tagLocation_ID, id)                 // ← 614
	b.pb.uint64Opt(tagLocation_Address, uint64(firstFrame.PC))  // ← 615
	for _, frame := range b.deck.frames {              // ← 616:内联链逐层
		// Write out each line in frame expansion.
		funcName := runtime_FrameSymbolName(&frame)// ← 618:符号名(runtime 链接名,如 main.glob..1)
		funcID := uint64(b.funcs[funcName])        // ← 619:函数表查 ID
		if funcID == 0 {                           // ← 620:新函数
			funcID = uint64(len(b.funcs)) + 1  // ← 621:分配 ID
			b.funcs[funcName] = int(funcID)    // ← 622:入表
			newFuncs = append(newFuncs, newFunc{  // ← 623:攒着,Location 写完再写
				id:        funcID,           // ← 624
				name:      funcName,         // ← 625
				file:      frame.File,       // ← 626
				startLine: int64(runtime_FrameStartLine(&frame)),  // ← 627:函数声明行
			})                                // ← 628
		}                                           // ← 629
		b.pbLine(tagLocation_Line, funcID, int64(frame.Line))  // ← 630:line[] 一层
	}                                                   // ← 631
	for i := range b.mem {                              // ← 632:找 addr 属于哪个 mapping
		if b.mem[i].start <= addr && addr < b.mem[i].end || b.mem[i].fake {  // ← 633:区间判定;fake 兜底全收
			b.pb.uint64Opt(tagLocation_MappingID, uint64(i+1))  // ← 634
			                                                   // ← 635
			m := b.mem[i]                                      // ← 636
			m.funcs |= b.deck.symbolizeResult                  // ← 637:聚合符号化结果(有失败则 mapping 不声明有符号)
			b.mem[i] = m                                       // ← 638
			break                                              // ← 639:只属一个 mapping
		}                                                           // ← 640
	}                                                               // ← 641
	b.pb.endMessage(tagProfile_Location, start)                     // ← 642:Location 收尾
	                                                                // ← 643
	// Write out functions we found during frame expansion.
	for _, fn := range newFuncs {                                  // ← 645:补写新函数
		start := b.pb.startMessage()                           // ← 646
		b.pb.uint64Opt(tagFunction_ID, fn.id)                  // ← 647
		b.pb.int64Opt(tagFunction_Name, b.stringIndex(fn.name))          // ← 648
		b.pb.int64Opt(tagFunction_SystemName, b.stringIndex(fn.name))    // ← 649:SystemName 同名(Go 无 C++ 那样的 demangle 区别)
		b.pb.int64Opt(tagFunction_Filename, b.stringIndex(fn.file))      // ← 650
		b.pb.int64Opt(tagFunction_StartLine, fn.startLine)     // ← 651
		b.pb.endMessage(tagProfile_Function, start)             // ← 652
	}                                                               // ← 653
	                                                                // ← 654
	b.flush()                                                       // ← 655
	return id                                                       // ← 656
}                                                                   // ← 657

几个数字与细节对得上前面所有铺垫:

  • id := uint64(len(b.locs)) + 1 ------ Location ID 从 1 自增,与 sample.location_id 引用的正是这套编号;
  • funcID == 0 判定「新函数」,ID 同样从 1 开始,b.funcs 是「函数全名 → ID」表;
  • runtime_FrameSymbolName(&frame) 取的是 runtime 链接名(如 main.glob..1),SystemName 也写同名------Go 没有 C++ 那样的 demangle 区别;
  • b.mem[i].start <= addr && addr < b.mem[i].end || b.mem[i].fake ------ 区间判定;fake 兜底条目全收所有地址(§8、难点 G);
  • m.funcs |= b.deck.symbolizeResult 把这一轮的符号化结果汇总到 mapping,正是 §5 那个 hasFunctions 判据的数据来源。

7.3 难点 F|emitLocation:为什么新函数要攒到最后才写

在纠结什么 :emitLocation 里明明在遍历 deck.frames 时就已经发现了新函数(funcID == 0),为什么不立刻写 Function 消息,非要塞进 newFuncs 等 Location 写完再补?

通俗地说 :因为消息不能套消息 。回忆难点 J(§10):startMessage() 到 endMessage() 之间是一个子消息的「内容区」,长度前缀要等收尾时才回填。Location 消息从 start := b.pb.startMessage() 开始,到 b.pb.endMessage(tagProfile_Location, start) 结束;如果中间插进去一个完整的 Function 消息,它就会被算进 Location 的内容长度里------pprof 工具解析时会把它当成 Location 的字段,整个结构错位。

所以源码分两段:

阶段 干什么
Location 内容区里 逐 frame 写 pbLine(line[] 一层),新函数只记进 newFuncs 小本本
endMessage 之后 再为 newFuncs 里的每一项补写独立的 Function 消息

还有两处「拷贝」特别容易被忽略:b.locs[addr] = locInfo{...} 时,pcs 和 firstPCFrames 都用 append([]T{}, ...) 拷贝了一份 。因为 defer b.deck.reset() 马上会把 deck 的切片长度清零、下次复用底层数组;不拷贝,缓存里存的就是会被覆写的同一块内存。§13 第 7 条就是这条。

最小例子 :newFuncs := make([]newFunc, 0, 8) 预留 8 个位置,遍历 frame 时遇到没见过的 funcName 就分配 funcID = len(b.funcs)+1、记进 b.funcs 和 newFuncs;等 Location 一 endMessage,再循环 newFuncs 逐个 startMessage → 五个字段 → endMessage。newFuncs 就是那张「先别写、等会儿补」的便签。

一句话记住 :子消息的内容区里不能再开子消息,所以新函数先记账、后补写;deck 要复用,缓存就得拷贝。

对应源码行 :§7.2 的 594~597 行「Location 消息中途不能写 Function------先攒后写」注释、608 / 610 行两次 append 拷贝、645~653 行补写循环。


8 mapping 与 parseProcSelfMaps:给每个地址找归属(659~766 行)

8.1 先建画面:给地址查一张地图

Location 光有地址还不够,pprof 工具得知道这个地址落在哪个二进制 / 共享库里,才能去配符号、算偏移。所以抄账员开工时(newProfileBuilder 里那句 b.readMapping(),§3)就读了一张模块地图:进程把哪些文件映射到了哪些地址区间。

Linux 上这张地图就是 /proc/self/maps。但它列出的是进程所有 内存映射------堆、栈、数据段、共享库、匿名映射......而 pprof 只关心「代码可能落在哪 」,也就是可执行段。所以解析器的主旋律是一串 continue:一行行扫过去,只把带 x 权限、有文件名、inode 正常的行留下,算上 buildID,回调上交。

8.2 源码逐行:parseProcSelfMaps

659~660 两个字节常量;662~751 行是 Linux /proc/self/maps 解析器:

go 复制代码
var space = []byte(" ")      // ← 659
var newline = []byte("\n")   // ← 660
                             // ← 661
// parseProcSelfMaps ...(662~682:函数签名 + 真实 maps 样例注释,十八行长样例原样贴在源码里当文档)
func parseProcSelfMaps(data []byte, addMapping func(lo, hi, offset uint64, file, buildID string)) {
	var line []byte                                  // ← 684:当前行游标
	// next removes and returns the next field in the line. ...(685~686)
	next := func() []byte {                          // ← 687:按空格切字段
		var f []byte                             // ← 688
		f, line, _ = bytes.Cut(line, space)      // ← 689
		line = bytes.TrimLeft(line, " ")         // ← 690:吃掉多余空格
		return f                                 // ← 691
	}                                                  // ← 692
	                                                   // ← 693
	for len(data) > 0 {                               // ← 694:逐行
		line, data, _ = bytes.Cut(data, newline)  // ← 695
		addr := next()                             // ← 696:字段① lo-hi
		loStr, hiStr, ok := strings.Cut(string(addr), "-")  // ← 697
		if !ok {
			continue                         // ← 699:格式异常行跳过
		}                                          // ← 700
		lo, err := strconv.ParseUint(loStr, 16, 64)  // ← 701:十六进制地址
		if err != nil {
			continue                          // ← 703
		}                                          // ← 704
		hi, err := strconv.ParseUint(hiStr, 16, 64)  // ← 705
		if err != nil {
			continue                          // ← 707
		}                                          // ← 708
		perm := next()                             // ← 709:字段② 权限
		if len(perm) < 4 || perm[2] != 'x' {       // ← 710:第 3 位是 x?
			// Only interested in executable mappings.  // ← 711:只要可执行段(代码在里面)
			continue                          // ← 712
		}                                          // ← 713
		offset, err := strconv.ParseUint(string(next()), 16, 64)  // ← 714:字段③ 文件偏移
		if err != nil {
			continue                          // ← 716
		}                                          // ← 717
		next()          // dev                     // ← 718:字段④ 设备号------丢弃
		inode := next() // inode                    // ← 719:字段⑤ inode(后面要判 0)
		if line == nil {                            // ← 720:行尾无文件名
			continue                          // ← 721
		}                                          // ← 722
		file := string(line)                        // ← 723:剩余部分=路径(可含空格,故不逐字段切)
	                                                   // ← 724
		// Trim deleted file marker.
		deletedStr := " (deleted)"                   // ← 726:已删除文件后缀
		deletedLen := len(deletedStr)                // ← 727
		if len(file) >= deletedLen && file[len(file)-deletedLen:] == deletedStr {
			file = file[:len(file)-deletedLen]   // ← 729:去掉(符号仍可用)
		}                                              // ← 730
	                                                   // ← 731
		if len(inode) == 1 && inode[0] == '0' && file == "" {  // ← 732:inode 0 且无名
			// Huge-page text mappings ...(733~736:大页文本映射的碎片段;
			//     [vdso]/[vsyscall] 也是 inode 0 但有名------放行)
			continue                          // ← 737
		}                                          // ← 738
	                                                   // ← 739~746:TODO------pprof 的 remapMappingIDs 有个
	//     /anon_hugepage 调整,Go 侧决定先不做,看看会坏什么
		buildID, _ := elfBuildID(file)             // ← 748:ELF build-id(elf.go)
		addMapping(lo, hi, offset, file, buildID)  // ← 749:回调上交
	}                                                  // ← 750
}                                                     // ← 751

next() 只切固定几个字段,末尾直接 string(line) 当路径------因为路径本身可能带空格,所以不能按空格逐字段切 。这一点解释了为什么代码不把整行 Split 成数组。

8.3 源码逐行:addMapping 与 addMappingEntry

go 复制代码
func (b *profileBuilder) addMapping(lo, hi, offset uint64, file, buildID string) {
	b.addMappingEntry(lo, hi, offset, file, buildID, false)  // ← 754:非伪造
}                                                             // ← 755
                                                              // ← 756
func (b *profileBuilder) addMappingEntry(lo, hi, offset uint64, file, buildID string, fake bool) {
	b.mem = append(b.mem, memMap{                          // ← 758:追加进 mapping 表
		start:   uintptr(lo),                          // ← 759
		end:     uintptr(hi),                          // ← 760
		offset:  offset,                               // ← 761
		file:    file,                                 // ← 762
		buildID: buildID,                              // ← 763
		fake:    fake,                                 // ← 764
	})                                                        // ← 765
}                                                             // ← 766(文件完)

addMapping 只是 addMappingEntry(..., false) 的一层薄封装;fake 参数留给平台兜底用。b.mem 里的顺序就是 §5 build 写 Mapping 表时的顺序,tagMapping_ID 取 i+1。

readMapping 的三种平台实现(概述,各自 30~78 行):

文件 平台 做法
proto_other.go(30 行) Linux/BSD os.ReadFile("/proc/self/maps") → parseProcSelfMaps;失败则加 fake mapping
proto_windows.go(78 行) Windows 遍历模块句柄(Module32Next)取每个 DLL 的基址 / 大小 / 路径;peBuildID(pe.go)从 PE 头算 buildID
proto_darwin.go(36 行) macOS _dyld_image_count / _dyld_get_image_... API + machoBuildID;另有 vminfo_darwin.go 提供内存信息

三者填的都是同一张 b.mem,对上层完全透明。

8.4 难点 G|mapping:为什么只留可执行段

在纠结什么 :parseProcSelfMaps 逐行读 /proc/self/maps,中间一串 continue 跳过,最后才 elfBuildID(file) + addMapping(...)。它到底在挑什么?

通俗地说 :/proc/self/maps 列出的是进程所有 内存映射:堆、栈、数据段、共享库、匿名映射......而 pprof 只关心「代码可能落在哪 」,也就是可执行段。所以 perm := next() 之后那句 perm[2] != 'x' 就是筛子:权限字段第 3 位不是 x 的行,一律跳过。

其余几个 continue 也各有理由:

跳过条件 通俗解释
地址切不出 lo-hi / ParseUint 失败 这行不是合法地址范围,别脏了表
line == nil(行尾没文件名) 匿名映射,没有可配对的文件
inode==0 且 file=="" 大页文本映射的碎片段;但 [vdso] / [vsyscall] 也是 inode 0,有名就放行
权限位不是 x 不是代码段,PC 不会落在这里

还有两个细节:文件名后缀 " (deleted)" 要去掉(文件被删了符号仍可用);剩下的整段 line 当路径,因为路径可能带空格,不能逐字段切。

那 fake 是干嘛的 :三种平台实现里,proto_other.go(Linux/BSD)读 /proc/self/maps 失败时会加一个 fake mapping。§7 的 emitLocation 找归属时那句 || b.mem[i].fake 就是让这个假条目「全收」所有地址,保证没有真实模块表时文件仍能生成。

最小例子 :一行 7f...-7f... r-xp 00001000 08:01 12345 /usr/bin/myapp,权限位有 x、有文件名、inode 非 0 → 留下,算出 lo/hi/offset,取 buildID,调 addMapping。隔壁一行 rw-p 的数据段 → 直接跳过。

一句话记住 :PC 只可能落在可执行段 ,所以 maps 里只挑带 x 的行;读不到就造个 fake 全收兜底。

对应源码行 :§8.2 的 709~713 行 perm[2] != 'x'、732~737 行 inode 判定、726~730 行 (deleted) 处理;§8.3 末尾三平台对照表。


9 map.go 的 profMap:按 (栈, tag) 即时去重

9.1 先建画面:整条流水线的减压阀

§4 那句 b.m.lookup(stk, tag).count += int64(count) 是整条流水线最关键的一句------没有它,每秒上百条样本会原样写进文件,文件瞬间爆炸。profMap 就是那只减压阀:同一个「栈 + 标签」只留一条,再来只把计数加上去。

它的实现看着比普通 map 复杂得多:拉链、全量链、空闲池、cap 钉死、move-to-front。但拆开看,每一处都是在回答同一个现实问题------样本流每秒上百条,绝大多数是重复的栈,既不能每条都新建条目,也不能每条都把栈序列化成字符串当 key。

9.2 源码逐行:profMap 结构

go 复制代码
// (map.go) A profMap is a map from (stack, tag) to mapEntry.
// It grows without bound, but that's assumed to be OK.   // ← 10~11:只增不减(剖析时长有限,可接受)
type profMap struct {             // ← 12
	hash    map[uintptr]*profMapEntry  // ← 13:桶号 → 条目拉链(Go 原生 map 只当"数组"用)
	all     *profMapEntry             // ← 14:全量链头(build 按插入序遍历)
	last    *profMapEntry             // ← 15:全量链尾(O(1) 追加)
	free    []profMapEntry            // ← 16:条目空闲池(成批分配)
	freeStk []uintptr                 // ← 17:栈 PC 空闲池(大块切着用)
}                                    // ← 18
                                     // ← 19~20
type profMapEntry struct {           // ← 21
	nextHash *profMapEntry // next in hash list  // ← 22
	nextAll  *profMapEntry // next in list of all entries  // ← 23
	stk      []uintptr     // ← 24:栈(拷贝)
	tag      unsafe.Pointer// ← 25:标签(g.labels 指针,可为 nil)
	count    int64         // ← 26:累计样本数
}                                    // ← 27

hash 是「桶号 → 拉链」,all / last 是另一条按插入序串起来的全量链。为什么两条链都要?因为 §5 的 build 要 for e := b.m.all; e != nil; e = e.nextAll 按插入序 遍历,而哈希桶里是乱序的。free / freeStk 则是成批分配的对象池,避免每条样本都 new。

9.3 源码逐行:lookup

go 复制代码
func (m *profMap) lookup(stk []uint64, tag unsafe.Pointer) *profMapEntry {
	// Compute hash of (stk, tag).
	h := uintptr(0)                                   // ← 30
	for _, x := range stk {                           // ← 31:滚动哈希:每步左旋 8 位再加 41 倍 PC
		h = h<<8 | (h >> (8 * (unsafe.Sizeof(h) - 1)))  // ← 32:rotate-left 8(位宽感知,32/64 位都对)
		h += uintptr(x) * 41                           // ← 33:乘 41------经典字符串哈希乘数
	}                                                     // ← 34
	h = h<<8 | (h >> (8 * (unsafe.Sizeof(h) - 1)))        // ← 35:tag 也滚进去
	h += uintptr(tag) * 41                                // ← 36
	                                                      // ← 37
	// Find entry if present.
	var last *profMapEntry                                // ← 39
Search:                                                  // ← 40:带标签循环(Go 的 goto 标签用于"退一层继续")
	for e := m.hash[h]; e != nil; last, e = e, e.nextHash {  // ← 41:拉链查找
		if len(e.stk) != len(stk) || e.tag != tag {   // ← 42:快筛
			continue                              // ← 43
		}                                             // ← 44
		for j := range stk {                           // ← 45:逐 PC 慢比
			if e.stk[j] != uintptr(stk[j]) {       // ← 46
				continue Search                    // ← 47:不匹配------回到外层拉链下一个
			}                                         // ← 48
		}                                             // ← 49
		// Move to front.
		if last != nil {                              // ← 51:命中且非链头
			last.nextHash = e.nextHash            // ← 52:摘下
			e.nextHash = m.hash[h]                 // ← 53:接到链头
			m.hash[h] = e                          // ← 54:MTF 启发式------热栈查找更快
		}                                             // ← 55
		return e                                       // ← 56
	}                                                     // ← 57
	                                                      // ← 58
	// Add new entry.
	if len(m.free) < 1 {                                  // ← 60:空闲池空了
		m.free = make([]profMapEntry, 128)            // ← 61:一次造 128 个
	}                                                     // ← 62
	e := &m.free[0]                                       // ← 63:取一个
	m.free = m.free[1:]                                   // ← 64:池游标前移
	e.nextHash = m.hash[h]                                // ← 65:接拉链
	e.tag = tag                                           // ← 66
	                                                      // ← 67
	if len(m.freeStk) < len(stk) {                       // ← 68:栈池不够长
		m.freeStk = make([]uintptr, 1024)             // ← 69:大块 1024
	}                                                     // ← 70
	// Limit cap to prevent append from clobbering freeStk.  // ← 71:cap 钉死------防止日后 append 越界写坏池
	e.stk = m.freeStk[:len(stk):len(stk)]                 // ← 72:从池里切一段
	m.freeStk = m.freeStk[len(stk):]                      // ← 73
	                                                      // ← 74
	for j := range stk {                                  // ← 75:拷贝栈
		e.stk[j] = uintptr(stk[j])                    // ← 76
	}                                                     // ← 77
	if m.hash == nil {                                    // ← 78:懒建 map
		m.hash = make(map[uintptr]*profMapEntry)      // ← 79
	}                                                     // ← 80
	m.hash[h] = e                                         // ← 81:挂桶
	if m.all == nil {                                     // ← 82:全量链为空
		m.all = e                                         // ← 83
		m.last = e                                        // ← 84
	} else {                                              // ← 85
		m.last.nextAll = e                                // ← 86:尾插(保插入序)
		m.last = e                                        // ← 87
	}                                                     // ← 88
	return e                                              // ← 89
}                                                        // ← 90(文件完)

四个设计逐个对号:

设计 代码 为什么
滚动哈希 30~36 行 h<<8 + uintptr(x)*41 直接对 []uint64 逐格算桶号,不用先把栈变成字符串
拉链 hash[h] + nextHash 哈希碰撞了就挂成一串,Go 原生 map 只当「桶数组」用
全量链 all / last + nextAll 另存一条插入序链,供 build 遍历
空闲池 free(128)/ freeStk(1024) 成批分配,避免每条样本都 new

Search: 标签是 Go 里少见的写法:continue Search 从内层「逐 PC 慢比」直接退回外层拉链的下一个条目,比层层 break 干净。

为什么不直接用 map[string]*entry(栈序列化成 key)?------样本流里每秒百条都要走查;这里避免了每次的字符串序列化分配,且 MTF 让热栈停在链头。这是「runtime 品味」的典型样本。

9.4 难点 H|profMap:按 (栈, tag) 即时去重,为什么不用 mapstring

在纠结什么 :b.m.lookup(stk, tag).count += ... 这一行是整条流水线的「减压阀」,可 profMap 的实现看着比普通 map 复杂得多:拉链、全量链、空闲池、cap 钉死、move-to-front。

通俗地说 :先看它要解决的现实------每秒上百条样本流过来,绝大多数是重复的栈 。要是每条都新建条目,文件会爆炸;要是每条都把栈序列化成字符串当 key,光分配就够呛。所以源码直接对 []uint64 做滚动哈希,一个字符串都不造。

move-to-front :命中且不在链头时,把条目摘下来插到链头(51~54 行)。热栈(反复出现的那个)永远排第一,下次一眼就命中------少数栈反复出现的负载形态收益最大。

cap 钉死 :e.stk = m.freeStk[:len(stk):len(stk)] 那个三索引切片,把容量也钉成 len(stk)。因为 freeStk 是从大池子里切出来的,万一以后有人对 e.stk 做 append,不钉死就会越过边界写进池子里别人的栈,把整张表污染。

最小例子(示意,真实哈希见 §9.3):

go 复制代码
for _, x := range stk {
	h = h<<8 | (h >> (8 * (unsafe.Sizeof(h) - 1)))
	h += uintptr(x) * 41
}

每读一格,左旋 8 位再加 41 倍,标签指针最后也滚进去------于是「同栈 + 同标签」必然落在同一个桶。

一句话记住 :不把栈变成字符串 ,直接对数字算哈希;热栈提到链头,栈池 cap 钉死防越界。

对应源码行 :§9.3 的 30~36 行滚动哈希、51~54 行 move-to-front、60~73 行空闲池与 cap 限制;§9.3 结尾那句「为什么不直接用 mapstring」。


10 protobuf.go:手写的 wire-format 编码器(1~141 行)

10.1 先建画面:只带一把螺丝刀的字节工

图 10-4 varint 与 wire-format:字段 key = 字段号左移 3 位按位或 wire_type,值用 LEB128 变长整数,packed 列表靠三次 copy 把长度前缀搬到头部。

看图时抓三处:key 里低 3 位表类型、varint 按 7 位一组用最高位标记续接、三次 copy 把 key+len 从尾部挪到头部;对应 §10.2、§10.4 与难点 I / J。

protoc 生成的代码要带 reflect / 初始化开销,这里手写一个只写的最小实现。整个编码器只有三件工具:一根 data []byte 缓冲、一张 tmp [16]byte 草稿纸、一个 nest int 嵌套深度计数。它能做的只有「写」:写 varint、写长度定界、写字符串、写 bool、开 / 关子消息------连「读」都没有。

它面对的核心麻烦只有一个:长度前缀必须在内容前面,可长度只有把内容写完才知道。这一节的「三次 copy 杂技」就是为它准备的。

10.2 源码逐行:varint / length / uint64

go 复制代码
// (protobuf.go) A protobuf is a simple protocol buffer encoder.
type protobuf struct {
	data []byte        // ← 9:输出缓冲
	tmp  [16]byte      // ← 10:endMessage 的前插 scratch(三次 copy 杂技用)
	nest  int          // ← 11:嵌套深度(flush 判"消息边界"用)
}                     // ← 12
                      // ← 13
func (b *protobuf) varint(x uint64) {     // ← 14:LEB128 变长整数------proto 的地基
	for x >= 128 {                     // ← 15:还有高位
		b.data = append(b.data, byte(x)|0x80)  // ← 16:低 7 位 + 继续位
		x >>= 7                         // ← 17
	}                                  // ← 18
	b.data = append(b.data, byte(x))   // ← 19:最后一字节无继续位
}                                      // ← 20
                                       // ← 21
func (b *protobuf) length(tag int, len int) {  // ← 22:长度定界符(tag,wire_type=2)+长度
	b.varint(uint64(tag)<<3 | 2)           // ← 23:字段号<<3 | wire_type
	b.varint(uint64(len))                  // ← 24
}                                          // ← 25
                                           // ← 26
func (b *protobuf) uint64(tag int, x uint64) {  // ← 27:单 varint 字段(wire_type=0)
	// append varint to b.data
	b.varint(uint64(tag)<<3 | 0)             // ← 29:key
	b.varint(x)                              // ← 30:value
}                                            // ← 31

三行「按位或」是同一个动作:uint64(tag)<<3 | 0 是「单个数」字段的 key,uint64(tag)<<3 | 2 是「带长度的一段」的 key,byte(x)|0x80 是 varint 的继续位。低 3 位放类型,高位放字段号------难点 I 专门拆这套布局。

10.3 源码逐行:packed 编码与三次 copy

packed 编码的三次 copy 杂技(33~51 行)------proto 规范:repeated 数值 >2 个元素时用「一个 key + 连续 varint + 总长度前缀」。问题是长度前缀在写完数据后才知道,而前缀必须在前面:

go 复制代码
func (b *protobuf) uint64s(tag int, x []uint64) {
	if len(x) > 2 {                          // ← 34:>2 个才值得 packed(阈值来自 proto 惯例)
		// Use packed encoding
		n1 := len(b.data)                // ← 36:数据区起点
		for _, u := range x {            // ← 37:先把裸 varint 全写进去(此时还没 key!)
			b.varint(u)              // ← 38
		}                                // ← 39
		n2 := len(b.data)                // ← 40:数据区终点
		b.length(tag, n2-n1)             // ← 41:★把 key+长度**追加**在数据后面!
		n3 := len(b.data)                // ← 42:现在的终点
		copy(b.tmp[:], b.data[n2:n3])    // ← 43:① 把 key+len 暂存 tmp
		copy(b.data[n1+(n3-n2):], b.data[n1:n2])  // ← 44:② 数据整体后移,前面腾出 key+len 的空位
		copy(b.data[n1:], b.tmp[:n3-n2])  // ← 45:③ key+len 就位
		return                           // ← 46
	}                                        // ← 47
	for _, u := range x {                    // ← 48:≤2 个:普通逐字段编码
		b.uint64(tag, u)                 // ← 49
	}                                        // ← 50
}                                            // ← 51

len(x) > 2 才走 packed------元素太少时,省下的 key 字节还不够抵长度前缀的开销,直接逐字段写更划算。

10.4 源码逐行:Opt 变体、字符串与子消息收尾

go 复制代码
func (b *protobuf) uint64Opt(tag int, x uint64) {   // ← 53:Opt 变体------零值不编码(proto 惯例,省字节)
	if x == 0 {
		return                                   // ← 55
	}                                               // ← 56
	b.uint64(tag, x)                               // ← 57
}                                                   // ← 58
                                                    // ← 59~70:int64/int64Opt(60~63:负数走补码 uint64,64/69 同构略)
func (b *protobuf) int64s(tag int, x []int64) {     // ← 72:int64 版 packed(73~89 与 uint64s 逐行同构)
	...                                              // ← 74~85(三次 copy 同上)
}                                                   // ← 90
                                                    // ← 91
func (b *protobuf) string(tag int, x string) {      // ← 92:字符串字段(wire_type=2)
	b.length(tag, len(x))                       // ← 93:key+len
	b.data = append(b.data, x...)               // ← 94:原始字节
}                                                   // ← 95
                                                    // ← 96
func (b *protobuf) strings(tag int, x []string) {   // ← 97:repeated string(无 packed------string 不是定长)
	for _, s := range x {                       // ← 98
		b.string(tag, s)                    // ← 99
	}                                           // ← 100
}                                                   // ← 101
                                                    // ← 102~108:stringOpt(空串跳过)/
                                                    // ← 110~116:bool(1/0)/
                                                    // ← 118~123:boolOpt(false 跳过)

Opt 系列(零值不编码)是 proto 惯例:值为 0 / 空串 / false 时整个字段都不写,省字节。strings 没有 packed------字符串不是定长数值,没法打包成连续 varint。

go 复制代码
type msgOffset int                       // ← 125:startMessage 的返回(占位位置)

func (b *protobuf) startMessage() msgOffset {  // ← 127:进入子消息
	b.nest++                                // ← 128:深度 +1(flush 据此拒绝切断)
	return msgOffset(len(b.data))          // ← 129:记下消息内容起点
}                                           // ← 130
                                            // ← 131
func (b *protobuf) endMessage(tag int, start msgOffset) {  // ← 132:子消息收尾------同款三次 copy!
	n1 := int(start)                    // ← 133:内容起点
	n2 := len(b.data)                   // ← 134:内容终点
	b.length(tag, n2-n1)                // ← 135:key+len 先追加到尾部
	n3 := len(b.data)                   // ← 136
	copy(b.tmp[:], b.data[n2:n3])       // ← 137:① 暂存
	copy(b.data[n1+(n3-n2):], b.data[n1:n2])  // ← 138:② 内容后移
	copy(b.data[n1:], b.tmp[:n3-n2])    // ← 139:③ 就位
	b.nest--                            // ← 140:深度 -1
}                                       // ← 141(文件完)

startMessage / endMessage 正是 §2 那些 pb* 三明治的两端:nest++ / nest-- 就是难点 C 里那道「现在能不能刷盘」的闸门,而 endMessage 用的是与 uint64s 完全同款 的三次 copy,只是 n1 换成 startMessage() 记下的内容起点。

为什么不用「预留长度位 + 回填」? varint 长度本身不定长(1~10 字节),预留多了浪费、预留少了放不下;尾部追加 + 整体搬移一次到位,代码只有三行。tmp [16]byte 恰好 ≥ 最大 key(2B)+ 最大 len(10B)。

10.5 难点 I|varint / field number 怎么读

在纠结什么 :b.varint(uint64(tag)<<3 | 2) 这一行,凭什么就能让 pprof 工具认出「这是个字段」?

通俗地说:protobuf 的字节里没有字段名、没有括号、没有逗号,全是数字。规矩只有两条:

  1. 每个字段先写一个 key :key = 字段号 << 3 按位或 wire_type。低 3 位说「值怎么摆」,高位说「这是第几号字段」。
  2. wire_type 只有两种在这里用得上 :0 表示「后面跟着一个 varint 数」;2 表示「后面跟着长度 + 一段字节」。

于是 tag<<3 按位或 0 就是「单个数」字段,tag<<3 按位或 2 就是「长度定界」字段。§1.4 那张常量表里的 tagProfile_Sample=2、tagSample_Value=2,说的就是字段号,会被左移 3 位塞进 key。

varint 怎么读:把一个整数按 7 位一组拆开,每组前面加一位「还有没有下一组」的标记。

规则 通俗解释
x >= 128 时 取低 7 位,加上 0x80 的继续位,写出去;x >>= 7 继续
x < 128 时 写最后一个字节,不带继续位
解码 读到最高位是 0 的字节就停,把各段 7 位拼回去

所以小数字(0~127)只占 1 字节,这正是难点 A 里「页码比字符串便宜」的底层原因。

最小例子 :字段号 9(tagProfile_TimeNanos)、wire_type 0 的 key 是 9<<3 = 72;值 300 的 varint 是两字节(因为 300 超过 127)。整条字段就是「72,300 的两字节」共 3 字节,没有字段名、没有等号。图 10-4 画的「key + len + 数据」就是这套布局。

一句话记住:字节里没有名字,只有「编号 + 类型」的 key;varint 让小数字只占一格。

对应源码行 :§10.2 varint 的 for x >= 128 循环、length 与 uint64 各一行;§1.4 字段号常量表。

10.6 难点 J|三次 copy 杂技:长度前缀为什么先追加到尾部

在纠结什么:嵌套消息和 packed 列表都要「key + 长度 + 内容」,可长度只有把内容写完才知道。为什么源码不「先留几个空字节,写完回填」,非要尾部追加再搬三次?

通俗地说 :因为长度本身是 varint,不定长。§10.4 结尾那句给了答案:长度可能是 1~10 字节,预留多了浪费、预留少了放不下。

于是源码反过来做:先把内容裸写进去,再把「key + 长度」追加到尾部 (这时长度终于知道了),然后三次 copy 把这段前缀挪到内容前面:

步 代码做什么 通俗解释
① copy(b.tmp[:], b.data[n2:n3]) 把刚追加的 key+len 暂存到 16 字节草稿纸
② copy(b.data[n1+(n3-n2):], b.data[n1:n2]) 把内容整体往后挪,前面空出前缀的位置
③ copy(b.data[n1:], b.tmp[:n3-n2]) 把前缀从草稿纸贴到空出来的位置

tmp [16]byte 为什么是 16?源码给了算式:足够放下「最大 key(2 字节)+ 最大 varint 长度(10 字节)」。

最小例子 :uint64s 里 len(x) > 2 才走 packed------先把三个裸 varint 写进 data(n1 到 n2),再 b.length(tag, n2-n1) 追加 key + 长度(n2 到 n3),三次 copy 之后,data[n1:] 变成「key | 长度 | 值1 | 值2 | 值3」。若只有 2 个或更少元素,源码直接逐字段写,不折腾。

endMessage 用的是完全同款 三次 copy,只是 n1 换成 startMessage() 记下的消息内容起点------所以 pbValueType、pbSample、pbLine 那些「三明治」全靠它收尾。

一句话记住 :长度事后才知道、又不定长,那就先写后面、再整体搬家,三行 copy 一次到位。

对应源码行 :§10.3 的 33~51 行 uint64s 三行 copy、§10.4 的 132~140 行 endMessage;§10.4 结尾「为什么不用预留长度位 + 回填」那段。


11 串起来:一条 CPU 记录走完全程

前十节是按源码文件顺序拆的零件。这一节只做一件事:跟着一条最普通的记录 从进 addCPUData 到出 cpu.pprof,把 §0.3 那张地图真正跑一遍。

开场 :newProfileBuilder 已经建好(strings 里只有空串、zw 是 gzip.BestSpeed、readMapping 已填好 mem)。

步 真实函数 / 字段 发生了什么 源码
1 addCPUData 首记录 havePeriod 为假 → 检查 data[0]==3 且 data[2]!=0,算出 b.period = 1e9 / int64(data[2]);data = data[3:]、tags = tags[1:] 把头记录消费掉 §4
2 主循环 for len(data) > 0 count := data[2]、stk := data[3:data[0]]、data = data[data[0]:]、tag := tags[0]、tags = tags[1:] §4
3 溢出判定 若 count==0 && len(stk)==1,把 count 改成 stk[0](丢失数),栈换成 lostProfileEvent 的伪 PC §4
4 b.m.lookup(stk, tag).count += int64(count) 同一个栈 + 同一个标签,只把计数加上去,不新增条目 §4、§9
5 build:b.end = time.Now() 写 time_nanos,CPU 专属再写两列 ValueType、时长、周期类型、周期 §5
6 for e := b.m.all; e != nil; e = e.nextAll 按插入序遍历去重表 §5
7 values[0]=e.count、values[1]=e.count*b.period 列①样本数、列②样本数乘周期 = CPU 纳秒 §5
8 locs = b.appendLocsForStack(locs[:0], e.stk) 栈 → 一串 Location 编号(内部调 allFrames、pcDeck.tryAdd、emitLocation) §3、§6、§7
9 b.pbSample(values, locs, labels) 写一条 Sample,且每样本 flush 一次 §2
10 emitLocation → stringIndex 遇到新函数名 / 文件名,先登记进 strings,字段里写页码 §2、§7
11 收尾 写 Mapping 表、写 tagProfile_StringTable、zw.Write(b.pb.data)、zw.Close() §5

一条具体记录长什么样(§4.2 的大注释给了格式):

位置 值 含义
data[0] 3+n 这条记录一共占几格
data[1] 时间戳 原注释明确写着「忽略」
data[2] count 这条记录代表几个样本
data[3:data[0]] 栈 一串 PC

整趟最核心的一句话 :输入是「一串数字」,输出是「一份档案」;中间那步 b.m.lookup(...).count += ... 就是把成千上万条流水账压成几百行样本的唯一动作。没有它,文件会爆炸。

把三行 minimal 版摆在一起看,全部魔法都在第三行:

go 复制代码
count := data[2]
stk := data[3:data[0]]
b.m.lookup(stk, tags[0]).count += int64(count)

第一行取样本数、第二行切出栈、第三行查表、命中就累加、没命中就新建。后面所有 Location / Function / Mapping / string_table / gzip,都只是把这张去重表里的内容翻译并装箱。


12 一页纸速查:不变量

这里把散在各节的「必须成立」翻成「通俗解释 / 谁保证 / 坏了会怎样」。读不下去时回来问一句「这句在守哪条?」,通常就通了。

# 通俗解释 谁保证 坏了会怎样
1 所有字符串先登记字典,字段只写页码 stringIndex + strings / stringMap 文件膨胀、同一函数无法聚合
2 0 号页码恒为空串 newProfileBuilder 的 strings: []string{""} 违反 proto 惯例,工具解析错位
3 同栈 + 同 tag 只累加计数,不新增条目 profMap.lookup 去重失效,文件爆炸
4 缓冲只在消息边界刷盘 flush 的 nest == 0 半截消息进 gzip,文件损坏
5 长度前缀事后才知道,用三次 copy 搬到头部 endMessage / uint64s 预留位数不对,字节错位
6 子消息内容区里不能再开子消息 emitLocation 的 newFuncs 延后补写 Function 被当成 Location 字段
7 deck 会复用底层数组,缓存必须拷贝 emitLocation 里两次 append([]T{}, ...) 缓存里的 PC 被下次写入覆写
8 一个 Location 表达一整条内联链 pcDeck 三判据 + line[] 内联层级丢失,火焰图对不上
9 每条样本都要收尾再刷 pbSample 末尾 b.flush() 大剖析把 pb.data 攒爆内存
10 文件 = gzip(protobuf),收尾要 Close build 的 zw.Write + zw.Close() gzip 缺 footer,工具读不出

这十条是整篇源码的验收标准。每一个看着绕的位运算 / 拷贝 / 状态机,最后都能归到其中一条上。


13 最容易读错的 9 件事

这些是读这份源码时最高频的误解,逐条回看对应节即可澄清。

1|「addCPUData 第一条记录是样本」 不是。首记录是元数据 :data[0] 必须等于 3、data[2] 是采样率 hz,源码算 b.period = 1e9 / int64(data[2])(100Hz → 10,000,000 纳秒),然后 data = data[3:]、tags = tags[1:] 把它消费掉。这段只在 !b.havePeriod 时执行一次(§4、难点 D)。

2|「addCPUData 的时间戳会写进文件」 不会。§4.2 注释明写「data[1] = 时间戳(忽略)」。文件里的时间来自 build 的 b.start / b.end,不是记录流里的那个数字(§5)。

3|「溢出记录是某种特殊通道 / 特殊字段」 不是。它就是一条普通记录,靠 count==0 && len(stk)==1 这个内容指纹 认出来,然后把栈换成 lostProfileEvent 的伪 PC(+1 保持 return-PC 语义)。「丢了多少」最终会出现在火焰图里(§4)。

4|「flush 只是省内存,随便什么时候刷都行」 差得远。nest == 0 是硬约束,保证「消息边界对齐」。在 startMessage / endMessage 之间刷,会把没回填前缀的半截消息送进 gzip(§2、难点 C)。

5|「values[1] 是实测出来的 CPU 时间」 不是实测。build 里直接 values[1] = e.count * b.period,是样本数乘周期 算出来的估计 CPU 纳秒;duration_nanos 才是 b.end.Sub(b.start) 的真实墙钟时长。两者口径不同,请留意区分(§5)。

6|「这个 encoder 既写又读,能直接把 pprof 文件解析回来」 不能。生产端只实现「写」:varint / length / 字符串 / bool / 嵌套消息,连「读」都没有;解析是 pprof 工具那一侧的事。这也是它敢只留三个字段的原因(§1、§10、难点 B)。

7|「b.locs 缓存里存的切片可以直接引用 deck 的」 不行。emitLocation 里 pcs 和 firstPCFrames 都 append([]T{}, ...) 拷贝过,因为 defer b.deck.reset() 之后 deck 的底层数组会被复用;直接引用等于埋一颗定时炸弹(§7、难点 F)。

8|「pcDeck 三判据是精确规则」 不是。§6.3 明说「都不完美,合起来够用」,是启发式 :Func==nil、Entry 相同、Name 不同三条分别排除非内联、不同函数、递归,单条都有反例(§6、难点 E)。

9|「parseProcSelfMaps 把 maps 每一行都收进表」 只收可执行段。perm[2] != 'x' 跳过、inode==0 且无名跳过、(deleted) 后缀去掉;[vdso] 这类 inode 0 但有名的反而放行(§8、难点 G)。


14 五分钟复述卡

能把下面 8 句连着讲给别人听(哪怕讲得磕巴),这套机制就算立住了。

  1. 流水线上 ④ 抄账员拿到的是一串裸 uint64,不是结构体------因为 ③ 账本在信号处理器里,只写得进数字。
  2. addCPUData 先按暗号切记录:第一格长度、第二格时间(忽略)、第三格样本数、后面是栈;首记录是周期元数据,100Hz 换成 10,000,000 纳秒。
  3. 所有名字先登记 string_table,字段里只写页码;stringIndex 就是那个查不到就追加的登记员。
  4. 同栈 + 同标签靠 profMap.lookup(...).count += ... 即时累加,不新增条目,这是文件不爆炸的关键。
  5. build 遍历去重表,把每个栈交给 appendLocsForStack;pcDeck 用三条启发式把内联摊开的伪 PC 折回一个 Location ,line[] 里装内联链。
  6. 编码器是手写的 141 行:不能依赖 protoc,只「写」不「读」;字段 key 是「编号左移 3 位按位或类型」,值用 varint。
  7. 长度前缀事后才知道又不定长,所以尾部追加 + 三次 copy 搬到头部;flush 等 nest == 0 才敢刷,消息不能半截进 gzip。
  8. 最后写 Mapping 表与 string_table,zw.Write 收尾、zw.Close() 补 gzip footer------一份 cpu.pprof 就交出去了。

讲不出第 2 句 → 回难点 D;第 4 句 → §9、难点 H;第 5 句 → §6、难点 E;第 6 / 7 句 → §10、难点 B / I / J。


写到这儿,再把开头那个问题答一遍:那份 cpu.pprof 不是「一次性打印」出来的,而是抄账员 profileBuilder 把一串裸 uint64 按暗号切开,用 profMap 把重复的栈压成一行行计数,再用 allFrames / pcDeck / emitLocation 把每个 PC 翻成带 line[] 的 Location,最后用一百多行手写的 varint 编码器把五张表灌进 gzip、关掉流补上 footer 才交出去的。函数名之所以在火焰图里只出现一次,是因为它早就登记进字典,表里只留了页码;长度前缀之所以看着别扭地先写到尾部,是因为它不定长,只能在内容写完那一刻才知道自己该占几格。

输入是一串数字,输出是一份档案,中间全靠去重、折叠和三次 copy------把这三件事记住,那些看似绕的结构,就都能解释成「好像也只能这么写」。

相关推荐
旋律41426 分钟前
布隆过滤器(Bloom Filter)
后端
站大爷IP34 分钟前
Python的构造方法把我坑惨了,原来__new__和__init__的区别这么大
后端
代码丰40 分钟前
从重复点击到多实例并发:异步报表导出的五层幂等与防重设计
后端
斯维赤42 分钟前
三级缓存为什么是三级?二级缓存不够吗
前端·后端·面试
Rain的Java大神之路1 小时前
把数组本身变成哈希表:原地哈希搞定 LeetCode 41「缺失的第一个正数」
java·后端·leetcode
卷无止境1 小时前
FDE全解析:把软件真正落地到客户现场的那类工程师
后端
锋行天下1 小时前
LangGraph 对接 MCP 实战指南:从本地开发到线上部署与模型防坑
前端·人工智能·后端
利威尔xu1 小时前
2026-11-18-Go接口幂等设计实战
开发语言·后端·golang
喵个咪2 小时前
RushWind Admin — update_mask 写面:字段级白名单、显式清除与点路径合并
后端·rust