How to Configure Snapshot Size in magic-trace for Different Use Cases

Use the -snapshot-size flag to set the Intel PT auxiliary buffer size, accepting values like 256K, 4M, or 1G that are automatically rounded to the nearest power-of-two page count; defaults are 4 MiB for root users or 256 KiB otherwise.

magic-trace captures execution traces by taking periodic snapshots of the Intel Processor Trace (PT) auxiliary buffer. The snapshot size determines how much historical execution data is preserved when a snapshot triggers, directly affecting memory consumption, trace granularity, and file size. This guide explains how to tune this parameter using command-line flags and OCaml module internals from the janestreet/magic-trace repository.

The -snapshot-size Flag and Default Behavior

The primary interface for adjusting buffer capacity is the -snapshot-size command-line option, defined in src/perf_tool_backend.ml as a Pow2_pages.t option:

and snapshot_size =
  Pow2_pages.optional_flag
    "-snapshot-size"
    ~doc:
      " Tunes the amount of data captured in a trace. Default: 4M if root or \
       perf_event_paranoid < 0, 256K otherwise. When running with sampling, \
       defaults to 512K, but cannot be changed. For more info: \
       https://magic-trace.org/w/s"

Default values depend on system privileges:

• 4 MiB when running as root or when /proc/sys/kernel/perf_event_paranoid is less than 0
• 256 KiB for unprivileged users under standard kernel configurations

This flag exclusively affects Intel PT collection mode; it is ignored when using stack-trace sampling.

How Sizes Are Parsed and Applied

User-provided sizes are converted to page-aligned values through the Pow2_pages.optional_flag function in src/pow2_pages.mli:

val optional_flag : string -> doc:string -> t option Command.Param.t

The Pow2_pages.create function rounds input values (e.g., 1G, 3M) up or down to the nearest power-of-two number of pages, emitting warnings if the value exceeds available virtual address space (48-bit limit) or falls outside valid ranges.

When collecting traces, the parsed size translates to the -m,<pages> argument passed to perf record. The mapping logic in src/perf_tool_backend.ml (lines 472–480) constructs this parameter:

let snapshot_size_opt =
  match snapshot_size, collection_mode with
  | Some snapshot_size, Intel_processor_trace _ ->
      [ [%string "-m,%{Pow2_pages.num_pages snapshot_size#Int}"] ]
  | Some _, Stacktrace_sampling _ ->
      Core.eprintf "Warning: -snapshot-size is ignored when not running with Intel PT.\n";
      []
  | None, _ -> []

Thus, the specified buffer size directly controls the AUX memory mapping used by the Linux perf subsystem.

Recommended Configurations by Use Case

Choose snapshot dimensions based on profiling objectives and system constraints:

• Low-overhead debugging: Specify -snapshot-size 256K (or omit the flag when running unprivileged) to minimize memory footprint and trace file size for brief investigations.
• Deep execution analysis: Use -snapshot-size 4M or -snapshot-size 8M to capture longer instruction histories before ring-buffer wraparound, revealing complete call chains in complex workflows.
• Production services: Retain the 256 KiB default or set an explicit modest value to prevent kernel memory pressure and reduce pause times in latency-sensitive environments.
• Complete execution capture: Omit -snapshot-size and instead pass -full-execution, which disables the ring buffer entirely and records the entire run (consuming hundreds of megabytes per second).

Interaction with Multi-Snapshot and Sampling Modes

Multi-snapshot recording: When using -multi-snapshot, each trigger event captures a full copy of the AUX buffer. Trace files grow linearly with the number of snapshots taken, so larger snapshot sizes compound file size proportionally.

Stack-trace sampling: In sampling mode, the snapshot size is fixed at 512 KiB and cannot be altered. The backend prints a warning to stderr if you attempt to use -snapshot-size in this configuration.

Full execution mode: The -full-execution boolean flag overrides snapshot sizing entirely by disabling the ring buffer, causing the trace to grow continuously until the process exits.

Practical Configuration Examples

# Default behavior (256 KiB for non-root users)

magic-trace ./my_program

# Large 1 GiB buffer for detailed historical analysis

magic-trace -snapshot-size 1G ./my_program

# Multiple small snapshots for iterative debugging

magic-trace -snapshot-size 256K -multi-snapshot ./my_program

# Complete trace without ring buffer limits

magic-trace -full-execution ./my_program

Summary

• -snapshot-size accepts power-of-two values (e.g., 256K, 4M, 1G) and defaults to 4 MiB for privileged users or 256 KiB for standard users.
• Sizes are rounded to the nearest power-of-two page count via Pow2_pages.create, with warnings emitted for out-of-range values.
• The setting translates to the -m,<pages> argument for perf record in Intel PT mode only; it is ignored under stack-trace sampling.
• Larger buffers provide deeper execution history but increase memory usage and, when combined with -multi-snapshot, significantly expand trace file size.
• Use -full-execution to bypass snapshot limits entirely for comprehensive tracing.

Frequently Asked Questions

What is the default snapshot size in magic-trace?

The default is 4 MiB if the process runs as root or if perf_event_paranoid is less than 0; otherwise, it defaults to 256 KiB. These values are hardcoded in the argument parser within src/perf_tool_backend.ml and represent the AUX buffer capacity before wraparound occurs.

Why is -snapshot-size ignored when I use stack-trace sampling?

Stack-trace sampling mode relies on perf’s built-in buffering mechanisms rather than Intel PT’s AUX ring buffer. When collection_mode is Stacktrace_sampling, the OCaml code explicitly ignores the snapshot size parameter and prints a warning, as the backend uses a fixed 512 KiB buffer that cannot be reconfigured through magic-trace.

How does -multi-snapshot affect trace file size?

Each trigger event in multi-snapshot mode appends a full copy of the AUX buffer to the trace file. Therefore, total file size equals snapshot size × number of triggers. Using an 8 MiB snapshot size with 100 triggers generates approximately 800 MiB of trace data.

Can I set an arbitrary size like 3MB for snapshots?

No. The Pow2_pages module rounds your input to the nearest power-of-two number of system pages (typically 4 KiB). Requesting 3M results in either 2 MiB or 4 MiB depending on rounding direction, and the tool emits a warning indicating the actual value applied.

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