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)
    --units UNIT            Force memory units (B, KB, MB, GB, KiB, MiB, GiB)

    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

    Force output in megabytes:
    peak-mem --units MB -- ./myapp

    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  - Implemented via sysinfo
    Windows  - Not implemented

LICENSE

MIT