README: refactor readme to be simplier

Signed-off-by: Charalampos Mitrodimas <[email protected]>

Author: charmitro

README.md

@@ -1,77 +1,87 @@
 # peak-mem
 
-[![CI](https://github.com/peak-mem/peak-mem/actions/workflows/ci.yml/badge.svg)](https://github.com/peak-mem/peak-mem/actions/workflows/ci.yml)
-[![Security Audit](https://github.com/peak-mem/peak-mem/actions/workflows/security.yml/badge.svg)](https://github.com/peak-mem/peak-mem/actions/workflows/security.yml)
+A lightweight, cross-platform memory usage monitor for any process.
 
-A lightweight, cross-platform memory usage monitor for any process. Track peak memory consumption with minimal overhead.
+## Overview
+
+peak-mem is a command-line utility that monitors and reports the peak memory usage of any program during its execution. It tracks both resident set size (RSS) and virtual memory size (VSZ) with minimal overhead, providing system administrators and developers with essential memory consumption metrics.
 
 ## Features
 
-- 🚀 **Minimal overhead** - Less than 1% CPU impact on monitored processes
-- 📊 **Multiple output formats** - Human-readable, JSON, CSV, or quiet mode
-- 👶 **Child process tracking** - Monitor entire process trees
-- ⚡ **Real-time monitoring** - Watch memory usage as it happens
-- 🎯 **Threshold alerts** - Exit with error code when memory exceeds limits
-- 📈 **Timeline recording** - Export memory usage over time
-- 🔧 **Zero configuration** - Works immediately after installation
+- Low overhead monitoring
+- Multiple output formats (human-readable, JSON, CSV, quiet)
+- Child process tracking with process tree aggregation
+- Real-time memory usage display
+- Memory threshold monitoring with configurable alerts
+- Timeline recording for memory usage analysis
+- Cross-platform support (Linux, macOS, Windows & FreeBSD planned)
+- Zero configuration required
 
 ## Installation
 
-### From source
+### From Source
 
 ```bash
 cargo install --path .
 ```
 
-### Pre-built binaries
+### Pre-built Binaries
 
 Download the latest release for your platform from the [releases page](https://github.com/peak-mem/peak-mem/releases).
 
 ## Usage
 
-### Basic usage
+### Basic Usage
 
 Monitor a command and report its peak memory usage:
 
 ```bash
 peak-mem -- cargo build --release
 ```
 
-Output:
+Example output:
 ```
 Command: cargo build --release
 Peak memory usage: 487.3 MB (RSS) / 892.1 MB (VSZ)
 Exit code: 0
 Duration: 14.2s
 ```
 
-### Command-line options
+### Command-line Options
 
 ```
-peak-mem [OPTIONS] -- <COMMAND> [ARGS...]
+USAGE:
+    peak-mem [OPTIONS] -- <COMMAND> [ARGS...]
 
 OPTIONS:
     -h, --help              Print help information
     -V, --version           Print version information
     -j, --json              Output in JSON format
     -c, --csv               Output in CSV format
-    -q, --quiet             Only output peak RSS value
-    -v, --verbose           Show detailed breakdown
-    -w, --watch             Show real-time memory usage
+    -q, --quiet             Only output peak RSS value in bytes
+    -v, --verbose           Show detailed process breakdown
+    -w, --watch             Display real-time memory usage
     -t, --threshold <SIZE>  Set memory threshold (e.g., 512M, 1G)
     --no-children           Don't track child processes
     --timeline <FILE>       Record memory timeline to file
     --interval <MS>         Sampling interval in milliseconds [default: 100]
+
+ARGS:
+    <COMMAND>               Command to execute and monitor
+    [ARGS...]               Arguments to pass to the command
 ```
 
-### Examples
+## Examples
+
+### JSON Output
 
-#### JSON output for CI/CD integration
+For integration with CI/CD pipelines or automated tools:
 
 ```bash
 peak-mem --json -- ./my-app
 ```
 
+Output:
 ```json
 {
   "command": "./my-app",
@@ -84,112 +94,224 @@ peak-mem --json -- ./my-app
 }
 ```
 
-#### Set memory threshold
+### Memory Threshold Monitoring
+
+Exit with error code if memory exceeds threshold:
 
 ```bash
 peak-mem --threshold 1GB -- ./memory-intensive-app
 ```
 
 If the process exceeds 1GB of RSS, peak-mem will exit with code 1.
 
-#### Real-time monitoring
+### Real-time Monitoring
+
+Display live memory usage during execution:
 
 ```bash
 peak-mem --watch -- ./long-running-process
 ```
 
-Shows live memory usage updates during execution.
+### Exclude Child Processes
 
-#### Monitor without child processes
+Monitor only the main process:
 
 ```bash
 peak-mem --no-children -- make -j8
 ```
 
-Only tracks the main make process, not the spawned compilation jobs.
+### Timeline Recording
 
-#### Record memory timeline
+Save memory usage over time for analysis:
 
 ```bash
 peak-mem --timeline memory.json -- ./batch-job
 ```
 
-Saves detailed memory usage over time for later analysis.
+### CSV Output
+
+For spreadsheet import or data analysis:
+
+```bash
+peak-mem --csv -- ./data-processor
+```
+
+Output:
+```csv
+command,peak_rss_bytes,peak_vsz_bytes,duration_ms,exit_code,threshold_exceeded,timestamp
+./data-processor,52428800,104857600,2150,0,false,2025-05-24T10:30:45+00:00
+```
 
 ## Platform Support
 
-- ✅ **Linux** - Full support via `/proc` filesystem
-- ✅ **macOS** - Full support via system APIs
-- 🚧 **Windows** - Planned
-- 🚧 **FreeBSD** - Planned
+| Platform | Status | Implementation |
+|----------|--------|---------------|
+| Linux    | Stable | `/proc` filesystem |
+| macOS    | Stable | `proc_pidinfo` APIs |
+| Windows  | Planned | Windows API |
+| FreeBSD  | Planned | `sysctl` interface |
 
-## How it works
+## How It Works
 
-peak-mem spawns your process and monitors its memory usage by:
+peak-mem operates by:
 
-1. Sampling memory statistics at regular intervals (default: 100ms)
-2. Tracking all child processes in the process tree
-3. Recording peak values throughout execution
-4. Reporting results after the process terminates
+1. Spawning the target process as a child
+2. Periodically sampling memory statistics (default: every 100ms)
+3. Tracking all descendant processes if enabled
+4. Recording peak values throughout execution
+5. Reporting results when the process terminates
 
-The tool uses platform-specific APIs for minimal overhead:
-- Linux: `/proc/[pid]/status` for memory information
-- macOS: `proc_pidinfo` system calls
-- Windows: `GetProcessMemoryInfo` (planned)
+The monitoring is performed using platform-specific APIs to minimize overhead:
+- **Linux**: Reads from `/proc/[pid]/status` and `/proc/[pid]/stat`
+- **macOS**: Uses `proc_pidinfo` system calls
+- **Windows**: Will use `GetProcessMemoryInfo` (planned)
+- **FreeBSD**: Will use `sysctl` and `kvm` interfaces (planned)
 
-## Performance
+## Performance Characteristics
 
-- **Startup time**: < 10ms
-- **Memory overhead**: < 10MB
-- **CPU overhead**: < 1%
-- **Binary size**: ~1.1MB (stripped)
+- Startup time: < 10ms
+- Memory overhead: < 10MB
+- CPU overhead: < 1%
+- Binary size: ~1.1MB (release build, stripped)
+- Sampling rate: Configurable, default 10Hz
 
-## Building from source
+## Building from Source
 
 ### Prerequisites
 
-- Rust 1.70 or later
-- Cargo
+- Rust 1.74 or later (specified in `rust-version` in Cargo.toml)
+- Platform-specific development tools
 
-### Build
+### Build Commands
 
 ```bash
 # Debug build
 cargo build
 
 # Release build (optimized)
 cargo build --release
+
+# Run tests
+cargo test
+
+# Run with verbose output
+RUST_LOG=debug cargo run -- <command>
+```
+
+### Cross-compilation
+
+```bash
+# For Linux x86_64
+cargo build --target x86_64-unknown-linux-gnu
+
+# For macOS x86_64
+cargo build --target x86_64-apple-darwin
+
+# For macOS ARM64
+cargo build --target aarch64-apple-darwin
+```
+
+## Development
+
+### Project Structure
+
+```
+src/
+├── main.rs          # Application entry point
+├── cli.rs           # Command-line argument parsing
+├── types.rs         # Core data structures
+├── process/         # Process spawning and management
+├── monitor/         # Platform-specific memory monitoring
+│   ├── mod.rs       # Platform abstraction layer
+│   ├── linux.rs     # Linux implementation
+│   ├── macos.rs     # macOS implementation
+│   ├── windows.rs   # Windows implementation (stub)
+│   └── tracker.rs   # Memory tracking logic
+└── output/          # Output formatting
 ```
 
-### Run tests
+### Testing
 
 ```bash
+# Run all tests
 cargo test
+
+# Run tests with output
+cargo test -- --nocapture
+
+# Run specific test
+cargo test test_memory_tracking
 ```
 
-## Contributing
+### Code Quality
+
+```bash
+# Format code
+cargo fmt
+
+# Run linter
+cargo clippy -- -D warnings
+
+# Security audit
+cargo audit
+
+# Check dependencies
+cargo deny check
+```
+
+## Configuration
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+peak-mem requires no configuration files. All options are specified via command-line arguments.
 
-### Development
+Environment variables:
+- `RUST_LOG`: Set to `debug` for verbose logging
 
-The codebase is organized as follows:
+## Troubleshooting
 
-- `src/cli.rs` - Command-line argument parsing
-- `src/monitor/` - Platform-specific memory monitoring
-- `src/process/` - Process spawning and management
-- `src/output/` - Output formatting
-- `src/types.rs` - Core data types
+### Permission Denied
+
+On some systems, you may need elevated permissions to monitor certain processes:
+- Linux: No special permissions required for own processes
+- macOS: May require developer tools or sudo for system processes
+
+### High Memory Usage Reported
+
+Virtual memory size (VSZ) includes all mapped memory and is typically much larger than RSS. Focus on RSS for actual physical memory usage.
+
+### Child Processes Not Tracked
+
+Some programs may spawn processes in ways that break the parent-child relationship. Use system-specific tools like `pstree` to verify process relationships.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and clippy
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
 ## License
 
-This project is licensed under either of
+This project is dual-licensed under:
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 - MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
-at your option.
+You may choose either license for your use.
 
 ## Acknowledgments
 
-Inspired by GNU time's memory reporting and the need for a simple, cross-platform memory monitoring tool.
+This project was inspired by:
+- GNU time's memory reporting capabilities
+- The need for a simple, cross-platform memory monitoring solution
+- The Rust ecosystem's excellent system programming capabilities
+
+## Related Projects
+
+- [GNU time](https://www.gnu.org/software/time/) - Classic UNIX time with memory reporting
+- [hyperfine](https://github.com/sharkdp/hyperfine) - Command-line benchmarking tool
+- [procs](https://github.com/dalance/procs) - Modern ps replacement written in Rust