janestreet--magic-trace/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

magic-trace

概述

magic-trace 收集并展示进程正在执行内容的高分辨率追踪（trace）记录。人们用它来：

• 查明为何生产环境中运行的应用在处理某些请求时很慢，同时又在应付海量无趣请求，
• 看清代码实际在做什么，而不是以为它在做什么，
• 获取应用崩溃前的执行历史，而不只是最后时刻的一张堆栈跟踪（stacktrace），
• ……以及更多用途！

magic-trace：

• 具有 2%-10% 开销,
• 使用时不需修改应用，
• 以约 40ns 分辨率追踪每一次函数调用，并且
• 渲染可回溯约 10ms（可配置）的调用栈时间线。

用法类似 perf: 指向一个进程即可开始运行。与 perf 的关键区别在于：magic-trace 不是随时间对调用栈采样，而是使用 Intel Processor Trace 对截至某一选定时刻的全部控制流环形缓冲区做快照[^1]。然后你可以交互式地浏览时间线上发生的事。

你可以让 magic-trace 盯住某个函数，这样当应用调用它时，magic-trace 就会拍一张快照。或者附加到正在运行的进程上，用 Ctrl+C 分离，以查看程序任意时刻的追踪记录。

[^1]：perf 也能做到这一点，但多数人并不这么用它。事实上，若深入底层，你会发现 magic-trace 使用 perf 来驱动 Intel PT。

用户评价

"Magic-trace 是我用过的最简单的命令行调试工具之一。"

• Francis Ricci, Jane Street

"Magic-trace 不仅用于性能分析。它能直接揭示程序中发生了什么、何时发生以及为何发生。建议为满足一切自省（introspective）目标时都考虑使用它！"

• Andrew Hunter, Jane Street

我经常用 perf，我认为 perf 和 magic-trace 各自提供了对方没有的视角。我从 magic-trace 获益，完全是因为它能在任意缩放级别下按切片展示，因此我能看到某个 70ns 函数执行的所有函数调用，而在 perf 中这些内容完全不可见。

• Doug Patti, Jane Street

更多用户评价……

安装

1. 确保要追踪的系统受支持. 最容易让人栽跟头的限制是：虚拟机大多不受支持、仅支持 Intel（Skylake[^3] 或更新）、仅支持 Linux。

2. 从最新发布页. 获取发布版二进制文件。

   1. 若下载的是预编译二进制文件（非软件包），chmod +x magic-trace[^4]
   2. 若下载的是软件包，运行 sudo dpkg -i magic-trace*.deb

   然后运行 magic-trace -help 进行测试，应会显示一些帮助文本。

[^3]：严格来说，任何比 Broadwell 更新的平台都可以，但我们不会定期在该平台上测试，且时间分辨率更差（约 1us）。 [^4]：https://github.com/actions/upload-artifact/issues/38

快速入门

1. 这里's 有一份可供试用的示例 C 程序。它是 man 3 dlopen 中示例的轻微修改版。下载后，用 gcc demo.c -ldl -o demo 编译，再以 ./demo 保持运行。我们将用该程序学习 dlopen 的用法。

2. 运行 magic-trace attach -pid $(pidof demo)。看到已成功附加的提示后，等待几秒，然后对 magic-trace 按 Ctrl+C。它会在当前工作目录输出名为 trace.fxt.gz 的文件。

3. 打开 magic-trace.org, 点击左上角的 "Open trace file"（打开追踪文件），并选择上一步生成的追踪文件。

4. 此时应已展开为一条追踪记录。放大直到能看到 dlopen/dlsym/cos/printf/dlclose 的单次循环。
   • W 向鼠标光标所在位置放大（需要多次放大才能看到有用内容），
   • S 缩小，
   • A 向左移动，
   • D 向右移动，以及
   • 滚轮在调用栈上下移动视口。只有查看特别深的堆栈跟踪时才需要滚动，对本示例可能用处不大。

5. 在调用栈周围的空白处点击拖动以进行测量。在时间线顶部点击可插旗标。使用测量工具，测量运行 cos 的耗时。在我的屏幕上约为 ~5.7us。

恭喜，你刚刚神奇地完成了第一次程序追踪！

与传统 perf 工作流相比，magic-trace 擅长生成假设。例如，你可能会注意到运行 cos 耗时 6us 实在太长了！若再放大，你会看到其中实际上有五个粉色的 "[untraced]" 单元格。若以 root 重新运行 magic-trace 并传入 -trace-include-kernel，就能看到它们的堆栈跟踪。它们是页错误（page fault）处理程序！演示程序实际上调用了 cos 两次。若在 6us 的 cos 调用末尾附近再放大，你会看到第二次调用耗时远更少且不会发生页错误。

使用方法

magic-trace 将持续把控制流记录到环形缓冲区。在某种触发条件下，它对缓冲区拍快照并重建调用栈。

有两种拍快照的方式：

我们刚才做的就是其中一种：Ctrl+C 结束 magic-trace。若 magic-trace 在未拍过快照的情况下终止，会对程序末尾拍一张快照。

你也可以在应用调用某个函数时触发快照。做法是向 magic-trace 传入 -trigger 标志。

• -trigger '?' 会弹出模糊查找选择器，让你从可执行文件中的所有符号里选择，
• -trigger SYMBOL 选择你事先知道的某个具体、完整修饰（mangled）符号，以及
• -trigger . 选择默认符号 magic_trace_stop_indicator。

停止指示器（stop indicator）很强大。以下是一些你可能想放置它的场景：

• 若使用异步运行时，可在调度器周期耗时过长时放置。
• 在服务器中，当某个请求耗时出奇地长时。
• 垃圾回收器运行之后，查看它在做什么以及它打断了什么。
• 某个编译器 pass 完成之后。

你可以把停止指示器留在生产代码中。它不必执行任何特定操作，magic-trace 只需要函数名。它只是一个空函数，但不会被内联。调用它大约耗费 ~10us，但仅在 magic-trace 实际用它拍快照时才会产生该开销。

文档

更多文档可在 magic-trace wiki. 上查阅。

讨论

加入我们的 Discord 进行实时交流，或前往 GitHub 讨论组 进行异步讨论。

贡献

如果你想贡献代码：

1. 阅读构建说明,
2. 配置你的编辑器,
3. 快速浏览代码库,，然后
4. 查看 issue 跟踪器 寻找合适的入门项目。

隐私政策

magic-trace 不会将你的代码或其衍生内容（包括 traces）发送到任何地方。

magic-trace.org 是 Perfetto, 的轻度修改 fork，完全在浏览器中运行。据我们所知，它不会将 trace 发送到任何地方。如果你担心这一点日后可能改变，可以 搭建本地 Perfetto UI 副本 并使用它。

致谢

Tristan Hume 是 magic-trace 的原始作者。他在 Jane Street, 工作期间编写了该项目，Jane Street 目前负责维护。

Intel PT（Intel Processor Trace）是 magic-trace 所依赖的基础技术。我们要感谢 Intel 的同仁多年来为使其可用所做的努力，尽管它在更广泛的软件社区中普及缓慢。

如果没有 perf 对 Intel PT 的广泛支持，magic-trace 就不可能存在。perf 承担了大部分解读 Intel PT 输出数据的工作，若没有他们的努力，magic-trace 很可能根本不会问世。感谢你们，perf 开发者。

magic-trace.org 是 Perfetto, 的 fork，仅做了少量修改。我们要感谢 Google 负责该项目的同仁。这是一个高质量的代码库，很好地解决了一个难题。

magic-trace 背后的思想绝非独创。我们整理了一份 先前工作 列表，记录了影响其设计的内容。