# How magic-trace Distinguishes Between Intel Processor Trace and 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.

- Repository: [Jane Street/magic-trace](https://github.com/janestreet/magic-trace)
- Tags: internals
- Published: 2026-05-24

---

**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`](https://github.com/janestreet/magic-trace/blob/main/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.

```ocaml
(* 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`](https://github.com/janestreet/magic-trace/blob/main/src/collection_mode.ml). This type explicitly enumerates the two supported tracing approaches:

```ocaml
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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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:

```bash
magic-trace snapshot --exe ./my_program

```

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

```bash
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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/src/collection_mode.ml), while the command-line parsing that sets the mode occurs in [`src/bin/magic_trace_bin.ml`](https://github.com/janestreet/magic-trace/blob/main/src/bin/magic_trace_bin.ml). The actual execution path selection happens in [`src/perf_tool_backend.ml`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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.