magic-trace: Intel PT call-stack snapshots for Linux x86 processes

What magic-trace answers that a profiler cannot

A sampling profiler tells you where a process spends time. It cannot tell you the sequence of calls inside a function that finishes in 70 nanoseconds, because the sampler will almost never land inside it. magic-trace is built for that gap. The README describes it as collecting and displaying high-resolution traces of what a process is doing, and lists the use cases its users report: understanding why some production requests are slow while the rest are uninteresting, seeing what code actually does rather than what you assume, and getting a history of what the application was doing before it crashed instead of a single stacktrace at the final instant.

The audience is narrow and specific. You need a Linux machine with an Intel CPU from Skylake or later. The README points to a supported-platforms page and names the constraints that most commonly trip people up: virtual machines are mostly not supported, Intel only, Linux only. Broadwell and newer is technically possible according to the README footnote, but it is not a platform the project regularly tests on and timing resolution degrades to roughly 1 microsecond. There is no macOS build and no ARM build described anywhere in the README.

The claimed overhead is 2% to 10%, linked to a wiki page rather than stated as a measured number in the README itself. That range is the number to quote when someone asks whether it is safe on a production host, and it is also the number to verify yourself before you attach to anything that matters.

The ring buffer, the trigger, and the 10ms window

The mechanism is Intel Processor Trace. The README is explicit that magic-trace uses Intel PT to snapshot a ring buffer of all control flow leading up to a chosen point in time, and that under the hood it uses perf to drive Intel PT. That last point matters for anyone evaluating it: perf is a dependency, not a competitor that magic-trace replaces wholesale.

At runtime magic-trace continuously records control flow into that ring buffer. Nothing is decoded while recording. When a trigger fires, it takes a snapshot of the buffer and reconstructs call stacks from it. The README states the tool traces every function call with roughly 40ns resolution and renders a timeline of call stacks going back a configurable ~10ms. So the unit of analysis is not a sample but a window: everything that executed in the last several milliseconds before the trigger.

There are two triggers. The interactive one is Ctrl+C: if magic-trace terminates without having already taken a snapshot, it snapshots the end of the program. The other is function-based, where you point magic-trace at a function so that when the application calls it, the snapshot is taken. That second mode is what turns the tool from a debugging aid into a targeted instrument, because you can capture the state of the world at the exact call you care about rather than at a moment you happened to press a key.

The comparison the README draws with perf is not about capability. It concedes that perf can drive Intel PT too, but argues that is not how most people use it. The distinction is in the default workflow: sampling call stacks throughout time versus snapshotting all control flow up to a chosen instant. One of the quoted testimonials makes the practical version of this point, describing how working in slices at any zoom level let the author see all the function calls a 70ns function was performing, which sampling had rendered invisible.

Installing magic-trace and taking a first trace

The README gives two install paths, both from the latest release page rather than from a package manager. If you download the prebuilt binary, it needs the executable bit set. If you download the Debian package, it installs with dpkg. After either path, the smoke test is the help flag.

chmod +x magic-trace
sudo dpkg -i magic-trace*.deb
magic-trace -help

The README says that command should bring up some help text. If it does not, the binary is not going to attach to anything, and the most likely cause is the platform constraints from the previous section rather than a broken download.

For a first real trace, the repository ships a demo. The README links to demo/demo.c, describes it as a slightly modified version of the example in man 3 dlopen, and gives the build line. The demo directory also contains variants in C#, C++, Go, JavaScript, OCaml and Java, so the same exercise is available in other languages if C is not your stack.

gcc demo.c -ldl -o demo
./demo

Leave that running in one terminal. In another, attach by pid and then interrupt with Ctrl+C after a couple of seconds. The README states this writes trace.fxt.gz into the working directory.

magic-trace attach -pid $(pidof demo)

Open magic-trace.org, click Open trace file in the top left, and load the file. The viewer's controls are keyboard-driven: W zooms in at the cursor, S zooms out, A and D move left and right, and the scroll wheel moves the viewport up and down the stack. The README warns that you will need to zoom in a lot before anything useful appears. To measure, click and drag on the white space around the call stacks, and plant flags by clicking in the timeline along the top.

The worked example in the README is worth reproducing because it shows the tool doing something a profiler would not. Measuring the cos call in the demo gives roughly 5.7 microseconds on the author's screen, which is far too long for a cosine. Zooming further reveals five pink [untraced] cells. Re-running with root and -trace-include-kernel fills those in as page fault handlers. The demo calls cos twice, and the second call is much faster and does not fault. That is the whole value proposition in one trace: the first call paid for faulting in a page, the second did not.

Where magic-trace stops being the right tool

