PEAK-MEM(1)

📦
version 0.1.4 · 2 versions
, in ubuntu stonking

💖 peak-mem — the manual, but make it make sense 💖

okay so bestie, this is peak-mem(1), a User Commands girly. She watches your processes eat memory and tells you the biggest bite they ever took. no cap, she's iconic. 🫶

✨ NAME ✨

peak-mem — monitor peak memory usage of processes 💅

🌸 SYNOPSIS 🌸

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

like literally that's it. dash dash, then your command, then whatever args. periodt.

🦋 DESCRIPTION 🦋

peak-mem is a lightweight memory usage monitor that tracks and reports the peak memory usage of a process and its children while they're running. she gives you both real-time monitoring and post-execution reporting, and she does it with minimal overhead. lowkey a queen. 👑

The tool monitors both RSS (Resident Set Size) and VSZ (Virtual Size) memory metrics, tracking the maximum values reached during the lifetime of the monitored process.

so basically: she watches, she remembers the worst moment, she tells you. ✨

🎀 OPTIONS 🎀

💖 Output Format Options 💖

  • -j, --json — output the results in JSON format. perfect if you wanna feed it to other tools, iykyk.
  • -c, --csv — output the results in CSV format. the output includes headers and is suitable for importing into spreadsheets or data analysis tools. spreadsheet girlies rise 🍓
  • -q, --quiet — quiet mode. only outputs the peak RSS value in bytes, with no formatting. useful for scripting. no frills, no commentary, just the number. 🧚
  • -v, --verbose — show a detailed breakdown including the process tree. displays memory usage for each process in the hierarchy. it's giving main character energy for your whole process family tree 🌈

👑 Monitoring Options 👑

  • -w, --watch — display real-time memory usage during execution. the display updates continuously as the process runs. live footage, bestie 📺
  • -t, --threshold SIZE — set a memory threshold alert. accepts values like 512M, 1G, 2GiB. the program will indicate if the threshold is exceeded. check MEMORY UNITS for how unit suffixes are interpreted.
  • --no-children — don't track child processes. by default, peak-mem monitors the entire process tree. this one is for when you only care about the parent. 😤
  • --timeline FILE — record a detailed memory timeline to the specified file. the timeline includes timestamps and memory values for later analysis. receipts, but for memory 📝
  • --interval MS — set the sampling interval in milliseconds (default: 100). lower values provide more accurate peak detection but increase overhead. so like… more accurate = more work. choose your fighter 💀
  • --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. see MEMORY UNITS for how unit suffixes are interpreted.

💜 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. ✨ snapshot the vibe ✨
  • --compare-baseline NAME — compare the current run against a previously saved baseline. reports memory usage changes and indicates if a regression is detected. glow-up or glow-down, she'll tell you 🦋
  • --regression-threshold PERCENT — set the percentage increase in RSS that constitutes a regression (default: 10.0). only used with --compare-baseline. pick your tolerance, bestie.
  • --baseline-dir DIR — directory to store baseline files (default: ~/.cache/peak-mem/baselines).
  • --list-baselines — list all saved baselines and exit. show me the archive 💅
  • --delete-baseline NAME — delete a saved baseline and exit. it's not you, it's the memory footprint 🥀

🌈 Standard Options 🌈

  • -h, --help — display help message and exit.
  • -V, --version — display version information and exit.

⭐ EXAMPLES ⭐

🌸 Basic Usage 🌸

monitor memory usage of a cargo build:

peak-mem -- cargo build

🌸 JSON Output 🌸

get machine-readable output:

peak-mem --json -- ./myapp

🌸 Memory Threshold 🌸

alert if memory usage exceeds 1GB:

peak-mem --threshold 1G -- ./memory-intensive-app

🌸 Real-time Monitoring 🌸

watch memory usage as it happens:

peak-mem --watch -- ./long-running-process

🌸 Timeline Recording 🌸

record a detailed timeline for analysis:

peak-mem --timeline memory.json -- ./app

🌸 Process-only Monitoring 🌸

monitor only the main process, ignoring children:

peak-mem --no-children -- ./parent-process

🌸 Fixed Memory Units 🌸

display memory usage in megabytes:

peak-mem --units MB -- ./myapp

🌸 Combined Options 🌸

verbose output with threshold and timeline:

