https://github.com/charmitro/peak-mem

A lightweight, cross-platform memory usage monitor for any process. Mirror of https://sr.ht/~charmitro/peak-mem/
https://github.com/charmitro/peak-mem

cli memory monitoring performance profiler

Last synced: 9 months ago
JSON representation

A lightweight, cross-platform memory usage monitor for any process. Mirror of https://sr.ht/~charmitro/peak-mem/

• Host: GitHub
• URL: https://github.com/charmitro/peak-mem
• Owner: charmitro
• License: mit
• Created: 2025-05-24T12:39:22.000Z (about 1 year ago)
• Default Branch: master
• Last Pushed: 2025-07-13T17:35:55.000Z (11 months ago)
• Last Synced: 2025-07-13T19:30:23.841Z (11 months ago)
• Topics: cli, memory, monitoring, performance, profiler
• Language: Rust
• Homepage: https://blog.charmitro.gr/blog/peak-mem-a-lightweight-memory-usage-monitor/
• Size: 101 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 4
• Metadata Files:
  • Readme: README
  • License: LICENSE

Awesome Lists containing this project

README

          
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