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

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

项目由 Jane Street 工程师 Tristan Hume 在内部开发，2020 年开源，当前由 Jane Street 维护，最新版本 v1.2.4（2025 年 4 月）。Jane Street 是全球最大的 OCaml 商业用户，量化交易业务对延迟敏感，magic-trace 最初就是为定位交易系统里那些"宏观 profile 看不见的微妙性能问题"而生。代码库 99.7% 是 OCaml，底层依赖 Linux perf 驱动 Intel PT。

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

理解 magic-trace 的前提是理解 Intel PT 的工作方式。PT 是 CPU 内置的硬件单元，而非软件插桩。当 PT 启用后，处理器在执行指令的同时，把控制流变化信息编码成高度压缩的数据包，直接写入物理内存中预留的环形缓冲区（Ring Buffer），绕过 TLB 和缓存。这意味着追踪本身不占用流水线周期，也不污染缓存层级，开销主要来自数据包写入内存的带宽消耗和后续解码，而不是"每条指令多执行一段代码"。

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。

为了让解码器能在数据流中定位边界，PT 每 4KB 生成一个 PSB（Packet Stream Boundary）心跳包。PIP（Paging Information Packet）记录 CR3 寄存器变化，用于把线性地址归属到正确的进程。TSC（Time-Stamp Counter）、CBR（Core Bus Ratio）、MTC（Mini Time Counter）、CYC（Cycle Count）等数据包提供时间信息，CYC 包记录两个数据包之间经过的处理器时钟周期数，这是 magic-trace 达到约 40 纳秒分辨率的基础。

这套机制决定了 PT 的开销结构：硬件做编码，软件做解码。追踪阶段几乎不干扰被测程序，代价转移到事后解码的 CPU 时间上。

magic-trace 的架构

magic-trace 本身不直接操作 PT 的 MSR（Model Specific Register），而是借助 Linux perf 子系统。perf 负责配置 IA32_RTIT_CTL 等 MSR、收集原始 PT 数据流、处理 ToPA（Table of Physical Addresses）输出缓冲。magic-trace 在 perf 之上做三件事：

解码阶段，magic-trace 用 libipt 把 TNT、TIP、FUP 等数据包还原成"哪条指令跳到了哪里"，再结合被测程序的 ELF 二进制和调试信息，重建出完整的函数调用栈。OCaml 后端负责符号解析——把指令地址映射到函数名和源码行号。对于 OCaml 程序，符号解析需要处理 OCaml 编译器的命名约定；对于 C++ 程序，需要处理 name mangling。任何使用 ELF 的语言都能受益，但 OCaml 和 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，第二次因为页已经驻留，耗时远小于第一次。

这个流程体现了 magic-trace 的核心用法：挂接、触发、脱离、回放。它不修改应用代码，不需要重新编译，对运行中的进程是只读旁观。

触发机制：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 完成后。

硬件与平台边界

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

• 处理器：Intel，Skylake 及以上（Broadwell 技术上支持，但时间分辨率降到约 1 微秒，官方不常规测试）。
• 操作系统：Linux only。PT 依赖 perf 子系统，其他系统暂不支持。
• 虚拟机：大多数虚拟机不支持 PT 透传。裸机或支持 PT 透传的虚拟化环境才行。
• 检查支持：用 cpuid 指令，EAX=07H、ECX=0H，检查 EBX 的第 25 位。

这些限制是 magic-trace 最常绊倒新人的地方。AMD 处理器没有 PT 等价物，ARM 的 ETM（Embedded Trace Macrocell）机制不同，magic-trace 目前不支持。

Jane Street 的使用场景

Jane Street 的核心业务是量化交易和做市，延迟敏感度在微秒级。OCaml 是他们的主要开发语言，交易系统、研究工具、内部基础设施大量使用 OCaml。在这种场景下，传统 profiler 的采样粒度不够：一个 50 微秒的请求里，可能有一个 3 微秒的异常路径，采样式 profiler 大概率完全错过。

magic-trace 在 Jane Street 内部的典型用法包括：

• 交易请求延迟根因分析：在请求处理超时的分支放置 stop indicator，抓取那一次请求的完整调用栈。
• 垃圾回收影响评估：在 GC 结束后触发快照，看 GC 中断了什么、恢复后执行了什么。
• 并发竞态时序重建：PT 记录的是精确控制流，多线程各自的轨迹可以对照时间戳排列。
• 崩溃前回放：程序崩溃时，环形缓冲区里保留了最后约 10 毫秒的执行历史，比一个崩溃瞬间的栈回溯信息量大得多。

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

采用建议

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

不适合的场景：AMD 平台、Windows/macOS 环境、虚拟机内（除非确认 PT 透传可用）、需要长期持续追踪（环形缓冲区只保留最近约 10 毫秒，不适合做全量审计）。

采用顺序上，建议先用 perf record 找到大致的性能区域，再用 magic-trace 钻入那个区域做指令级回放。把 stop indicator 放在"已经知道有问题"的代码路径入口，比盲目挂接一个跑满负载的生产进程更有针对性。magic-trace 的开销虽然只有个位数百分比，但解码阶段会消耗额外 CPU，不适合在高峰期对核心服务长时间挂接。

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