pwrzv is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install pwrzv

It will make the pwrzv command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall pwrzv uninstalls.

Adding `pwrzv` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add pwrzv

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

pwrzv = "0.6.2"

The pwrzv library will be automatically available globally. Read the pwrzv library documentation.

Back to the crate overview.

Readme

pwrzv

A Rolls-Royce–inspired performance reserve meter for Linux and macOS systems. Elegant, minimal, and focused on what really matters: how much performance your machine has left to give.

⚠️ Beta Stage Notice

This library is currently in Beta stage and not yet fully mature.

Parameter tuning may not be precise enough and might need adjustment for specific systems
API and behavior may change in future versions
We welcome your feedback and contributions through Issues and Pull Requests
Please test thoroughly before using in production environments

Your feedback is crucial for improving this project!

🛠 What is pwrzv?

Inspired by the Power Reserve gauge in Rolls-Royce cars — which shows how much engine power is still available — pwrzv brings the same philosophy to Unix-like systems. Instead of showing raw usage, it estimates how much headroom remains in your system's core resources.

It provides a simple 0–5 score, calculated from multiple real-time metrics:

CPU usage and I/O wait
Memory availability
Swap activity
Disk I/O
Network throughput and packet loss
File descriptor consumption

All inputs are weighted and transformed via sigmoid functions to reflect practical bottlenecks, not just raw numbers.

🚦 Example Output

Basic Usage

$ pwrzv
2

Detailed Analysis

$ pwrzv --detailed
=== System Power Reserve Analysis ===

System Metrics:
  CPU Usage: 12.34% (iowait: 0.00%)
  Memory Available: 78.50%
  Swap Usage: 0.00%
  Disk I/O Usage: 5.10%
  Network I/O Usage: 0.75%
  File Descriptor Usage: 3.42%

Component Scores (0-5):
  CPU:              5
  I/O Wait:         5
  Memory:           4
  Swap:             5
  Disk I/O:         5
  Network I/O:      5
  File Descriptors: 5

Overall Assessment:
  Power Reserve Score: 4 (Good - Ample resources)
  Bottlenecks: None

✅ System has ample performance headroom.

📦 Installation

From Source

git clone https://github.com/kookyleo/pwrzv.git
cd pwrzv
cargo install --path .

Using Cargo

cargo install pwrzv

🖥️ Platform Support

pwrzv supports Linux and macOS systems for now. Other platforms will display an error message.

Platform-Specific Implementation

Linux: Uses /proc filesystem for direct system metrics access
macOS: Uses system commands (sysctl, vm_stat, iostat, etc.) for metrics collection

🔧 Usage

Command Line Interface

# Basic usage (simplest numeric output)
pwrzv

# Detailed component analysis (default text format)
pwrzv --detailed

# Detailed analysis with JSON output
pwrzv --detailed json

# Detailed analysis with YAML output
pwrzv --detailed yaml

Library Usage

use pwrzv::{get_power_reserve_level_direct, PwrzvError};

#[tokio::main]
async fn main() -> Result<(), PwrzvError> {
    let level = get_power_reserve_level_direct().await?;
    println!("Power Reserve Level: {}/5", level);
    Ok(())
}

Detailed Analysis

use pwrzv::{get_power_reserve_level_with_details_direct, PwrzvError};

#[tokio::main]
async fn main() -> Result<(), PwrzvError> {
    let (level, details) = get_power_reserve_level_with_details_direct().await?;
    
    println!("Power Reserve: {:.2}/5.0", level);
    println!("Detailed metrics:");
    for (metric, value) in details {
        println!("  {}: {:.3}", metric, value);
    }
    Ok(())
}

Platform Support Check

use pwrzv::{check_platform, get_platform_name, PwrzvError};

fn main() -> Result<(), PwrzvError> {
    println!("Running on: {}", get_platform_name());
    
    match check_platform() {
        Ok(()) => println!("Platform is supported!"),
        Err(e) => eprintln!("Platform not supported: {}", e),
    }
    Ok(())
}

📊 Scoring System

The scoring system uses sigmoid functions to map resource utilization to a 0-5 scale:

