magic-trace：Jane Street 开源的高分辨率进程追踪工具

magic-trace 解决的不是"怎么调用模型"，而是"程序在实际运行时到底在做什么"。传统 perf 以采样方式工作，只能给出统计意义上的热点；magic-trace 则通过 Intel Processor Trace（Intel PT）技术，把选定时刻之前的所有控制流完整记录下来，生成可交互的时间线供开发者缩放、测量、定位问题。

先判断这个工具值不值得看

如果你在生产环境里遇到请求延迟异常但日志看不出问题、如果程序崩溃只有一个最终 stacktrace 如果你想验证一个函数"真的只跑了 6μs"，magic-trace 是目前最合适的开源工具。它不需要改代码、不需要插桩，只要attach 到进程就能拿到完整调用历史，开销只有 2%-10%。

如果你的场景是 daily profiling 或 continuous monitoring，magic-trace 不适合——它是触发式快照，不是持续采样工具。

系统地图

magic-trace 的工作分为三个阶段：

核心技术依赖：perf + Intel PT + Perfetto 可视化引擎。三个组件各司其职，不是自己造轮子。

核心机制

Intel PT 环形缓冲区

Intel PT 是 Intel 处理器内置的跟踪硬件，能以极低开销记录处理器的控制流。magic-trace 不做采样，而是让 Intel PT 把所有分支记录到一个环形缓冲区——相当于把进程"刚才在想什么"全部记下来。分辨率约为 40ns。

快照触发机制

有两种触发方式：

手动快照：Ctrl+C 终止 magic-trace，它会把缓冲区里从进程启动到此刻的所有记录 dump 出来。适合分析崩溃前的调用链。

函数触发：通过 -trigger 参数指定一个函数名，magic-trace 会在该函数被调用时自动触发快照。适合分析某个具体操作的调用路径，比如 HTTP 请求入口或调度器周期。

触发符号可以用 -trigger '?' 模糊匹配，也可以指定完整 mangled 符号，或者直接用默认的 magic_trace_stop_indicator 空函数。

可视化引擎

快照生成的是 FXT 格式文件，用浏览器打开 magic-trace.org 即可浏览。时间线支持 WASD 键盘缩放平移，点击调用栈可以测量精确时长，深色区域表示"未追踪"（通常是内核态调用）。

一次 tracing 任务如何流过系统

以一个 dlopen 示例程序为例：

1. 在终端启动 ./demo，记住 PID
2. 运行 magic-trace attach -pid $(pidof demo)
3. 程序调用 dlopen/dlsym/cos/printf/dlclose，Intel PT 持续记录
4. Ctrl+C 终止，magic-trace 生成 trace.fxt.gz
5. 浏览器打开 magic-trace.org，加载文件
6. 缩放到 cos 函数，测量执行时长约 5.7μs
7. 继续放大，发现有 5 个粉色未追踪区域——是 page fault handler

这个例子说明了一个关键点：传统 profiling 里"cos 跑了 5.7μs"就结束了；magic-trace 把这 5.7μs 里面发生了什么拆开给你看——有 page fault，有两次调用，第二次快得多。

与传统 perf 的对比

两者互补。Doug Patti（Jane Street）的评价很准确：perf 给你另一个视角，magic-trace 给你完整切片。

开销与限制

magic-trace 官方标注开销为 2%-10%，这个开销来自于 Intel PT 的持续记录能力。需要注意的是：

• 仅支持 Intel（Skylake/Broadwell 及以后），AMD 不支持
• 仅支持 Linux，macOS 和 Windows 不可用
• 虚拟机支持有限，大多数云 VM 不支持 Intel PT
• 触发快照的空函数调用约 10μs，仅在实际触发时才会产生

安装与快速开始

1. 确认平台支持（Intel Linux，非 VM）：dmesg | grep -i pt
2. 下载 最新 release 包，chmod +x magic-trace
3. 测试：magic-trace -help
4. 下载 demo.c，编译运行
5. magic-trace attach -pid $(pidof demo)，然后 Ctrl+C
6. 浏览器打开 magic-trace.org 加载 trace.fxt.gz

采用建议

先上的团队：

• 在 Linux 生产环境做性能诊断的团队
• 需要追踪"请求为什么慢"的 API 服务开发者
• 对 OCaml 程序有调试需求的团队（magic-trace 本身就是 OCaml 写的）

可以等等的团队：

• 主要在 macOS 或 Windows 开发
• 只需要 statistical profiling（普通 perf 足够）
• 虚拟机环境无法支持 Intel PT

项目元数据

magic-trace 不发送任何代码或追踪数据到外部。viz 由浏览器本地完成，隐私政策透明。