Repolode
Submit
janestreet

janestreet/magic-trace

A Linux profiler that uses Intel Processor Trace to record every function call in a process and display them on an interactive timeline.

View on GitHubWebsite
Stars
6,347
Forks
223
Open issues
73
Last commit
19 days ago

What is it?

magic-trace collects and displays high-resolution traces of what a process is doing. Instead of sampling call stacks at intervals as perf does, it uses Intel Processor Trace to keep a ring buffer of all control flow, then takes a snapshot of that buffer at a chosen moment. The snapshot is reconstructed into an interactive timeline of call stacks covering roughly the last 10 ms by default, with function calls resolved to about 40 ns.

You can attach it to a running process and detach with Ctrl+C to capture the end of the run, or set a trigger so a snapshot is taken whenever a specified function is called. Traces are written as trace.fxt.gz files and opened in the magic-trace.org viewer, which runs in the browser, a fork of Perfetto. The tool does not require application changes and is stated to add 2%-10% overhead.

It requires an Intel CPU from Skylake or later, and runs on Linux only. Most virtual machines are not supported.

Key features

  • 01Records every function call in a process with about 40 ns resolution.
  • 02Uses Intel Processor Trace to snapshot a ring buffer of control flow instead of sampling.
  • 03Attaches to a running process without application changes.
  • 04Triggers snapshots on a chosen function call or on detach.
  • 05Viewer runs in the browser and does not upload traces.

Use cases

  • Finding out why some production requests are slow among many fast ones.
  • Seeing what code actually runs, versus what was assumed, in a hot path.
  • Reviewing the sequence of calls leading up to a crash.
  • Investigating what happens between two points in a long-running program, such as a scheduler cycle or GC pass.

Quick start

  1. 1

    Download the release binary or package from the latest release page

  2. 2

    Make the prebuilt binary executable

    chmod +x magic-trace
  3. 3

    Install the downloaded .deb package

    sudo dpkg -i magic-trace*.deb
  4. 4

    Check the installation by viewing the help text

    magic-trace -help

Things to know

  • Linux only and requires an Intel CPU (Skylake or later).
  • VMs are mostly not supported.

In collections

OpenTelemetry & observability platforms

Topics

#performance-tools#profiling#tracing#intel-pt#linux#debugging#observability#intel#introspection#profile

FAQ

What is magic-trace?
A Linux profiler that uses Intel Processor Trace to record every function call in a process and display them on an interactive timeline. magic-trace collects and displays high-resolution traces of what a process is doing. Instead of sampling call stacks at intervals as perf does, it uses Intel Processor Trace to keep a ring buffer of all control flow, then takes a snapshot of that buffer at a chosen moment. The snapshot is reconstructed into an interactive timeline of call stacks covering roughly the last 10 ms by default, with function calls resolved to about 40 ns.
Is magic-trace free to use? What license does it have?
magic-trace is open source under the MIT license. Check the license terms before using it in commercial products.
Is magic-trace still maintained?
Actively maintained. The last commit to magic-trace was on Oct 19, 2026.
What can I use magic-trace for?
Finding out why some production requests are slow among many fast ones. Seeing what code actually runs, versus what was assumed, in a hot path. Reviewing the sequence of calls leading up to a crash. Investigating what happens between two points in a long-running program, such as a scheduler cycle or GC pass.
How do I install magic-trace?
Download the release binary or package from the latest release page Make the prebuilt binary executable: chmod +x magic-trace Install the downloaded .deb package: sudo dpkg -i magic-trace*.deb Check the installation by viewing the help text: magic-trace -help
Where can I get magic-trace?
The source code and installation instructions are on GitHub: https://github.com/janestreet/magic-trace

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects