peak-mem

peak-mem

Monitor peak memory usage of processes.

INSTALLATION

Install from a local path:
cargo install --path .

Or install directly from https://crates.io/crates/peak-mem:
cargo install peak-mem

USAGE

peak-mem [OPTIONS] -- COMMAND [ARGS...]

OPTIONS

-h, --help              Show help
-V, --version           Show version
-j, --json              Output JSON
-c, --csv               Output CSV
-q, --quiet             Output only RSS in bytes
-v, --verbose           Show process breakdown
-w, --watch             Show real-time usage
-t, --threshold SIZE    Set memory threshold
--no-children           Don't track child processes
--timeline FILE         Record timeline
--interval MS           Sampling interval (default: 100)

Memory Regression Detection:
--save-baseline NAME    Save current run as baseline
--compare-baseline NAME Compare against saved baseline
--regression-threshold % Memory increase threshold (default: 10%)
--baseline-dir DIR      Baseline storage directory
--list-baselines        List all saved baselines
--delete-baseline NAME  Delete a saved baseline

EXAMPLES

Basic usage:
peak-mem -- cargo build

JSON output:
peak-mem --json -- ./myapp

Set 1GB threshold:
peak-mem --threshold 1G -- ./test

Memory regression detection:
# Save a baseline
peak-mem --save-baseline v1.0 -- ./myapp

# Compare against baseline
peak-mem --compare-baseline v1.0 -- ./myapp

# Use stricter threshold (5% increase = regression)
peak-mem --compare-baseline v1.0 --regression-threshold 5 -- ./myapp

# List and manage baselines
peak-mem --list-baselines
peak-mem --delete-baseline v1.0

BUILDING

cargo build --release

INSTALLING MANPAGE

System-wide installation:
sudo install -Dm644 man/man1/peak-mem.1 /usr/share/man/man1/peak-mem.1

Local installation:
install -Dm644 man/man1/peak-mem.1 ~/.local/share/man/man1/peak-mem.1

View the manpage:
man peak-mem

MEMORY REGRESSION DETECTION

Peak-mem can save memory usage baselines and compare subsequent runs
to detect memory regressions. This is useful for:

- CI/CD pipelines to catch memory regressions
- Comparing memory usage before/after optimizations
- Tracking memory usage across releases

Baselines are stored in ~/.cache/peak-mem/baselines/ by default.
When comparing, peak-mem will:

1. Report percentage changes in RSS, VSZ, and duration
2. Exit with code 1 if RSS increases exceed the threshold
3. Support multiple output formats (human, JSON, CSV, quiet)

PLATFORM SUPPORT

Linux    - Implemented via /proc
macOS    - Implemented via proc_pidinfo
FreeBSD  - Not implemented
Windows  - Not implemented

LICENSE

MIT