Go trace -d=parsed 的事件解析输出方案

如果手里已经有 Go 执行追踪文件，只想把它解析成可以检索的事件文本，直接使用 go tool trace -d=parsed trace.out。这个模式读取 trace 文件，调用解析器逐个读取事件，打印事件的字符串表示，然后结束进程；它不会启动 trace viewer，也不负责生成 pprof 文件。

官方地址：https://go.dev/src/cmd/trace/main.go

把 -d=parsed 当作“解析结果导出”入口即可：输入是 trace 文件，输出是标准输出中的解析事件，原始文件仍应保留给网页查看或其他诊断模式使用。

• 需要逐条查看事件内容：使用 -d=parsed。
• 需要研究编码层原始事件：使用 -d=wire。
• 需要统计事件类型占用的字节和数量：使用 -d=footprint。

这个参数解决什么问题

网页查看器适合观察调度、阻塞和 GC 等时间关系，但排查“文件能否被解析”“某类事件是否出现在输入中”时，文本输出更容易保存、搜索和交给脚本做二次整理。Go 官方 cmd/trace 源码把 parsed、wire、footprint 定义为调试模式；传入这些模式后会打印调试信息并退出，不会继续走 HTTP 监听和网页渲染分支。

按输入和输出理解解析链路

先准备一个追踪文件。它可以来自 go test -trace，也可以由程序使用 runtime/trace 产生。输入文件必须是当前工具能够识别的执行追踪格式；文件不存在、权限不足或格式不完整，都会在读取或解析阶段返回错误。

# 为测试包写出执行追踪文件，路径可替换为实际包路径
go test -trace=trace.out ./path/to/pkg

# 读取解析后的事件，并把标准输出保存成文本
go tool trace -d=parsed trace.out > parsed-events.txt

这个命令的关键点是输出方向：事件文本在标准输出，错误信息通常走标准错误，所以重定向只保存解析结果，不会把错误提示混进文件。解析结束后命令返回，parsed-events.txt 不是新的 trace 文件，不能再拿它作为 go tool trace 的输入。

三种调试模式要分开使用

parsed 使用处理后的事件读取器，逐个调用事件读取方法并输出事件字符串；wire 走原始读取器，关注编码层事件；footprint 则读取原始事件并按事件类型汇总字节数和数量。三者的输出目标不同，不能只靠换一个后缀来互相替代。

# 查看解析器理解后的事件，适合检索事件内容
go tool trace -d=parsed trace.out

# 查看原始编码层事件，适合排查输入格式问题
go tool trace -d=wire trace.out

# 查看事件类型的字节占用和数量统计
go tool trace -d=footprint trace.out

如果目标是调度延迟、网络阻塞或同步阻塞的概览，应使用 -pprof=net、-pprof=sync、-pprof=syscall 或 -pprof=sched 生成 pprof 风格数据；如果要看时间线和任务关系，则回到默认网页查看模式。-d=parsed 只解决“把事件解析出来并打印”的问题。

结果判断与失败边界

看到大量事件文本并正常返回，说明工具至少完成了文件打开、格式识别和事件读取；这不等于已经定位性能根因。若提示无法打开文件，先检查路径和权限；若提示解析失败，保留原始文件并尝试 -d=wire 观察更低层的输入情况。文件很大时，直接把全部文本打印到终端会降低检索效率，可保存到文件后按事件名称或时间字段筛选。

不要用 -http 来“配合” -d=parsed：调试分支在监听地址处理前就结束了。也不要把输出文本交给 go tool pprof，pprof 入口需要由 -pprof 生成的 profile 数据。

常见问题

解析事件输出能替代网页 trace viewer 吗？

不能完全替代。文本适合搜索和留档，网页查看器适合观察时间轴、调度关系和交互式视图；两者应复用同一个原始 trace 文件。

为什么输出为空或很快结束？

先确认输入文件确实包含执行追踪数据，再区分标准输出与标准错误。若文件本身不可读，命令会在读取器初始化或读取事件时返回错误，而不是生成可用的解析事件文本。

实际排查时可以按“保留原始文件、先用 parsed 看事件、再按需要切换 wire 或 footprint、最后决定是否使用网页或 pprof”的顺序处理。这样既不会误把调试输出当成可视化结果，也能把一次解析过程留下可复用的文本记录。