magic-trace：Jane Street 开源的高性能实时追踪工具

magic-trace 是少数把 Intel 处理器追踪（Processor Trace, PT）落到应用层调用栈重建上的开源工具。它用硬件级控制流记录换取事后可回放的完整轨迹：约 40 纳秒分辨率、2%-10% 开销、可回看约 10 毫秒（可配置）的调用历史。在采样式 profiler 看不到的微秒级毛刺、时序异常、崩溃前最后一段执行路径上，magic-trace 提供的是另一种证据。

项目起源于 2021 年夏天，Jane Street 工程师 Tristan Hume 起草了项目方案，与实习生 Chris Lambert 一起完成实现：先用一周做出基于 perf 的原型，实习结束前又完成了从零的实现。2022 年 1 月项目开源，此后由 Jane Street 维护，最新版本 v1.2.4（2025 年 4 月）。Jane Street 做的是亚微秒级延迟的交易业务，交易系统几乎全部时间在等待网络包，却要求在远小于采样间隔的尺度上做出响应——magic-trace 最初就是为定位这类"宏观 profile 看不见的性能问题"而生。代码库 99.7% 是 OCaml，底层依赖 Linux perf 驱动 Intel PT。

为什么 PT 的开销能做到个位数百分比

理解 magic-trace 的前提是理解 Intel PT 的工作方式。PT 是 CPU 内置的硬件单元，而非软件插桩。PT 启用后，处理器在执行指令的同时，由专用硬件把控制流变化信息编码成高度压缩的数据包，写入物理内存中预留的环形缓冲区（Ring Buffer）。编码不在指令执行路径上，追踪的开销主要来自两处：数据包写入内存占用的带宽，以及事后解码消耗的 CPU 时间。Jane Street 在开销文档里给出的测量是：PT 追踪消耗数百 Mbps 的内存带宽，2%-10% 的应用减速大部分来源于此；如果带宽即将饱和，PT 会自动暂停追踪。

PT 的核心设计围绕控制流改变指令（Change of Flow Instruction, COFI）。CPU 只在控制流发生跳转时才记录信息，顺序执行的基本块不产生任何数据包。COFI 分三类：

• 直接条件分支（如 je、jne、loop）：用 1 个比特记录是否跳转（Taken / Not Taken），多个比特压缩成一个 TNT 数据包。
• 直接无条件跳转（如相对 jmp、call）：目标地址可从二进制反汇编推断，不记录任何信息。
• 间接跳转（如寄存器或内存寻址的 call、jmp、ret）：目标地址运行时才能确定，用 TIP（Target IP）数据包记录目标地址。

异步事件（中断、异常）的源地址和目标地址都无法从二进制推断，PT 用 FUP（Flow Update Packet）记录源地址、TIP 记录目标地址，两者成对出现，FUP 先于 TIP。

其余的包各管一件事。PSB（Packet Stream Boundary）是同步包，按可编程的周期插入（perf 的 psb_period 参数，最小 2KiB 一个，可配到 16KiB 及更高），解码器靠它定位数据流边界，每个 PSB 附带一个 TSC 时间戳。PIP（Paging Information Packet）记录 CR3 寄存器变化，用于把线性地址归属到正确的进程。

时间信息由一组专用包提供：TSC（Time-Stamp Counter）、CBR（Core Bus Ratio）、MTC（Mini Time Counter）、CYC（Cycle Count）。CYC 包记录两个数据包之间经过的处理器时钟周期数，这是 magic-trace 达到约 40 纳秒分辨率的基础。

magic-trace 的架构

一个容易产生的误解是 magic-trace 自己实现了 PT 解码器。实际上它把重活留给了 perf：官方代码导览自嘲它"多少算是个升级版的文本过滤器"。perf 负责配置 PT 硬件（IA32_RTIT_CTL 等 MSR）、管理 ToPA（Table of Physical Addresses）输出缓冲、解码原始 PT 数据包流；magic-trace 解析 perf script 输出的文本，把它变成内部事件，再重建调用栈：

代码库里保留了 direct_backend/ 目录——绕过 perf 命令行、直接对接 perf 子系统的方案，目前是实验性的，默认不参与构建。现阶段唯一可用的路径就是上面表格里的 perf 命令行方案。

