magic-trace
github.com/janestreet/magic-trace- Category
- Developer Tools
- Rank
- No. 323Tools index
- Pricing
- Open Source
- Platform
- cli
- Type
- TOOL
- Builder
- janestreet
- GitHub
- 6.3k stars
- Latest release
- v1.2.4
- Date
About
A high-resolution process tracing tool that captures every function call with ~40ns precision using Intel Processor Trace. Unlike traditional sampling profilers, it records complete control flow history leading up to specific events, making it easier to debug performance issues and understand what code is actually doing.
What it does
magic-trace watches a running program, keeps recent execution history in a circular buffer, then freezes that history on demand or when a chosen symbol runs. It reconstructs the captured activity as call stacks and produces a trace you inspect in an interactive browser timeline.
Why it's ranked here
This is a compelling specialist debugger because it makes rare slow requests, crashes, scheduler stalls, garbage collection, and compiler phases inspectable around the moment that matters. Its focused capture model and browser visualization are practical, but strict hardware and operating system requirements sharply limit where teams can deploy it.
What's good
It attaches without requiring application changes and offers manual or symbol-based capture. The fuzzy symbol selector reduces setup friction. Configurable recent history preserves context before an event, while timeline zooming, measurement, flags, optional kernel stacks, and inline-frame symbolization help turn unexplained latency into concrete hypotheses.
Tradeoffs
It targets Linux on recent Intel processors, with Skylake or later recommended, and most virtual machines are unsupported. Reported tracing overhead is 2% to 10%. The usual history window is about 10 milliseconds. Kernel detail requires elevated privileges, and an active stop indicator costs about 10 microseconds when captured.
How to use it well
Use it when a Linux service or runtime has rare, event-shaped failures that sampling might miss. Attach to production-like processes, trigger on unusually slow work or runtime pauses, then inspect the preceding timeline and refine hypotheses. Keep a sampling profiler for broad, long-duration performance attribution across workloads and unsupported platforms.
Technical notes+
The Makefile builds and installs the OCaml project through Dune. src/ptrace_stubs.c, src/boot_time_stubs.c, and src/breakpoint_stubs.c bridge OCaml to Linux ptrace, perf events, timestamp conversion, and hardware breakpoints. src/llvm_symbolizer_stubs.cpp uses LLVM to recover inline frames and substitutes shorter names for mangled OCaml symbols. direct_backend/manual_perf_stubs.c configures Intel PT through perf_event_open, maps data and auxiliary ring buffers, and snapshots them. direct_backend/decoding_stubs.c decodes packets with libipt and sideband data into call, return, jump, trace-boundary, and error events. README.md describes a separate browser-based Perfetto fork for viewing the generated compressed trace.
Observed
- Primary implementation
- OCaml project built with Dune, with substantial C and C++ native stubs
- Install surface
- Prebuilt executable, Debian package, or Dune install target
- Interface
- Command-line tool that attaches to a process and emits a compressed trace for browser viewing
- Platform support
- Linux on Intel processors, with Skylake or later recommended; most virtual machines are unsupported
- Language examples
- Repository demos exercise C, C++, Go, and JavaScript programs
Read from README.md, Makefile, src/perf_utils.h, src/ptrace_stubs.c, src/perf_dlfilter.c, src/perf_dlfilter.h, src/boot_time_stubs.c, src/breakpoint_stubs.c, src/llvm_symbolizer_stubs.cpp, demo/demo.c, demo/demo.go, demo/demo.js, demo/demo.cpp, direct_backend/decoding_stubs.c, direct_backend/manual_perf_stubs.c.
What it can do
Trace process execution with high-resolution timing
Running process or application → High-resolution execution trace with ~40ns precision
Capture complete function call history
Process execution flow → Complete record of all function calls and control flow
Record control flow leading to specific events
Target event or performance issue → Complete execution history leading up to the event
Generate interactive timeline visualization
Process trace data → Interactive visual timeline of call stacks
Profile application performance without code changes
Any existing application or process → Performance trace data with 2%-10% overhead
Display call stack execution patterns
Traced process data → Visual representation of call stack patterns and timing
Tags
Media
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.