magic-trace
一款基于 Intel Processor Trace 的高分辨率追踪工具，以约 40 纳秒精度记录程序全部函数调用，提供回放式交互分析，无需修改代码，开销仅 2-10%。
像回放录像一样查看程序纳秒级函数调用详情，快速定位性能瓶颈与异常行为。
核心功能
- 捕获所有函数调用（包括 C/C++、Rust 等编译语言），分辨率约 40 纳秒
- 无侵入式追踪：无需修改应用程序代码或重新编译
- 支持两种触发模式：手动 Ctrl+C 或指定函数自动触发，最多可回溯约 10 毫秒历史
- 生成交互式调用栈时间线，支持缩放、测量、标记等操作
- 通过 Intel Processor Trace 硬件实现低开销（2-10%）
避坑指南
- •仅支持 Intel Skylake 及以后的 CPU 架构，且仅限 Linux 系统
- •不支持在虚拟机中运行（虚拟机通常不支持 Intel PT 穿透）
- •使用内核态追踪（-trace-include-kernel）需要 root 权限
- •触发函数必须是一个空函数且不能被内联，否则 magic-trace 无法识别
- •追踪时进程额外开销约 2-10%，高频场景下需评估影响
适用场景
- 分析生产环境请求响应慢的原因，区分异常请求与正常请求的行为差异
- 追踪程序崩溃前最后几毫秒的完整执行路径，替代单一栈回溯
详细介绍
magic-trace 是 Jane Street 开发的一款高性能追踪工具，基于 Intel Processor Trace 技术，以约 40 纳秒的分辨率记录程序执行的所有函数调用。它通过环形缓冲区持续录制控制流，在触发时（如 Ctrl+C 或调用指定函数）截取触发点前约 10 毫秒的完整调用栈历史，并生成可交互的时间线视图。与传统采样工具 perf 不同，magic-trace 捕获全部控制流，让你能看清事件发生前微秒级的精确行为。它无需修改应用程序代码，额外开销仅 2%-10%，支持通过符号模糊匹配或预留空函数作为触发点。适用于生产环境性能问题排查、理解复杂代码执行过程以及崩溃现场回放等场景。
常见问题与排障 (2)
故障排除为什么构建 magic-trace 时，make default 会失败并提示 'Library "ocaml_intrinsics" not found'？
测试目标 'variable-duration' 依赖于 'ocaml_intrinsics'，但 'ocaml_intrinsics' 未在 magic-trace.opam 中声明为依赖项。请将 'ocaml_intrinsics' 添加到 opam 文件的 'with-test' 依赖项中，然后再次运行 opam install . --deps-only 和 make default。或者在构建前手动执行 opam install ocaml_intrinsics。
故障排除为什么magic-trace在使用perf 6时无法解析符号？
magic-trace 目前仅支持 perf 版本 5 或更早。perf 6 输出的符号格式 magic-trace 尚无法识别。要解决此问题，请降级到 perf 版本 5。
标签
快速上手
安装软件
根据你的发行版安装对应的包（dpkg / rpm / AppImage）
下载最新版本的可执行文件，运行 chmod +x magic-trace 赋予执行权限
启动目标程序，运行 magic-trace attach -pid $(pidof 程序名)
等待数秒后按下 Ctrl+C，magic-trace 会在当前目录生成 trace.fxt.gz 文件
- 下载最新版本的可执行文件，运行 chmod +x magic-trace 赋予执行权限
- 启动目标程序，运行 magic-trace attach -pid $(pidof 程序名)
- 等待数秒后按下 Ctrl+C，magic-trace 会在当前目录生成 trace.fxt.gz 文件
暂未获取到校验码
该项目暂未在 GitHub Release 页面提供 SHA-256 校验码
SHA256 校验码
暂无校验码
建议从 GitHub Releases 页面直接下载，并自行核对文件完整性
本平台所有 SHA-256 校验码均提取自项目在 GitHub 官方 Release 页面发布的文件，未做任何修改。你可以通过 GitHub Releases 页面自行验证。
开源透明
查看 GitHub 源码卸载说明
直接删除下载的可执行文件即可（无其他系统文件残留）。
无额外依赖
下载后即可直接使用，无需安装其他运行环境
遇到问题？查看下方 FAQ
2 FAQs