调用栈重建是 OCaml 后端真正的复杂点：把"哪条指令跳到了哪里"还原成嵌套的函数调用栈，需要结合 ELF 二进制和调试信息做符号解析，处理 OCaml 编译器的命名约定和尾调用，处理 C++ 的 name mangling。按支持平台的官方文档，OCaml、C、C++、Rust 得到完整支持；Python 程序只能解出 C 帧；带异常的程序目前会让追踪视图混乱，官方列为待改进项。

最终产物是 trace.fxt.gz 文件，采用 Fuchsia Trace Format（FXT），gzip 压缩。把文件载入 magic-trace.org（Perfetto 的轻量 fork，完全在浏览器端运行，不上传数据），就能看到类似示波器的时序波形：横轴是时间，纵轴是调用栈深度，每个色块是一个函数调用，可以放大到单条指令测量。

与 perf / strace / ftrace 的对比

perf 采样回答"统计意义上哪里慢"，magic-trace 回答"这一次具体发生了什么"。两者互补：perf 适合先找到大致区域，magic-trace 适合钻进去看那 70 纳秒的函数到底调用了什么。Jane Street 工程师 Doug Patti 的评价是，magic-trace 的价值在于任意缩放级别都能看到切片细节，他能看到一个 70 纳秒函数内部的所有调用——这在 perf 里是看不见的。

strace 和 ftrace 的粒度和机制完全不同。strace 只看系统调用边界，ftrace 主要面向内核侧。magic-trace 看的是用户态控制流的完整路径。

一次完整的追踪流程

以官方 demo 为例，追踪 dlopen 的执行路径。先准备被测程序：

// demo.c，改自 man 3 dlopen
// gcc demo.c -ldl -o demo
// ./demo 让它持续运行

挂接到正在运行的进程：

magic-trace attach -pid $(pidof demo)

看到成功挂接的提示后，等待几秒，按 Ctrl+C 让 magic-trace 脱离。它会在当前目录生成 trace.fxt.gz。

打开 magic-trace.org，左上角点击 “Open trace file”，载入刚才的文件。用 W 键以鼠标位置为中心放大，S 缩小，A/D 左右移动，滚轮上下滚动调用栈。放大到能看到 dlopen / dlsym / cos / printf / dlclose 的单次循环。

在时间线上点击拖拽可以测量区间。官方示例里测量 cos 调用耗时约 5.7 微秒。继续放大，会看到 5 个粉色的 “[untraced]” 色块——那是内核态的缺页处理程序。用 root 权限重新运行并加 -trace-include-kernel 参数，就能看到这些内核栈。demo 程序实际调用了两次 cos，第二次因为页已经驻留，耗时远小于第一次。

这套流程不需要修改应用代码，不需要重新编译，对运行中的进程是只读旁观：挂接、等待、脱离、回放。

触发机制：stop indicator

magic-trace 持续把控制流写入环形缓冲区，默认覆盖旧数据。要在特定时刻冻结快照，有两种方式。

第一种是手动 Ctrl+C：magic-trace 在退出时如果还没拍过快照，会自动抓取缓冲区末尾。

第二种是 stop indicator（停止指示器）。用 -trigger 参数指定一个函数符号，当被测程序调用该函数时，magic-trace 自动抓取快照：

# 交互式选择符号（模糊匹配）
magic-trace attach -pid $(pidof demo) -trigger '?'

# 指定具体符号
magic-trace attach -pid $(pidof demo) -trigger 'my_module__handle_request'

# 使用默认符号 magic_trace_stop_indicator
magic-trace attach -pid $(pidof demo) -trigger '.'

stop indicator 是一个空的、不被内联的函数，可以留在生产代码里。它本身不做任何事，magic-trace 依赖的仅是这个符号名存在。抓取快照时应用会停顿约 10 微秒，且只在 magic-trace 实际挂接并触发时产生——官方因此建议把触发点放在"完整服务完一个用户请求之后"，避免停顿落进用户请求的耗时里。适合放置 stop indicator 的位置包括：异步运行时中调度周期超时的入口、服务端请求处理超时的分支、垃圾回收结束后的回调、编译器某个 pass 完成后。

