How magic-trace Distinguishes Between Intel Processor Trace and Sampling Mode

magic-trace distinguishes between Intel Processor Trace and sampling mode through the Collection_mode.t type variant, which is set by the snapshot or sample sub-command and propagated through the codebase to determine whether to invoke perf record -e intel-pt or standard hardware counter sampling.

magic-trace is a high-performance tracing tool developed by Jane Street that supports two fundamentally different data collection mechanisms. Understanding how magic-trace distinguishes between Intel Processor Trace (IPT) and sampling mode requires examining the command-line parsing logic in the OCaml source and the core type definitions that drive the backend implementation.

The Two Collection Modes in magic-trace

magic-trace implements two distinct tracing strategies that leverage different kernel subsystems and hardware features.

Intel Processor Trace Snapshot Mode

Intel Processor Trace (IPT) snapshot mode utilizes the hardware Intel PT feature available in modern x86 processors. In this mode, magic-trace invokes the kernel's perf subsystem with the intel-pt driver to record a complete execution flow snapshot of the traced program. This mode captures every branch and control flow transition with minimal overhead, storing the trace data in a circular buffer until a trigger event occurs.

Sampling Mode

Sampling mode relies on the classic perf sampling infrastructure rather than hardware tracing. The tool periodically collects hardware counter samples (such as CPU cycles) using perf record -e cycles and later decodes these samples into call-stack information. This approach provides statistical profiling data rather than the deterministic execution trace captured by IPT.

Implementation Details: From CLI to Kernel Invocation

The distinction between these modes is encoded early in the program lifecycle and propagated through specific source files that handle command interpretation and backend execution.

Command-Line Parsing in magic_trace_bin.ml

The binary entry point defined in src/bin/magic_trace_bin.ml registers two distinct sub-commands that determine the collection strategy. The Command.group definition creates separate entry points for snapshot and sample, with each sub-command setting a corresponding Collection_mode.t value that flows down the call stack.

(* Conceptual representation of the sub-command registration *)
Command.group ~summary:"..."
  [ "snapshot", snapshot_command  (* Sets Collection_mode.Snapshot *)
  ; "sample",   sample_command    (* Sets Collection_mode.Sampling *)
  ]

The Collection_mode Type Definition

The discriminated union type that enables this distinction is defined in src/collection_mode.ml. This type explicitly enumerates the two supported tracing approaches:

type t =
  | Snapshot   (* Intel PT snapshot mode *)
  | Sampling   (* Perf-sampling mode *)

This algebraic data type ensures that the mode selection is type-safe and exhaustive throughout the codebase, forcing pattern matches to handle both possibilities.

Backend Selection in perf_tool_backend.ml

The src/perf_tool_backend.ml file contains the critical logic that translates the Collection_mode.t value into specific perf command invocations. The run_perf function pattern-matches on the mode to construct the appropriate kernel interface:

• For Snapshot, the backend executes perf record -e intel-pt … to activate the Intel PT hardware tracing
• For Sampling, it executes perf record -e cycles … (or any user-specified hardware event) to enable periodic counter sampling

This pattern match ensures that the hardware-specific IPT driver is only invoked when explicitly requested through the snapshot sub-command.

Trace Entry Point Initialization

The high-level src/trace.ml module serves as the entry point for running programs under magic-trace. This module receives the chosen Collection_mode.t value and forwards it to the backend. The file's opening comment explicitly references running "under Intel Processor Trace in Snapshot mode", confirming that this distinction is maintained at the highest level of the application architecture.

Practical Usage Examples

To run magic-trace in Intel Processor Trace mode, use the snapshot sub-command:

magic-trace snapshot --exe ./my_program

To run in sampling mode instead, use the sample sub-command:

magic-trace sample --exe ./my_program

Both commands invoke the same magic-trace binary, but the sub-command selection determines the Collection_mode.t value that drives the backend to use either hardware tracing or statistical sampling.

Summary

• magic-trace distinguishes tracing modes through the Collection_mode.t type defined in src/collection_mode.ml, which has two variants: Snapshot and Sampling.
• The mode is selected via sub-commands (snapshot vs sample) parsed in src/bin/magic_trace_bin.ml and mapped to the corresponding type variant.
• Intel Processor Trace mode uses perf record -e intel-pt to capture complete execution traces via hardware PT features.
• Sampling mode uses perf record -e cycles to collect periodic hardware counter samples for statistical profiling.
• The backend logic in src/perf_tool_backend.ml pattern-matches on the Collection_mode.t to construct the appropriate perf invocation.

Frequently Asked Questions

What is the difference between snapshot mode and sampling mode in magic-trace?

Snapshot mode utilizes Intel Processor Trace hardware to capture a complete, deterministic record of every branch and control flow transition in the traced program. Sampling mode uses traditional perf infrastructure to periodically sample hardware counters (like CPU cycles) and reconstruct call stacks statistically, resulting in lower overhead but less precise execution data.

How do I select Intel Processor Trace mode when running magic-trace?

Use the snapshot sub-command rather than sample. For example: magic-trace snapshot --exe ./my_program. This sets the Collection_mode.Snapshot variant, which causes the backend in src/perf_tool_backend.ml to invoke perf with the intel-pt event.

Which source file defines the mode selection logic in magic-trace?

The core type definition resides in src/collection_mode.ml, while the command-line parsing that sets the mode occurs in src/bin/magic_trace_bin.ml. The actual execution path selection happens in src/perf_tool_backend.ml where the mode is pattern-matched to determine which perf arguments to use.

Does magic-trace use different perf commands for each tracing mode?

Yes. According to the source in src/perf_tool_backend.ml, snapshot mode executes perf record -e intel-pt to access the Intel PT hardware tracing driver, while sampling mode executes perf record -e cycles (or similar hardware events) to enable the standard perf sampling subsystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}