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

> Configure snapshot size in magic-trace using the -snapshot-size flag to optimize Intel PT auxiliary buffer settings for your specific use case. Learn recommended values.

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

---

**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`](https://github.com/janestreet/magic-trace/blob/main/src/perf_tool_backend.ml) as a `Pow2_pages.t option`:

```ocaml
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`:

```ocaml
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`](https://github.com/janestreet/magic-trace/blob/main/src/perf_tool_backend.ml) (lines 472–480) constructs this parameter:

```ocaml
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

```bash

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