# magic-trace | Jane Street | Knowledge Base | Instagit

magic-trace collects and displays high-resolution traces of what a process is doing

GitHub Stars: 6k

Repository: https://github.com/janestreet/magic-trace

---

## Articles

### [Magic-Trace Collection Mode Auto-Detection and Fallback Behavior](/janestreet/magic-trace/magic-trace-collection-mode-auto-detection-fallback)

Explore magic-trace's auto-detection of Intel Processor Trace (PT) and its fallback to stacktrace sampling. Discover how to override collection modes for efficient performance analysis.

- Tags: deep-dive
- Published: 2026-05-24

### [How Magic-Trace Extracts OCaml Exception Information from Debug Symbols](/janestreet/magic-trace/magic-trace-ocaml-exception-info-debug-symbols)

Learn how Magic-Trace extracts OCaml exception information from debug symbols using ELF note sections and address lists to reconstruct exception control flow for effective tracing.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Magic-Trace Manages Multi-Snapshotting with Switch-Output Signals](/janestreet/magic-trace/magic-trace-multi-snapshot-switch-output-signals)

Learn how Magic-Trace achieves multi-snapshotting using switch-output signals. Discover seamless output file rotation with SIGUSR2 without interrupting tracing.

- Tags: internals
- Published: 2026-05-24

### [How to Attach magic-trace to a Running Process: PID vs. fzf Selection Methods](/janestreet/magic-trace/magic-trace-process-attachment-pid-fzf)

Learn to attach magic-trace to running processes using PID or fzf fuzzy selection. Explore efficient debugging methods for your applications.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Trace Running Processes with magic-trace attach: A Complete Guide](/janestreet/magic-trace/magic-trace-trace-running-processes-attach)

Learn to trace running processes with magic trace attach command. Capture Intel Processor Trace data from live Linux processes with trigger options for in depth analysis.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Magic-Trace Controls perf Using ctlfd vs Signals: Implementation Deep Dive](/janestreet/magic-trace/magic-trace-control-perf-ctlfd-vs-signals)

Explore how Magic-Trace expertly manages perf control using ctlfd or signals. Discover the implementation details and benefits of its dynamic kernel version detection for reliable performance tracing.

- Tags: deep-dive
- Published: 2026-05-24

### [magic-trace Debug Info and Symbol Table Requirements: A Complete Guide](/janestreet/magic-trace/magic-trace-requirements-debug-info-symbol-tables)

Understand magic-trace debug info and symbol table needs. Learn how to configure your build for full source code tracing and symbol resolution to avoid raw addresses.

- Tags: how-to-guide
- Published: 2026-05-24

### [How magic-trace Captures Kernel Traces with kcore Support](/janestreet/magic-trace/magic-trace-capture-kernel-traces-kcore-support)

Learn how magic-trace captures kernel traces with kcore support by automatically enabling the --kcore flag for perf record in specific Intel Processor-Trace configurations. Optimize your kernel tracing.

- Tags: how-to-guide
- Published: 2026-05-24

### [How magic-trace perf_dlfilter Resolves Symbols: The Dynamic Linker Filter Mechanism](/janestreet/magic-trace/magic-trace-perf-dlfilter-symbol-resolution)

Understand how magic-trace perf_dlfilter resolves symbols by intercepting perf events and utilizing dl_iterate_phdr for efficient symbol lookup and caching.

- Tags: internals
- Published: 2026-05-24

### [How to Add Custom Events (branch-misses, cache-misses) to magic-trace Traces](/janestreet/magic-trace/magic-trace-add-custom-events-branch-misses-cache-misses)

Learn to add custom perf events like branch-misses and cache-misses to magic-trace traces using the --extra-events command-line option. Enhance your performance analysis today.

- Tags: how-to-guide
- Published: 2026-05-24

### [Magic-Trace Full Execution Mode vs Snapshot Ring Buffer: Key Differences Explained](/janestreet/magic-trace/magic-trace-full-execution-vs-snapshot-ring-buffer)

Understand the key differences between Magic-Trace full execution mode and the snapshot ring buffer. Learn when to use each for efficient system tracing.

- Tags: deep-dive
- Published: 2026-05-24