5 (Excellent): Abundant resources, system running smoothly
4 (Good): Ample resources available, good performance
3 (Moderate): Adequate performance, resources sufficient
2 (Low): Resource constrained, consider optimization
0-1 (Critical): System under heavy load, immediate attention needed

How It Works

Resource Collection: Gathers metrics from /proc filesystem or system commands
Normalization: Converts raw metrics to 0-1 scale
Sigmoid Transformation: Applies configurable thresholds and curves
Bottleneck Detection: Takes the minimum score (worst resource)
Final Scoring: Maps to 0-5 range with level descriptions

🧮 Numerical Calculation Methods

pwrzv employs sophisticated mathematical algorithms to convert raw system metrics into meaningful power reserve scores:

Sigmoid Function Transformation

The core calculation uses the sigmoid function to transform linear resource utilization into a smooth 0-1 scale:

f(x) = 1 / (1 + e^(-k * (x - x₀)))

Where:

x: Raw metric value (0-1 range after normalization)
x₀ (midpoint): The threshold where the metric begins significantly impacting the score
k (steepness): Controls the curve's steepness; higher values create more dramatic score changes

Multi-Stage Processing Pipeline

Raw Data Collection: Platform-specific metric gathering (Linux: /proc filesystem, macOS: system commands)
Normalization: Convert raw values to 0-1 scale for consistent processing
Sigmoid Transformation: Apply individual sigmoid curves to each metric based on its characteristics
Bottleneck Analysis: Identify the worst-performing resource (minimum score)
Final Mapping: Transform the 0-1 result to the 0-5 Power Reserve scale

Adaptive Thresholds

Each metric uses carefully tuned parameters:

CPU metrics: Balanced sensitivity for both usage spikes and sustained load
Memory metrics: Higher thresholds to account for normal OS caching behavior
I/O metrics: Moderate sensitivity to distinguish between light and heavy workloads
Network metrics: Separate handling for bandwidth utilization vs. packet loss sensitivity

This mathematical approach ensures that pwrzv provides intuitive, actionable scores that reflect real system performance bottlenecks rather than raw utilization percentages.

⚙️ Environment Variable Configuration

pwrzv supports customizing sigmoid function parameters for each metric via environment variables to adapt to different system characteristics and use cases.

macOS Platform Environment Variables

# CPU usage configuration (default: midpoint=0.60, steepness=8.0)
export PWRZV_MACOS_CPU_USAGE_MIDPOINT=0.60
export PWRZV_MACOS_CPU_USAGE_STEEPNESS=8.0

# CPU load configuration (default: midpoint=1.2, steepness=5.0)
export PWRZV_MACOS_CPU_LOAD_MIDPOINT=1.2
export PWRZV_MACOS_CPU_LOAD_STEEPNESS=5.0

# Memory usage configuration (default: midpoint=0.85, steepness=20.0)
export PWRZV_MACOS_MEMORY_USAGE_MIDPOINT=0.85
export PWRZV_MACOS_MEMORY_USAGE_STEEPNESS=20.0

# Memory compression configuration (default: midpoint=0.60, steepness=15.0)
export PWRZV_MACOS_MEMORY_COMPRESSED_MIDPOINT=0.60
export PWRZV_MACOS_MEMORY_COMPRESSED_STEEPNESS=15.0

# Disk I/O configuration (default: midpoint=0.70, steepness=10.0)
export PWRZV_MACOS_DISK_IO_MIDPOINT=0.70
export PWRZV_MACOS_DISK_IO_STEEPNESS=10.0

# Network bandwidth configuration (default: midpoint=0.80, steepness=6.0)
export PWRZV_MACOS_NETWORK_MIDPOINT=0.80
export PWRZV_MACOS_NETWORK_STEEPNESS=6.0

# Network packet loss configuration (default: midpoint=0.01, steepness=50.0)
export PWRZV_MACOS_NETWORK_DROPPED_MIDPOINT=0.01
export PWRZV_MACOS_NETWORK_DROPPED_STEEPNESS=50.0

# File descriptor configuration (default: midpoint=0.90, steepness=30.0)
export PWRZV_MACOS_FD_MIDPOINT=0.90
export PWRZV_MACOS_FD_STEEPNESS=30.0

