# Timer Resolution Options in magic-trace: Low, Normal, High, Sample, and Custom

> 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.

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

---

**magic-trace provides five timer resolution options—Low, Normal, High, Sample, and Custom—that control the granularity of Intel Processor Trace (PT) and hardware sampling configurations through the `-timer-resolution` CLI flag.**

The `janestreet/magic-trace` tracer captures execution traces using Intel PT and CPU performance counters. Choosing the right **timer resolution** lets you balance timing precision against collection overhead, with each option mapping to specific `perf` event strings defined in the OCaml source.

## The Timer Resolution Type Definition

The available options are encoded in [`src/timer_resolution.ml`](https://github.com/janestreet/magic-trace/blob/main/src/timer_resolution.ml) as the variant type `Timer_resolution.t`. This type drives how magic-trace builds the underlying `perf` command:

```ocaml
type t =
  | Low
  | Normal
  | High
  | Sample of { freq : int }
  | Custom of {
      cyc         : bool option;
      cyc_thresh  : int option;
      mtc         : bool option;
      mtc_period  : int option;
      noretcomp   : bool option;
      psb_period  : int option;
    }

```

The `-timer-resolution` flag is parsed in the same file (lines 21–26) and defaults to `Normal` when not specified.

## The Five Timer Resolution Options Explained

### Low (Minimal Overhead)

**Low** provides the coarsest timing granularity, ideal for long-running traces where overhead must stay minimal.

- **Intel PT config**: Empty string (no special configuration)
- **Cycles config**: `"freq=1000"` (approximately 1 kHz sampling)

If the target machine lacks Intel PT support, magic-trace automatically falls back to this mode and emits a warning.

### Normal (Default Balance)

**Normal** is the default resolution, offering a practical balance between precision and performance.

- **Intel PT config**: `"cyc=1,cyc_thresh=1,mtc_period=0"`
- **Cycles config**: `"freq=10000"` (approximately 10 kHz sampling)

This mode enables cycle-accurate timestamps without the maximum overhead of High resolution.

### High (Maximum Precision)

**High** utilizes the finest granularity your CPU supports, approximately 10 nanoseconds per packet.

- **Intel PT config**: `"cyc=1,cyc_thresh=1,mtc_period=0,noretcomp=1"`
- **Cycles config**: `"freq=<max-sampling-frequency>"` (highest available rate)

The addition of `noretcomp=1` suppresses Return Compression to ensure every branch is recorded with full timing data.

### Sample (Explicit Sampling Frequency)

**Sample** is available only when the collection mode is `Stacktrace_sampling`. It accepts a custom frequency in Hertz.

- **Input**: `Sample {freq = 5000}` for 5 kHz sampling
- **Cycles config**: `"freq=<freq>"` where `<freq>` is your specified value

This option is ignored for Intel PT–only traces and is handled separately in the sampling backend.

### Custom (Full Configuration Control)

**Custom** grants complete control over Intel PT packet generation fields. You can set any combination of `cyc`, `cyc_thresh`, `mtc`, `mtc_period`, `noretcomp`, and `psb_period`.

- **Requirement**: Intel PT must be available; cannot be combined with sampling mode
- **Output**: Assembled config string (e.g., `"cyc=1,mtc=1,psb_period=5000"`)

Use this when you need specific packet synchronization boundaries or threshold behaviors not covered by the preset modes.

## How Resolution Maps to perf Commands

The conversion from OCaml type to `perf` event string happens in [`src/perf_tool_backend.ml`](https://github.com/janestreet/magic-trace/blob/main/src/perf_tool_backend.ml):

- **`perf_intel_pt_config_of_timer_resolution`** (lines 49–71): Translates `Low`, `Normal`, `High`, and `Custom` into Intel PT configuration strings.
- **`perf_cycles_config_of_timer_resolution`** (lines 74–80): Generates the cycles event configuration for sampling modes.

If `perf_intel_pt_config_of_timer_resolution` detects missing Intel PT capabilities (lines 41–47), it silently downgrades the request to `Low` to ensure the trace can still execute.

## Practical Usage Examples

Select your resolution via the `-timer-resolution` flag:

```bash

# Minimal overhead for long traces

magic-trace record -timer-resolution Low ./my_program

# Default precision (10 kHz)

magic-trace record -timer-resolution Normal ./my_program

# Maximum hardware precision

magic-trace record -timer-resolution High ./my_program

# Custom sampling at 20 kHz (requires -sampling flag)

magic-trace record \
  -timer-resolution 'Sample {freq = 20000}' \
  -sampling ./my_program

# Fine-grained Intel PT control

magic-trace record \
  -timer-resolution 'Custom {cyc = Some true; cyc_thresh = Some 2; mtc = Some true; \
                     mtc_period = Some 0; noretcomp = None; psb_period = Some 1000}' \
  ./my_program

```

Programmatically, construct the variants in OCaml:

```ocaml
let low_res = Timer_resolution.Low
let custom_res = Timer_resolution.Custom {
    cyc = Some true;
    cyc_thresh = Some 1;
    mtc = Some true;
    mtc_period = Some 0;
    noretcomp = None;
    psb_period = Some 500;
  }

```

## Summary

- **Low** (`freq=1000`): Minimal overhead, coarse timing, fallback when Intel PT is unavailable.
- **Normal** (`freq=10000`, `cyc=1`): Default balance of precision and performance.
- **High** (`freq=max`, `noretcomp=1`): Finest hardware-supported granularity (~10 ns).
- **Sample** (`freq=custom`): Only for `Stacktrace_sampling` mode; accepts Hz values.
- **Custom**: Full control over Intel PT fields via the variant record fields.

Key implementation files include [`src/timer_resolution.ml`](https://github.com/janestreet/magic-trace/blob/main/src/timer_resolution.ml) for type definitions and [`src/perf_tool_backend.ml`](https://github.com/janestreet/magic-trace/blob/main/src/perf_tool_backend.ml) for `perf` command generation.

## Frequently Asked Questions

### What is the default timer resolution in magic-trace?

**Normal** is the default resolution when you do not provide the `-timer-resolution` flag. It configures Intel PT with cycle-accurate timestamps at 10 kHz sampling, providing sufficient detail for most performance analysis tasks without excessive overhead.

### Can I use Custom resolution with Stacktrace sampling?

No. The **Custom** resolution is exclusively for Intel PT–based collection and cannot be combined with the `Stacktrace_sampling` mode. If you need custom sampling frequencies in sampling mode, use the **Sample** option instead, which accepts a specific frequency in Hertz.

### Why does High resolution disable return compression?

**High** resolution sets `noretcomp=1` in the Intel PT configuration to disable Return Compression. This ensures that every branch target is emitted as a separate packet with full timing information, eliminating the compression artifacts that can obscure precise timing analysis at sub-microsecond scales.

### What happens if my CPU doesn't support Intel PT?

If the hardware lacks Intel PT capabilities, magic-trace automatically falls back to **Low** resolution and issues a warning. In this fallback state, the tracer relies solely on the cycles event configured at 1 kHz, ensuring the trace can still complete even on older or restricted hardware.