peak-mem -v --threshold 2G --timeline mem.json -- make -j8

🌸 Memory Regression Detection 🌸

save a baseline for your application:

peak-mem --save-baseline v1.0 -- ./myapp

compare against the baseline after changes:

peak-mem --compare-baseline v1.0 -- ./myapp

use a stricter regression threshold (5%):

peak-mem --compare-baseline v1.0 --regression-threshold 5 -- ./myapp

list and manage baselines:

peak-mem --list-baselines
peak-mem --delete-baseline v1.0

💅 OUTPUT FORMATS 💅

🩷 Human-readable (default) 🩷

shows peak RSS and VSZ in human-readable units (KiB, MiB, GiB) along with the monitored command and exit status. cute, cozy, readable 🌼

🩷 JSON Format (-j) 🩷

outputs a JSON object containing:

  • command: the executed command with arguments
  • peak_rss_bytes: peak RSS in bytes
  • peak_vsz_bytes: peak VSZ in bytes
  • duration_ms: execution time in milliseconds
  • exit_code: process exit code
  • threshold_exceeded: boolean (if threshold was set)
  • tracked_children: boolean indicating if children were tracked

🩷 CSV Format (-c) 🩷

outputs CSV with headers:

command,peak_rss_bytes,peak_vsz_bytes,duration_ms,exit_code

🩷 Quiet Format (-q) 🩷

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

🩷 Verbose Format (-v) 🩷

shows a detailed process tree with individual memory usage for each process, including PIDs and process names. the whole fam, accounted for 🌳

🫶 MEMORY UNITS 🫶

okay this part is important so pay attention bestie!! unit suffixes without an "i" are decimal (SI, powers of 1000); suffixes with an "i" are binary (IEC, powers of 1024). this convention applies consistently to both input (--threshold) and output (--units and automatic sizing, which uses binary units). 🔥

  • no suffix, B: bytes
  • K, KB: kilobytes (1000 bytes); M, MB: megabytes (1000² bytes); G, GB: gigabytes (1000³ bytes); T, TB: terabytes (1000 bytes)
  • KiB: kibibytes (1024 bytes); MiB: mebibytes (1024² bytes); GiB: gibibytes (1024³ bytes); TiB: tebibytes (1024 bytes)

😭 EXIT STATUS 😭

peak-mem normally exits with the same status code as the monitored command. if the monitored command is terminated by a signal, peak-mem exits with status 128 + signal number. she's just the messenger, fr fr.

special exit codes:

  • 1 — memory threshold exceeded (when using --threshold)
  • 1 — memory regression detected (when using --compare-baseline)
yes bestie, they're both 1. read the context. 💀

🌈 PLATFORM SUPPORT 🌈

  • Linux — full support via /proc filesystem 🐧
  • macOS — full support via proc_pidinfo 🍎
  • FreeBSD — full support via sysinfo 😈
  • Windows — not supported 🙈

💀 LIMITATIONS 💀

  • memory sampling occurs at intervals (default 100ms), so very brief spikes might be missed. decrease the interval for more accurate peak detection.
  • on some systems, tracking child processes requires appropriate permissions.
  • timeline files can grow large for long-running processes with small intervals.

🦋 ENVIRONMENT 🦋

peak-mem forwards all environment variables to the monitored process without modification. she does not touch your stuff. respectful. 💖

🌸 SIGNALS 🌸

peak-mem forwards most signals to the monitored process, allowing for proper cleanup and termination handling. so your process still gets its goodbye moment. 🥹

🎀 FILES 🎀

  • /proc/[pid]/status — on Linux, used to read memory information.
  • /proc/[pid]/task/ — on Linux, used to track all threads of a process.

⭐ SEE ALSO ⭐

time(1), ps(1), top(1), htop(1), pmap(1)

🐛 BUGS 🐛

report bugs at: ~charmitro/peak-mem-devel@lists.sr.ht

(not me writing bugs… couldn't be me… but if it is, tell them 🙈)

👑 AUTHOR 👑

written by Charalampos Mitrodimas and Panagiotis Foliadis. kings. 💅

copyright © 2025 peak-mem contributors. license: MIT.

and that's the whole thing, bestie!! ✨💖 this was peak-mem version 0.1.4, dated July 2026, from section 1 of the manual. go monitor something and slay responsibly. 🎀🦋💜

📦 where this page comes from