OCaml 应用还可以直接用随项目发布的 magic_trace 库：调用 Magic_trace.take_snapshot 即时触发快照（实现是向父进程发 SIGUSR2），配合异步运行时的超时检测，就是 Jane Street 内部定位长周期问题的用法。

硬件与平台边界

magic-trace 的能力边界由 Intel PT 的硬件要求决定：

• 处理器：Intel，Skylake 及以上（Broadwell 技术上支持，但时间分辨率降到约 1 微秒，官方不常规测试）。
• 操作系统：Linux only。PT 依赖 perf 子系统，其他系统暂不支持。
• 虚拟机：大多数虚拟机不支持 PT 透传。官方给出的可用条件是 KVM 宿主机、内核 5.0+；公有云虚拟机不保证可用，裸金属实例没有此问题。
• perf 版本：退出时快照需要 perf 5.4+；内核态追踪在 5.5 以上效果更好。
• 异常处理：目前不支持，OCaml/C++ 抛异常的路径会扰乱追踪视图。
• 检查支持：grep intel_pt /proc/cpuinfo 有输出即可；对应到 CPUID 是 EAX=07H、ECX=0H 时 EBX 的第 25 位。

这些限制是 magic-trace 最常绊倒新人的地方。AMD 处理器没有 PT，ARM 的 ETM（Embedded Trace Macrocell）机制不同，官方明确表示两者都不支持。

Jane Street 的使用场景

Jane Street 的核心业务是量化交易和做市，官网对交易系统的描述是亚微秒级（sub-microsecond）。官方博文里解释过为什么采样式 profiler 在这个尺度上失效：典型采样器每隔约 250 微秒打断一次程序、记一份调用栈再聚合，而他们的交易系统几乎全部时间在等待网络包，要求在远小于这个间隔的尺度上响应——“你运气好才能在关心的代码里采到一个样本”。采样还分不清"一个函数被调了 10 次"和"一次调用慢了 10 倍"，magic-trace 的完整控制流恰好补上这两点。

官方博文给出过三个真实案例：

• 一次 100 纳秒的性能回归，追查结果是某个补丁让一个本该内联的函数调用失去了内联。
• 升级编译器后交易系统变慢，定位下来同样是内联决策变了。
• 异步调度里出现长达 15 秒的 async cycle。在周期超过阈值时调用 Magic_trace.take_snapshot，回看最后约 10 毫秒，发现问题出在某个集合的条目数远超预期——并且能区分是循环次数太多，还是单次执行太慢。

另一个 README 明确列出的用法是崩溃前回放：环形缓冲区里保留着最后约 10 毫秒的执行历史，比崩溃瞬间的栈回溯信息量大得多。

这些场景的共同点是：问题已经发生，需要事后还原"当时到底执行了什么"。PT 的事后回放模型正好匹配这种需求。

采用建议

magic-trace 适合两类团队。第一类是运行在 Intel/Linux 裸机上、对延迟敏感的服务团队，尤其是 OCaml、C、C++ 或 Rust 代码库。第二类是被竞态、崩溃前状态、微秒级毛刺困住的工程师，采样式 profiler 已经无法定位问题。

不适合的场景：AMD 平台、Windows/macOS 环境、虚拟机内（除非确认是 KVM 宿主机且内核 5.0+）、代码大量使用异常（追踪视图会混乱）、需要长期持续追踪（环形缓冲区只保留最近约 10 毫秒，不适合做全量审计）。

采用顺序上，建议先用 perf record 找到大致的性能区域，再用 magic-trace 钻入那个区域做指令级回放。把 stop indicator 放在"已经知道有问题"的代码路径入口，比盲目挂接一个跑满负载的生产进程更有针对性。两点代价要预算进去：追踪本身开销 2%-10%（大头是内存带宽），快照时应用停顿约 10 微秒；解码是事后批量进行的，官方博文提到最快的解码器也比实时慢约 60 倍，高峰期对核心服务长时间挂接要慎重。如果带宽不足导致追踪频繁暂停，trace 里会出现 Decode Errors——官方排查文档列的第一原因就是内存带宽饱和，可以把时间分辨率调低来缓解。

GitHub: https://github.com/janestreet/magic-trace 在线 UI: https://magic-trace.org/