Output Format Options¶

-j, --json

Output results in JSON format. Useful for parsing by other tools.

-c, --csv

Output results in CSV format. The output includes headers and is suitable for importing into spreadsheets or data analysis tools.

-q, --quiet

Quiet mode. Only output the peak RSS value in bytes with no formatting. Useful for scripting.

-v, --verbose

Show detailed breakdown including process tree. Displays memory usage for each process in the hierarchy.

Monitoring Options¶

-w, --watch

Display real-time memory usage during execution. Updates the display continuously as the process runs.

-t, --threshold SIZE

Set a memory threshold alert. Accepts values like 512M, 1G, 2GB. The program will indicate if the threshold is exceeded.

--no-children

Don't track child processes. By default, peak-mem monitors the entire process tree.

--timeline FILE

Record detailed memory timeline to the specified file. The timeline includes timestamps and memory values for later analysis.

--interval MS

Set the sampling interval in milliseconds (default: 100). Lower values provide more accurate peak detection but increase overhead.

--units UNIT

Force specific memory units in human-readable output instead of automatic sizing. Supported units: B (bytes), KB (kilobytes), MB (megabytes), GB (gigabytes), KiB (kibibytes), MiB (mebibytes), GiB (gibibytes). This option affects all human-readable output including verbose mode and baseline comparisons.

Baseline Management Options¶

--save-baseline NAME

Save the current run's memory usage as a baseline with the given name. Baselines are stored for future comparison to detect memory regressions.

--compare-baseline NAME

Compare the current run against a previously saved baseline. Reports memory usage changes and indicates if a regression is detected.

--regression-threshold PERCENT

Set the percentage increase in RSS that constitutes a regression (default: 10.0). Only used with --compare-baseline.

--baseline-dir DIR

Directory to store baseline files (default: ~/.cache/peak-mem/baselines).

--list-baselines

List all saved baselines and exit.

--delete-baseline NAME

Delete a saved baseline and exit.

Standard Options¶

-h, --help

Display help message and exit.

-V, --version

Display version information and exit.

Basic Usage¶

Monitor memory usage of a cargo build:

JSON Output¶

Get machine-readable output:

Memory Threshold¶

Alert if memory usage exceeds 1GB:

Real-time Monitoring¶

Watch memory usage as it happens:

Timeline Recording¶

Record detailed timeline for analysis:

Process-only Monitoring¶

Monitor only the main process, ignoring children:

Fixed Memory Units¶

Display memory usage in megabytes:

Combined Options¶

Verbose output with threshold and timeline:

Memory Regression Detection¶

Save a baseline for your application:

Compare against the baseline after changes:

Use stricter regression threshold (5%):

List and manage baselines:

Human-readable (default)¶

Shows peak RSS and VSZ in human-readable units (KB, MB, GB) along with the monitored command and exit status.

JSON Format (-j)¶

Outputs a JSON object containing:

CSV Format (-c)¶

Outputs CSV with headers:

Quiet Format (-q)¶

Outputs only the peak RSS value in bytes as a plain number.

Verbose Format (-v)¶

Shows detailed process tree with individual memory usage for each process, including PIDs and process names.