I've released peak-mem, a simple command-line tool that tracks the peak memory usage of any process.
The project is hosted on sourcehut: https://sr.ht/~charmitro/peak-mem/.
While a mirror can be found in Github https://github.com/charmitro/peak-mem.
Why Another Memory Monitor?
I created peak-mem while analyzing a multi-threaded program's cache implementation. I needed to understand the peak memory usage across all threads and processes. I wanted something that:
- Works like the time command - just prefix your command
- Tracks the entire process tree by default
- Provides both human-readable and machine-parseable output
- Runs on Linux and macOS (with hope for Windows and FREEBSD)
Getting Started
Installation is straightforward with Cargo:
cargo install --git https://git.sr.ht/~charmitro/peak-mem
Then use it like you would the time command:
peak-mem -- cargo check
You'll see output like:
Command: cargo check
Peak memory usage: 376.9 MiB (RSS) / 1.2 GiB (VSZ)
Exit code: 0
Duration: 1.0s
Key Features
Multiple Output Formats: Choose between human-readable (default), JSON, CSV, or quiet mode for scripting:
peak-mem --json -- ls -la
peak-mem --csv -- echo test
peak-mem --quiet -- echo test # outputs only RSS in bytes
Real-time Monitoring: Watch memory usage as it happens with the --watch flag:
peak-mem --watch -- sleep 3
Current RSS: 900.0 KiB | Peak RSS: 900.0 KiB
Current VSZ: 5.3 MiB | Peak VSZ: 5.3 MiB
Memory Thresholds: Set alerts for when memory usage exceeds limits:
peak-mem --threshold 10M -- cargo check
⚠️ THRESHOLD EXCEEDED
Process Tree Tracking: By default, peak-mem tracks all child processes. See the full breakdown with --verbose:
peak-mem --verbose -- sh -c "sleep 0.1 & sleep 0.1 & wait"
Process Tree: (3 processes monitored)
sh (PID: 1547929) - Peak: 900.0 KiB
sleep (PID: 1547932) - Peak: 904.0 KiB
sleep (PID: 1547931) - Peak: 892.0 KiB
This shows each process in the tree with its individual peak usage - perfect for understanding where memory is actually being consumed.
Timeline Recording: For detailed analysis, record a memory timeline:
peak-mem --timeline memory.json -- ./app
How It Works
peak-mem spawns your process and samples its memory usage every 100ms (configurable). It tracks both RSS (Resident Set Size - actual RAM used) and VSZ (Virtual Size - total address space). The tool properly forwards signals, so Ctrl+C works as expected.
On Linux, it reads from /proc for minimal overhead. On macOS, it uses the native proc_pidinfo API. The sampling approach means very brief memory spikes might be missed, but the overhead is negligible - typically less than 1% CPU.
Use Cases
I've found peak-mem particularly useful for:
- Performance regression testing: Track memory usage over time
- Development: Quickly check memory impact of changes
Contributing
Send patches to: ~charmitro/peak-mem-devel@lists.sr.ht
Discuss at: https://lists.sr.ht/~charmitro/peak-mem-discuss
Contributions are welcome! The codebase is written in Rust with a focus on simplicity and correctness. Platform support for Windows and FreeBSD would be particularly appreciated.
The tool is MIT licensed.