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

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 as the variant type Timer_resolution.t. This type drives how magic-trace builds the underlying perf command:

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:

• 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:

# 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:

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 for type definitions and 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.

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