构建分析
profile 记录构建中每条命令何时启动、运行了多久、由哪条命令启动,并把它们写成一份 Perfetto 和 chrome://tracing 都能打开的 trace:构建的时间线,从中可以看到同时运行了多少条命令、决定构建时长的那串步骤,以及耗时最长的步骤。
命令:profile
用法
bash
catter profile [options] -- <build-command>选项
| 选项 | 说明 |
|---|---|
-o, --output <path> | 把 trace 写到该路径,相对路径从 -C 指定的目录算起。默认:trace.json。 |
--top <n> | 列出耗时最长的 n 条命令。默认:5;0 表示不列出。 |
-q, --quiet | 不打印摘要,也不打印 catter 未能捕获某条命令的原因。 |
profile 也接受所有运行构建的命令共有的选项:-C、--capture、--from 和 handler 的选项(见配置参考)。
构建结束后,无论成功还是失败,catter 都会写出 trace,所在目录不存在时先创建它,随后像构建那样退出。trace 无法写入时,catter 说明原因并以 1 退出;被 handler 中止的构建不生成 trace。除非指定了 -q,catter 一得知某条命令未能捕获,就打印原因。
Trace 文件
trace 是一个 JSON 文件,采用 Chrome 的 trace event 格式。在 ui.perfetto.dev(Open trace file)或 chrome://tracing(Load)中打开它。其中的时间以微秒计,从第一条命令启动时算起。
- 泳道。 每条命令是某条泳道(lane)上的一个切片(slice)。一条命令如果在启动它的命令运行期间开始并结束,而且那条命令启动的命令从没有两条同时运行,它就画在那条命令之内、同一条泳道上:例如 shell 和它运行的编译器,编译器驱动程序和它的各个阶段(
cc1plus、as、collect2、ld)。构建工具同时运行的命令,各自放在它们启动时没有任何命令在运行的第一条泳道上:在make -j8下,lane 1 是make,它下面的泳道是它的任务,同时运行了几个任务就有几条。 - critical path。 泳道上方的一条轨道(track),放着关键路径上的命令(见下文)。
- running。 一个计数器(counter),显示每一时刻有多少条命令在工作。命令在运行、且它启动的命令都没有在运行时,才算在工作;catter 分析的编译器或归档工具命令则在整个运行期间都算在工作,它启动的程序也算在它里面。
每个切片以它的程序命名,catter 分析的命令还带上它所涉及的文件:编译命令编译的源文件(c++ main.cc),链接或归档命令生成的文件(c++ app、ar libfoo.a)。catter 分析的命令,切片的类别(category)是命令所做的事:compile、link、preprocess、archive 等。切片的参数(args)包括:
| 参数 | 内容 |
|---|---|
command | 命令的参数,写在一行里:只含 ASCII 字母、数字和 _@%+=:,./\- 的参数原样写出,其他参数写成 JSON 字符串。 |
cwd | 命令运行所在的目录。 |
exit | 命令的退出码;被信号结束的命令为 128 加信号编号。 |
id | 命令在会话中的 ID,parent 引用的就是它。 |
parent | 启动它的那条命令的 ID;构建命令没有此项。 |
writes | catter 分析的命令写出的文件。 |
target | 对编译命令,是读取它的目标文件的命令所写出的文件:该目标文件最终进入的库或程序。 |
摘要
除非指定了 -q,catter 写完 trace 后会打印 trace 显示的内容:
Profiled 1234 commands in 83.4 s: 6.2 ran at once on average, 16 at most.
Critical path, 48.9 s: c++ big.cc 41.0 s > ar libcore.a 400 ms > c++ app 7.5 s
Slowest:
41.0 s c++ big.cc
7.5 s c++ app
3.1 s python3
2.9 s c++ parser.cc
2.0 s cmake
Trace saved to /src/project/trace.json: open it in https://ui.perfetto.dev or chrome://tracing.- 第一行给出构建用了多久,从第一条命令启动到最后一条命令结束;平均同时有多少条命令在工作,即各条命令工作时间之和除以构建用时;以及最多同时有多少条命令在工作。
- 关键路径是由编译、归档和链接组成的一条链,链上每一步都读取前一步写出的文件,且各步耗时之和最长。它追踪的文件是编译器或归档工具的参数中指定的文件:catter 不分析的程序(例如代码生成器)以及编译包含的头文件都不在其中,因此这条链可能比真正决定构建时长的那条短。超过六步的路径只显示前三步和最后两步。
- 最慢的命令是工作时间最长的那些命令。构建工具、shell 或脚本只计入它自己工作的时间:例如
make读取 makefile、cmake配置项目的时间,而不计它们等待的编译。 - 有命令没有写进 trace 时,另有一行说明有多少条:catter 未能捕获的命令,以及在构建结束前没有结束的命令,例如比构建活得更久的构建服务器。
时间与捕获后端
每个捕获后端都会给出每条命令的启动时间和时长:
| 后端 | 启动时间和时长 |
|---|---|
hook | 在 Linux 和 macOS 上,由 catter-proxy 测量每条命令,从它启动 catter 让它运行的程序算起,到该程序退出为止;在 Windows 上由 catter 测量,从它接手钩子启动后挂起的程序算起,到该程序退出为止。构建的每个程序都要等到 catter 做出决定才启动,在 Linux 和 macOS 上还要经由 catter-proxy 启动:trace 显示的是构建在 catter 下运行的样子。 |
wrapper | 与 hook 下相同,但只针对 shim 所代替的编译器、链接器和归档工具,以及构建命令:trace 中只有这些命令。 |
ptrace | catter 的跟踪者(tracer)看到每个进程 exec 它的程序以及退出的时刻。构建的每个进程在每次 fork、exec 和退出时都会暂停,等 catter 读取它。 |
eslogger | Endpoint Security 给出的每次 exec 和退出的时间。它只观察:构建像没有 catter 时那样运行。 |
--from | 文件记录的时间,单位为微秒:事件的 execution 中有它的 start(从会话开始算起)和 duration。文件没有记录的时间为 0。 |
使用场景
- 识别串行化瓶颈 -- 发现有可用核心时构建仍一次只运行一条命令的阶段:
running计数器降到 1。 - 衡量实际并行度 -- 把同时运行的命令数与核心数、以及构建工具得到的
-j相比较。 - 定位慢速编译单元 -- 找到编译耗时不成比例的源文件,以及关键路径上的源文件。
- 调试构建系统配置 -- 检测错误的依赖配置、不必要的串行化或次优的任务调度。