### [How Magic‑Trace Handles ELF Files and Symbol Resolution](/janestreet/magic-trace/magic-trace-handle-elf-files-symbol-resolution)

Learn how Magic-Trace processes ELF files and resolves symbols. Discover its advanced techniques for address translation and source symbol annotation for precise profiling.

- Tags: how-to-guide
- Published: 2026-05-24

### [Understanding magic-trace Trace Scope: Userspace, Kernel, and Combined Modes](/janestreet/magic-trace/magic-trace-trace-scope-userspace-kernel-combined)

Explore the magic-trace trace scope: understand userspace, kernel, and combined modes to control your tracing. Learn how to include kernel instructions with command-line flags.

- Tags: deep-dive
- Published: 2026-05-24

### [Performance Implications of Magic-Trace's Multi-Snapshot Mode](/janestreet/magic-trace/magic-trace-multi-snapshot-performance)

Discover the performance implications of magic-trace's multi-snapshot mode. Understand the trade-offs between runtime overhead, memory usage, and continuous code path visibility.

- Tags: performance
- Published: 2026-05-24

### [How Magic-Trace Integrates with Perf for Intel PT Decoding](/janestreet/magic-trace/magic-trace-integrate-perf-intel-pt-decoding)

Learn how Magic-Trace integrates with Linux perf to decode Intel PT streams, converting raw hardware data into structured function call events for advanced debugging.

- Tags: how-to-guide
- Published: 2026-05-24

### [Timer Resolution Options in magic-trace: Low, Normal, High, Sample, and Custom](/janestreet/magic-trace/magic-trace-timer-resolution-options)

Explore magic-trace's timer resolution options: Low, Normal, High, Sample, and Custom. Control Intel PT granularity using the -timer-resolution CLI flag for precise performance analysis.

- Tags: deep-dive
- Published: 2026-05-24

### [How to Use Trace Filtering with Start and Stop Symbols in magic-trace](/janestreet/magic-trace/magic-trace-trace-filtering-start-stop-symbols)

Learn to use trace filtering with start and stop symbols in magic-trace. Reduce trace output and analysis complexity by capturing specific execution periods. Master -filter flag.

- Tags: how-to-guide
- Published: 2026-05-24

### [Dwarf vs LBR vs Frame Pointers: Comparing Magic-Trace Callgraph Modes](/janestreet/magic-trace/magic-trace-callgraph-modes-dwarf-last-branch-record-frame-pointers)

Explore Dwarf vs LBR vs Frame Pointers mode in magic-trace. Understand their trade-offs in portability, hardware needs, and runtime overhead for Linux perf samples.

- Tags: comparison
- Published: 2026-05-24

### [How to Configure Snapshot Size in magic-trace for Different Use Cases](/janestreet/magic-trace/magic-trace-configure-snapshot-size)

Configure snapshot size in magic-trace using the -snapshot-size flag to optimize Intel PT auxiliary buffer settings for your specific use case. Learn recommended values.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Magic-Trace Implements Breakpoint-Based Snapshotting Using Linux Perf Hardware Breakpoints](/janestreet/magic-trace/magic-trace-breakpoint-based-snapshotting)

Discover how Magic-Trace uses Linux perf hardware breakpoints to implement efficient breakpoint-based snapshotting, capturing timestamps and register state on function execution.

- Tags: internals
- Published: 2026-05-24

### [Magic-Trace Multi-Thread Recording and Snapshot Buffer Allocation Considerations](/janestreet/magic-trace/magic-trace-multi-thread-recording-buffer-allocation)

Understand magic-trace multi-thread recording and snapshot buffer allocation. Learn how the buffer divides equally for power-of-two page alignment and its impact on look-back windows.

- Tags: deep-dive
- Published: 2026-05-24

### [How magic-trace Distinguishes Between Intel Processor Trace and Sampling Mode](/janestreet/magic-trace/magic-trace-intel-processor-trace-vs-sampling-mode)

Discover how magic-trace differentiates Intel Processor Trace from sampling mode using its Collection_mode.t type variant. Learn how command sub-options determine tracing strategy.

- Tags: internals
- Published: 2026-05-24