The platform constraints are the first hard limit and they are not negotiable through configuration. Linux only, Intel only, Skylake or later, and virtual machines mostly unsupported. If your production fleet runs on AMD EPYC, or on ARM, or on macOS laptops, or inside a VM, magic-trace is not a slow option or a degraded option. It is simply not available, and the README's supported-platforms page is where you confirm that before spending time on it.

The second limit is the window. The README describes a timeline going back a configurable ~10ms. That is the right shape for a request handler or a crash you can reproduce on demand, and the wrong shape for anything whose interesting behaviour unfolds over seconds. A slow batch job, a garbage collection pause that builds over minutes, a leak that manifests after an hour of traffic: none of those fit into a 10ms snapshot, and no flag in the README changes that.

The third is the trigger itself. Function-based capture requires that you know which function to name in advance. That is fine when you already suspect the call site. It is useless in the exploratory case where you do not yet know which function is involved, and there the Ctrl+C path is what you have, which means you are back to catching the moment by hand. The README frames the tool as excelling at hypothesis generation, and that framing is honest: it generates hypotheses well, but it still needs a hypothesis about where to look, or a human with a keyboard.

One more practical point. Kernel stacks appear as [untraced] cells unless you run with root and pass -trace-include-kernel, as the README's page-fault example shows. If your hypothesis involves syscalls, page faults or scheduler behaviour, the default trace will show you gaps exactly where you wanted information, and you need elevated privileges to fill them.

magic-trace vs perf and vs Perfetto

perf is the obvious comparison and the README makes it directly. The difference is the recording model, not the underlying hardware facility. Both can drive Intel PT. A conventional perf workflow samples call stacks at intervals and aggregates them, which answers where time went across a run. magic-trace snapshots all control flow up to a chosen instant and reconstructs the call tree for that window, which answers what happened immediately before this moment. The README acknowledges perf can do the snapshot approach but argues most people do not use it that way. If your team already has a perf-based Intel PT workflow tuned to this, magic-trace is a different interface over similar plumbing rather than a new capability.

Perfetto is the other name that comes up. It is a tracing framework with its own trace format, its own collection tooling and a browser-based UI, and it is not limited to Intel PT or to Linux x86. The practical difference for an adopter is that Perfetto expects instrumentation or platform trace sources feeding its format, whereas magic-trace produces trace.fxt.gz from Intel PT without application changes and expects you to open it at magic-trace.org. If you need traces from Android, from a browser, or from a system where Intel PT is unavailable, Perfetto is the one that will run. If you need the last 10ms of every function call in a Linux x86 process with no code changes, that is magic-trace's specific shape and Perfetto would require you to build the equivalent yourself.

The honest summary is that these tools are not ranked. The README's own framing, echoed in the quoted testimonial from someone who uses perf heavily, is that both give perspectives the other does not.

Maintenance, building from source, and the MIT licence

The repository is not archived, and the last push was on 2026-08-19. The most recent tagged release is v1.2.4 from 2025-04-13, with v1.2.3 and v1.2.2 before it in June 2024. So the cadence visible in the release history is a release roughly once a year, with commit activity continuing between releases. That is a slow-moving project, and the gap between the last release and the last push is worth knowing if you are pinning to a tag rather than tracking master.

Building from source is a dune project, and the Makefile is thin. The default target runs dune build, install runs dune install with an optional PREFIX, and there are uninstall, reinstall and clean targets. A PROFILE variable is passed through to dune build. The repository also carries a magic-trace.opam file and a magic-trace.opam.locked file, so the OCaml dependency set is pinned in the repository. The presence of .ocamlformat, a dune-project file and a CONTRIBUTING.md suggests the project has its own formatting and contribution conventions rather than accepting arbitrary patches.

Upgrade cost is the thing to weigh. Because the runtime depends on Intel PT through perf, a kernel or perf change on your host can affect whether tracing works at all, independent of which magic-trace version you run. Pinning a release binary does not insulate you from that. It only fixes the CLI and decoder side.

The licence is MIT, per the repository's LICENSE.md and the licence badge in the README. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained, and it disclaims warranty. That is a general description of the licence text, not advice about your situation. If you are redistributing a modified magic-trace inside a product, the obligation that matters is preserving the notice, and your legal team should read LICENSE.md rather than take this paragraph as a conclusion.

Editorial conclusion

Adopt magic-trace when you have a Linux x86 machine with Intel Skylake or later and a question that a sampled stack cannot answer, such as what a 70ns function did internally. Skip it on AMD, on virtual machines, on ARM, or on macOS, where the README's supported-platforms page rules it out. Before you rely on it, verify three things on your own hardware: that magic-trace -help runs, that attach against the demo binary produces trace.fxt.gz, and that magic-trace.org opens that file, because the browser viewer is a separate component from the CLI.

Frequently asked questions

Official sources

1. janestreet/magic-trace on GitHub
2. License: MIT
3. Project website
4. README
5. Releases