diff --git a/README.md b/README.md index 832a55e..f7a9f17 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/janestreet/magic-trace) · [上游 README](https://github.com/janestreet/magic-trace/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

@@ -18,148 +24,146 @@

-# Overview +# 概述 -magic-trace collects and displays high-resolution traces of what a process is doing. People have used it to: +magic-trace 收集并展示进程正在执行内容的高分辨率追踪（trace）记录。人们用它来： -- figure out why an application running in production handles some requests slowly while simultaneously handling a sea of uninteresting requests, -- look at what their code is *actually* doing instead of what they *think* it's doing, -- get a history of what their application was doing before it crashed, instead of a mere stacktrace at that final instant, -- ...and much more! +- 查明为何生产环境中运行的应用在处理某些请求时很慢，同时又在应付海量无趣请求， +- 看清代码*实际*在做什么，而不是*以为*它在做什么， +- 获取应用崩溃前的执行历史，而不只是最后时刻的一张堆栈跟踪（stacktrace）， +- ……以及更多用途！ -magic-trace: +magic-trace： -- has [2%-10% overhead](https://github.com/janestreet/magic-trace/wiki/Overhead), -- doesn't require application changes to use, -- traces *every function call* with ~40ns resolution, and -- renders a timeline of call stacks going back (a configurable) ~10ms. +- 具有 [2%-10% 开销](https://github.com/janestreet/magic-trace/wiki/Overhead), +- 使用时不需修改应用， +- 以约 40ns 分辨率追踪*每一次函数调用*，并且 +- 渲染可回溯约 10ms（可配置）的调用栈时间线。 -You use it like [`perf`](https://en.wikipedia.org/wiki/Perf_(Linux)): point it to a process and off it goes. The key difference from `perf` is that instead of sampling call stacks throughout time, magic-trace uses [Intel Processor Trace](https://man7.org/linux/man-pages/man1/perf-intel-pt.1.html) to snapshot a ring buffer of *all control flow* leading up to a chosen point in time[^1]. Then, you can explore an interactive timeline of what happened. +用法类似 [`perf`](https://en.wikipedia.org/wiki/Perf_(Linux)): 指向一个进程即可开始运行。与 `perf` 的关键区别在于：magic-trace 不是随时间对调用栈采样，而是使用 [Intel Processor Trace](https://man7.org/linux/man-pages/man1/perf-intel-pt.1.html) 对截至某一选定时刻的*全部控制流*环形缓冲区做快照[^1]。然后你可以交互式地浏览时间线上发生的事。 -You can point magic-trace at a function such that when your application calls it, magic-trace takes a snapshot. Alternatively, attach it to a running process and detach it with Ctrl+C, to see a trace of an arbitrary point in your program. +你可以让 magic-trace 盯住某个函数，这样当应用调用它时，magic-trace 就会拍一张快照。或者附加到正在运行的进程上，用 Ctrl+C 分离，以查看程序任意时刻的追踪记录。 -[^1]: `perf` can do this too, but that's not how most people use it. In fact, if you peek under the hood you'll see that magic-trace uses `perf` to drive Intel PT. +[^1]：`perf` 也能做到这一点，但多数人并不这么用它。事实上，若深入底层，你会发现 magic-trace 使用 `perf` 来驱动 Intel PT。 -# Testimonials +# 用户评价 -> "Magic-trace is one of the simplest command-line debugging tools I have ever used." +> "Magic-trace 是我用过的最简单的命令行调试工具之一。" - Francis Ricci, Jane Street -> "Magic-trace is not just for performance. The tool gives insight directly into what happens in your program, when, and why. Consider using it for all your introspective goals!" +> "Magic-trace 不仅用于性能分析。它能直接揭示程序中发生了什么、何时发生以及为何发生。建议为满足一切自省（introspective）目标时都考虑使用它！" - Andrew Hunter, Jane Street -> I use perf a ton, and I think that both perf and magic-trace give perspectives that the other doesn't. The benefit I got from magic-trace was entirely based on the fact that it works in slices at any zoom level, so I was able to see all the function calls that a 70ns function was performing, which was invisible in perf. +> 我经常用 perf，我认为 perf 和 magic-trace 各自提供了对方没有的视角。我从 magic-trace 获益，完全是因为它能在任意缩放级别下按切片展示，因此我能看到某个 70ns 函数执行的所有函数调用，而在 perf 中这些内容完全不可见。 - Doug Patti, Jane Street -[more testimonials...](https://github.com/janestreet/magic-trace/wiki/Unsolicited-reviews) +[更多用户评价……](https://github.com/janestreet/magic-trace/wiki/Unsolicited-reviews) -# Install +# 安装 -1. Make sure the system you want to trace is [supported](https://github.com/janestreet/magic-trace/wiki/Supported-platforms,-programming-languages,-and-runtimes). The constraints that most commonly trip people up are: VMs are mostly not supported, Intel only (Skylake[^3] or later), Linux only. +1. 确保要追踪的系统[受支持](https://github.com/janestreet/magic-trace/wiki/Supported-platforms,-programming-languages,-and-runtimes). 最容易让人栽跟头的限制是：虚拟机大多不受支持、仅支持 Intel（Skylake[^3] 或更新）、仅支持 Linux。 -2. Grab a release binary from the [latest release page](https://github.com/janestreet/magic-trace/releases/latest). +2. 从[最新发布页](https://github.com/janestreet/magic-trace/releases/latest). 获取发布版二进制文件。 - 1. If downloading the prebuilt binary (not package), `chmod +x magic-trace`[^4] - 1. If downloading the package, run `sudo dpkg -i magic-trace*.deb` + 1. 若下载的是预编译二进制文件（非软件包），`chmod +x magic-trace`[^4] + 1. 若下载的是软件包，运行 `sudo dpkg -i magic-trace*.deb` - Then, test it by running `magic-trace -help`, which should bring up some help text. + 然后运行 `magic-trace -help` 进行测试，应会显示一些帮助文本。 -[^3]: Strictly speaking, anything newer than Broadwell, but this is not a platform we regularly test on, and timing resolution is worse (~1us). -[^4]: https://github.com/actions/upload-artifact/issues/38 +[^3]：严格来说，任何比 Broadwell 更新的平台都可以，但我们不会定期在该平台上测试，且时间分辨率更差（约 1us）。 +[^4]：https://github.com/actions/upload-artifact/issues/38 -# Getting started +# 快速入门 -1. [Here](https://raw.githubusercontent.com/janestreet/magic-trace/master/demo/demo.c)'s a sample C program to try out. It's a slightly modified version of the example in `man 3 dlopen`. Download that, build it with `gcc demo.c -ldl -o demo`, then leave it running `./demo`. We're going to use that program to learn how `dlopen` works. +1. [这里](https://raw.githubusercontent.com/janestreet/magic-trace/master/demo/demo.c)'s 有一份可供试用的示例 C 程序。它是 `man 3 dlopen` 中示例的轻微修改版。下载后，用 `gcc demo.c -ldl -o demo` 编译，再以 `./demo` 保持运行。我们将用该程序学习 `dlopen` 的用法。 -2. Run `magic-trace attach -pid $(pidof demo)`. When you see the message that it's successfully attached, wait a couple seconds and Ctrl+C `magic-trace`. It will output a file called `trace.fxt.gz` in your working directory. +2. 运行 `magic-trace attach -pid $(pidof demo)`。看到已成功附加的提示后，等待几秒，然后对 `magic-trace` 按 Ctrl+C。它会在当前工作目录输出名为 `trace.fxt.gz` 的文件。

-3. Open [magic-trace.org](https://magic-trace.org/), click _"Open trace file"_ in the top-left-hand and give it the trace file generated in the previous step. +3. 打开 [magic-trace.org](https://magic-trace.org/), 点击左上角的 _"Open trace file"_（打开追踪文件），并选择上一步生成的追踪文件。

-4. That should have expanded into a trace. Zoom in until you can see an individual loop through `dlopen`/`dlsym`/`cos`/`printf`/`dlclose`. - - W zooms into wherever your mouse cursor is pointed (you'll need to zoom in a bunch to see anything useful), - - S zooms out, - - A moves left, - - D moves right, and - - scroll wheel moves your viewport up and down the stack. You'll only need to scroll to see particularly deep stack traces, it's probably not useful for this example. +4. 此时应已展开为一条追踪记录。放大直到能看到 `dlopen`/`dlsym`/`cos`/`printf`/`dlclose` 的单次循环。 + - W 向鼠标光标所在位置放大（需要多次放大才能看到有用内容）， + - S 缩小， + - A 向左移动， + - D 向右移动，以及 + - 滚轮在调用栈上下移动视口。只有查看特别深的堆栈跟踪时才需要滚动，对本示例可能用处不大。

-5. Click and drag on the white space around the call stacks to measure. Plant flags by clicking in the timeline along the top. Using the measurement tool, measure how long it takes to run `cos`. On my screen it takes ~5.7us. +5. 在调用栈周围的空白处点击拖动以进行测量。在时间线顶部点击可插旗标。使用测量工具，测量运行 `cos` 的耗时。在我的屏幕上约为 ~5.7us。

-Congratulations, you just magically traced your first program! +恭喜，你刚刚神奇地完成了第一次程序追踪！ -In contrast to traditional `perf` workflows, magic-trace excels at hypothesis generation. For example, you might notice that taking 6us to run `cos` is a really long time! If you zoom in even more, you'll see that there's actually five pink "\[untraced\]" cells in there. If you re-run magic-trace with root and pass it `-trace-include-kernel`, you'll see stacktraces for those. They're page fault handlers! The demo program actually calls `cos` twice. If you zoom in even more near the end of the 6us `cos` call, you'll see that the second call takes *far* less time and does not page fault. +与传统 `perf` 工作流相比，magic-trace 擅长生成假设。例如，你可能会注意到运行 `cos` 耗时 6us 实在太长了！若再放大，你会看到其中实际上有五个粉色的 "\[untraced\]" 单元格。若以 root 重新运行 magic-trace 并传入 `-trace-include-kernel`，就能看到它们的堆栈跟踪。它们是页错误（page fault）处理程序！演示程序实际上调用了 `cos` 两次。若在 6us 的 `cos` 调用末尾附近再放大，你会看到第二次调用耗时*远*更少且不会发生页错误。 -# How to use it +# 使用方法 -magic-trace continuously records control flow into a ring buffer. Upon some sort of trigger, it takes a snapshot of that buffer and reconstructs call stacks. +magic-trace 将持续把控制流记录到环形缓冲区。在某种触发条件下，它对缓冲区拍快照并重建调用栈。 -There are two ways to take a snapshot: +有两种拍快照的方式： -We just did this one: Ctrl+C magic-trace. If magic-trace terminates without already having taken a snapshot, it takes a snapshot of the end of the program. +我们刚才做的就是其中一种：Ctrl+C 结束 magic-trace。若 magic-trace 在未拍过快照的情况下终止，会对程序末尾拍一张快照。 -You can also trigger snapshots when the application calls a function. To do so, pass magic-trace -the `-trigger` flag. +你也可以在应用调用某个函数时触发快照。做法是向 magic-trace 传入 `-trigger` 标志。 -- `-trigger '?'` brings up a fuzzy-finding selector that lets you choose from all - symbols in your executable, -- `-trigger SYMBOL` selects a specific, fully mangled, symbol you know ahead of time, and -- `-trigger .` selects the default symbol `magic_trace_stop_indicator`. +- `-trigger '?'` 会弹出模糊查找选择器，让你从可执行文件中的所有符号里选择， +- `-trigger SYMBOL` 选择你事先知道的某个具体、完整修饰（mangled）符号，以及 +- `-trigger .` 选择默认符号 `magic_trace_stop_indicator`。 -Stop indicators are powerful. Here are some ideas for where you might want to place one: +停止指示器（stop indicator）很强大。以下是一些你可能想放置它的场景： -- If you're using an asynchronous runtime, any time a scheduler cycle takes too long. -- In a server, when a request takes a surprisingly long time. -- After the garbage collector runs, to see what it's doing and what it interrupted. -- After a compiler pass has completed. +- 若使用异步运行时，可在调度器周期耗时过长时放置。 +- 在服务器中，当某个请求耗时出奇地长时。 +- 垃圾回收器运行之后，查看它在做什么以及它打断了什么。 +- 某个编译器 pass 完成之后。 -You may leave the stop indicator in production code. It doesn't need to do anything in particular, magic-trace just needs the name. It is just an empty, but not inlined, function. It will cost ~10us to call, but *only when magic-trace actually uses it to take a snapshot*. +你可以把停止指示器留在生产代码中。它不必执行任何特定操作，magic-trace 只需要函数名。它只是一个空函数，但不会被内联。调用它大约耗费 ~10us，但*仅在 magic-trace 实际用它拍快照时*才会产生该开销。 -# Documentation +# 文档 -More documentation is available on [the magic-trace wiki](https://github.com/janestreet/magic-trace/wiki). +更多文档可在 [magic-trace wiki](https://github.com/janestreet/magic-trace/wiki). 上查阅。 -# Discussion +# 讨论 -Join us [on Discord](https://discord.gg/vkzPYeZ292) to chat synchronously, or the [GitHub discussion group](https://github.com/janestreet/magic-trace/discussions) to do so asynchronously. +加入我们的 [Discord](https://discord.gg/vkzPYeZ292) 进行实时交流，或前往 [GitHub 讨论组](https://github.com/janestreet/magic-trace/discussions) 进行异步讨论。 -# Contributing +# 贡献 -If you'd like to contribute: +如果你想贡献代码： -1. [read the build instructions](https://github.com/janestreet/magic-trace/wiki/Build-instructions), -1. [set up your editor](https://ocaml.org/learn/tutorials/up_and_running.html#Editor-support-for-OCaml), -1. [take a quick tour through the codebase](https://github.com/janestreet/magic-trace/wiki/A-quick-tour-of-the-codebase), then -1. [hit up the issue tracker](https://github.com/janestreet/magic-trace/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for a good starter project. +1. [阅读构建说明](https://github.com/janestreet/magic-trace/wiki/Build-instructions), +1. [配置你的编辑器](https://ocaml.org/learn/tutorials/up_and_running.html#Editor-support-for-OCaml), +1. [快速浏览代码库](https://github.com/janestreet/magic-trace/wiki/A-quick-tour-of-the-codebase),，然后 +1. [查看 issue 跟踪器](https://github.com/janestreet/magic-trace/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 寻找合适的入门项目。 -# Privacy policy +# 隐私政策 -magic-trace does not send your code or derivatives of your code (including traces) anywhere. +magic-trace 不会将你的代码或其衍生内容（包括 traces）发送到任何地方。 -[magic-trace.org](https://magic-trace.org) is a [lightly modified fork of Perfetto](https://github.com/janestreet/magic-trace/wiki/About-the-UI), and runs entirely in your browser. As far as we can tell, it does not send your trace anywhere. If you're worried about that changing one day, [set up your own local copy of the Perfetto UI](https://github.com/janestreet/magic-trace/wiki/Setting-up-a-local-copy-of-the-UI) and use that instead. +[magic-trace.org](https://magic-trace.org) 是 [Perfetto](https://github.com/janestreet/magic-trace/wiki/About-the-UI), 的轻度修改 fork，完全在浏览器中运行。据我们所知，它不会将 trace 发送到任何地方。如果你担心这一点日后可能改变，可以 [搭建本地 Perfetto UI 副本](https://github.com/janestreet/magic-trace/wiki/Setting-up-a-local-copy-of-the-UI) 并使用它。 -# Acknowledgements +# 致谢 -[Tristan Hume](https://github.com/trishume) is the original author of magic-trace. He wrote it while working at [Jane Street](https://www.janestreet.com/join-jane-street/), who currently maintains it. +[Tristan Hume](https://github.com/trishume) 是 magic-trace 的原始作者。他在 [Jane Street](https://www.janestreet.com/join-jane-street/), 工作期间编写了该项目，Jane Street 目前负责维护。 -Intel PT is the foundational technology upon which magic-trace rests. We'd like to thank the people at Intel for their years-long efforts to make it available, despite its slow uptake in the greater software community. +Intel PT（Intel Processor Trace）是 magic-trace 所依赖的基础技术。我们要感谢 Intel 的同仁多年来为使其可用所做的努力，尽管它在更广泛的软件社区中普及缓慢。 -magic-trace would not be possible without `perf`s extensive support for Intel PT. `perf` does most of the work in interpreting Intel PT's output, and magic-trace likely wouldn't exist were it not for their efforts. Thank you, `perf` developers. +如果没有 `perf` 对 Intel PT 的广泛支持，magic-trace 就不可能存在。`perf` 承担了大部分解读 Intel PT 输出数据的工作，若没有他们的努力，magic-trace 很可能根本不会问世。感谢你们，`perf` 开发者。 -[magic-trace.org](https://magic-trace.org) is a fork of [Perfetto](https://github.com/janestreet/magic-trace/wiki/About-the-UI), with minor modifications. We'd like to thank the people at Google responsible for it. It's a high quality codebase that solves a hard problem well. +[magic-trace.org](https://magic-trace.org) 是 [Perfetto](https://github.com/janestreet/magic-trace/wiki/About-the-UI), 的 fork，仅做了少量修改。我们要感谢 Google 负责该项目的同仁。这是一个高质量的代码库，很好地解决了一个难题。 -The ideas behind magic-trace are in no way unique. We've written down a list of [prior art](https://github.com/janestreet/magic-trace/wiki/Prior-art) that has influenced its design. +magic-trace 背后的思想绝非独创。我们整理了一份 [先前工作](https://github.com/janestreet/magic-trace/wiki/Prior-art) 列表，记录了影响其设计的内容。