PEAK-MEM(1)

NAME
peak-mem - monitor peak memory usage of processes

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

DESCRIPTION
peak-mem is a lightweight memory usage monitor that tracks and reports the peak memory usage of a process and its children during execution. It provides both real-time monitoring and post-execution reporting with minimal overhead.

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.

OPTIONS

  Output Format Options

-j, --json
    Output results in JSON format. Useful for parsing by other tools.

-c, --csv
    Output results in CSV format. The output includes headers and is suitable for importing into spreadsheets or data analysis tools.

-q, --quiet
    Quiet mode. Only output the peak RSS value in bytes with no formatting. Useful for scripting.

-v, --verbose
    Show detailed breakdown including process tree. Displays memory usage for each process in the hierarchy.

  Monitoring Options

-w, --watch
    Display real-time memory usage during execution. Updates the display continuously as the process runs.

-t, --threshold SIZE
    Set a memory threshold alert. Accepts values like 512M, 1G, 2GB. The program will indicate if the threshold is exceeded.

--no-children
    Don't track child processes. By default, peak-mem monitors the entire process tree.

--timeline FILE
    Record detailed memory timeline to the specified file. The timeline includes timestamps and memory values for later analysis.

--interval MS
    Set the sampling interval in milliseconds (default: 100). Lower values provide more accurate peak detection but increase overhead.

--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.

  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.

--compare-baseline NAME
    Compare the current run against a previously saved baseline. Reports memory usage changes and indicates if a regression is detected.

--regression-threshold PERCENT
    Set the percentage increase in RSS that constitutes a regression (default: 10.0). Only used with --compare-baseline.

--baseline-dir DIR
    Directory to store baseline files (default: ~/.cache/peak-mem/baselines).

--list-baselines
    List all saved baselines and exit.

--delete-baseline NAME
    Delete a saved baseline and exit.

  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 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 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 (KB, MB, GB) along with the monitored command and exit status.

  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 detailed process tree with individual memory usage for each process, including PIDs and process names.

MEMORY UNITS
Memory sizes can be specified using the following units:

    •   K, KB: Kilobytes (1024 bytes)

    •   M, MB: Megabytes (1024² bytes)

    •   G, GB: Gigabytes (1024³ bytes)

    •   No suffix: 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.

Special exit codes:

    1   Memory threshold exceeded (when using --threshold)

    1   Memory regression detected (when using --compare-baseline)

PLATFORM SUPPORT

Linux
    Full support via /proc filesystem

macOS
    Full support via proc_pidinfo

FreeBSD
    Not currently implemented

Windows
    Not currently implemented

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.

SIGNALS
peak-mem forwards most signals to the monitored process, allowing for proper cleanup and termination handling.

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

AUTHOR
Written by the peak-mem contributors.

COPYRIGHT
Copyright © 2025 peak-mem contributors. License: MIT