# Process count configuration (default: midpoint=0.80, steepness=12.0)
export PWRZV_MACOS_PROCESS_MIDPOINT=0.80
export PWRZV_MACOS_PROCESS_STEEPNESS=12.0

Linux Platform Environment Variables

# CPU usage configuration (default: midpoint=0.65, steepness=8.0)
export PWRZV_LINUX_CPU_USAGE_MIDPOINT=0.65
export PWRZV_LINUX_CPU_USAGE_STEEPNESS=8.0

# CPU I/O wait configuration (default: midpoint=0.20, steepness=20.0)
export PWRZV_LINUX_CPU_IOWAIT_MIDPOINT=0.20
export PWRZV_LINUX_CPU_IOWAIT_STEEPNESS=20.0

# CPU load configuration (default: midpoint=1.2, steepness=5.0)
export PWRZV_LINUX_CPU_LOAD_MIDPOINT=1.2
export PWRZV_LINUX_CPU_LOAD_STEEPNESS=5.0

# Memory usage configuration (default: midpoint=0.85, steepness=18.0)
export PWRZV_LINUX_MEMORY_USAGE_MIDPOINT=0.85
export PWRZV_LINUX_MEMORY_USAGE_STEEPNESS=18.0

# Memory pressure configuration (default: midpoint=0.30, steepness=12.0)
export PWRZV_LINUX_MEMORY_PRESSURE_MIDPOINT=0.30
export PWRZV_LINUX_MEMORY_PRESSURE_STEEPNESS=12.0

# Disk I/O configuration (default: midpoint=0.70, steepness=10.0)
export PWRZV_LINUX_DISK_IO_MIDPOINT=0.70
export PWRZV_LINUX_DISK_IO_STEEPNESS=10.0

# Network bandwidth configuration (default: midpoint=0.80, steepness=6.0)
export PWRZV_LINUX_NETWORK_MIDPOINT=0.80
export PWRZV_LINUX_NETWORK_STEEPNESS=6.0

# Network packet loss configuration (default: midpoint=0.01, steepness=50.0)
export PWRZV_LINUX_NETWORK_DROPPED_MIDPOINT=0.01
export PWRZV_LINUX_NETWORK_DROPPED_STEEPNESS=50.0

# File descriptor configuration (default: midpoint=0.90, steepness=25.0)
export PWRZV_LINUX_FD_MIDPOINT=0.90
export PWRZV_LINUX_FD_STEEPNESS=25.0

# Process count configuration (default: midpoint=0.80, steepness=12.0)
export PWRZV_LINUX_PROCESS_MIDPOINT=0.80
export PWRZV_LINUX_PROCESS_STEEPNESS=12.0

Parameter Meanings

midpoint: Sigmoid function midpoint value, representing the threshold where this metric starts significantly affecting the score
steepness: Sigmoid function steepness, higher values make the curve steeper and score changes more dramatic

Usage Example

# Adjust CPU threshold for high-performance server
export PWRZV_LINUX_CPU_USAGE_MIDPOINT=0.80
export PWRZV_LINUX_CPU_USAGE_STEEPNESS=15.0

# Run pwrzv
pwrzv --detailed

🧪 Philosophy

While most system monitors highlight how much is used, pwrzv tells you how much is left. This makes it a useful tool for:

Minimal dashboards - Single metric overview
Autoscaling decisions - When to scale up/down
Performance monitoring - Proactive resource management
System health checks - Quick status assessment

🔄 Examples

Run the included examples:

# Basic usage example
cargo run --example basic_usage

# Detailed metrics analysis example
cargo run --example detailed_metrics

🧪 Testing

# Run all tests
cargo test

# Run only unit tests
cargo test --lib

# Run documentation tests
cargo test --doc

# Run examples
cargo run --example basic_usage

📚 API Documentation

Generate and view the full API documentation:

cargo doc --open

🤝 Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass: cargo test
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by the Power Reserve gauge in Rolls-Royce automobiles
Built with Rust for performance and reliability
Thanks to the Linux kernel for providing comprehensive /proc metrics

Installing the command-line executable

Adding pwrzv library as a dependency

Adding `pwrzv` library as a dependency