Skip to content

README.md

Latest commit

 

History

History
255 lines (182 loc) · 7.61 KB

README.md

File metadata and controls

255 lines (182 loc) · 7.61 KB

🔍 RustWhy

CI License: GPL-3.0 Rust Version

Unified Linux System Diagnostics – Understand WHY things happen

RustWhy is a comprehensive system diagnostic tool that explains why your Linux system behaves a certain way. It combines 13 specialized diagnostic modules into one powerful CLI, providing actionable insights in plain language.

✨ Features

🔧 Complete Diagnostic Suite

Module Command Purpose
🚀 Boot Analysis rustwhy boot Analyze boot performance and identify slow services
💻 CPU Diagnostics rustwhy cpu Explain high CPU usage and top consumers
🧠 Memory Analysis rustwhy mem Understand memory consumption and identify leaks
💾 Disk Analysis rustwhy disk Find what's consuming disk space
📊 I/O Diagnostics rustwhy io Identify processes causing high disk I/O
🌐 Network Diagnostics rustwhy net Troubleshoot connectivity and performance issues
🌡️ Temperature Analysis rustwhy temp Monitor system temperatures and thermal throttling
🔊 Fan Diagnostics rustwhy fan Understand fan behavior and correlate with temps
🎮 GPU Analysis rustwhy gpu Comprehensive GPU diagnostics (NVIDIA/AMD/Intel)
🔋 Battery Analysis rustwhy batt Diagnose battery drain and power consumption
😴 Sleep Diagnostics rustwhy sleep Identify sleep/suspend inhibitors
🔌 USB Diagnostics rustwhy usb Troubleshoot USB device issues
📁 Mount Diagnostics rustwhy mount Debug filesystem mount problems

🎯 Key Capabilities

  • Plain Language Output: Get explanations you can understand, not just raw data
  • Actionable Recommendations: Receive specific commands and steps to resolve issues
  • Real-time Monitoring: Watch mode for continuous diagnostics (CPU, I/O, fans, temperature, GPU)
  • Multiple Output Formats: Terminal (colored), JSON for scripting
  • Comprehensive Metrics: Detailed breakdowns with thresholds and severity levels
  • Multi-Vendor GPU Support: Automatic detection and monitoring for NVIDIA, AMD, and Intel GPUs
  • Shell Completions: Auto-complete support for Bash, Zsh, Fish, and PowerShell

📦 Installation

From AUR (Arch Linux)

Arch Linux users can install RustWhy from the AUR using their favorite AUR helper:

# Using paru
paru -S rustwhy-git

# Using yay
yay -S rustwhy-git

# Or manually
git clone https://aur.archlinux.org/rustwhy-git.git
cd rustwhy-git
makepkg -sri

From Source

git clone https://github.com/Ninso112/rustwhy.git
cd rustwhy
cargo build --release
sudo cp target/release/rustwhy /usr/local/bin/

With NVIDIA GPU Support

cargo build --release --features nvidia
sudo cp target/release/rustwhy /usr/local/bin/

🚀 Usage

Quick Diagnostics

# Analyze CPU usage
rustwhy cpu

# Detailed memory analysis
rustwhy mem --detailed

# Check why disk is full
rustwhy disk /home --depth 4

# Network diagnostics with custom host
rustwhy net --host google.com

# Check boot performance
rustwhy boot --top 15

# Analyze GPU utilization and temperature
rustwhy gpu

Monitoring Mode

# Live CPU monitoring (updates every 2 seconds)
rustwhy cpu --watch

# Monitor disk I/O with 5-second intervals
rustwhy io --watch --interval 5

# Watch fan speeds and temperatures
rustwhy fan --watch

# Temperature monitoring
rustwhy temp --watch

# GPU monitoring
rustwhy gpu --watch

Advanced Usage

# Run all diagnostics
rustwhy all

# JSON output for scripting/parsing
rustwhy cpu --json
rustwhy all --json

# Verbose output with additional details
rustwhy mem --verbose

# Filter disk analysis
rustwhy disk --large 100M --old 90  # Files >100MB and >90 days old

# Check specific USB device
rustwhy usb --device 1234:5678

# Analyze NFS mounts
rustwhy mount --nfs

Shell Completions

# Generate completions for your shell
rustwhy completions bash > ~/.local/share/bash-completion/completions/rustwhy
rustwhy completions zsh > ~/.zsh/completions/_rustwhy
rustwhy completions fish > ~/.config/fish/completions/rustwhy.fish

📖 Documentation

🔍 Example Output

CPU DIAGNOSTICS
════════════════════════════════════════════════════════════

Overall Status: ✅ OK - CPU usage within normal range

  Load Average: 1.23 / 1.45 / 1.67 (1m / 5m / 15m)
  CPU Usage: 23.4%
  CPU Cores: 8

💡 WHY is this happening?

   ┌─ Finding: firefox (PID 12345) consuming 8.2% CPU
   │  → Memory: 2458240 KB, User: 1000
   └─ ℹ️  INFO

   ┌─ Finding: gnome-shell (PID 1678) consuming 3.1% CPU
   │  → Memory: 458240 KB, User: 1000
   └─ ℹ️  INFO

📋 RECOMMENDATIONS:

   1. [LOW] Monitor CPU usage during peak hours
      $ ps aux --sort=-%cpu | head -n 15
      → Keep track of resource-intensive applications

🛠️ Requirements

  • Operating System: Linux (kernel 4.0+)
  • Rust: 1.70 or newer
  • System Access: Some modules require /proc and /sys access
  • Optional:
    • systemd for boot analysis
    • NVIDIA drivers for GPU diagnostics (with --features nvidia)
    • Root access for some advanced diagnostics

🤝 Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

Quick Start for Contributors

# Clone and build
git clone https://github.com/Ninso112/rustwhy.git
cd rustwhy
cargo build

# Run tests
cargo test

# Check formatting and linting
cargo fmt --all -- --check
cargo clippy --all-features -- -D warnings

# Run a module
cargo run -- cpu

📝 License

This project is licensed under the GPL-3.0 License – see the LICENSE file for details.

🙏 Acknowledgments

RustWhy consolidates and reimplements in Rust the functionality of these Python diagnostic tools:

  • bootwhy, cpuwhy, memwhy, diskwhy, iowhy
  • netwhy, fanwhy, tempwhy, gpuwhy
  • battwhy, sleepwhy, usbwhy, mountwhy

🌟 Star History

If you find RustWhy useful, please consider giving it a star on GitHub!

📮 Support

🗺️ Roadmap

  • Add HTML output format
  • Implement historical data tracking
  • Add system health scoring
  • Create interactive TUI mode
  • Multi-vendor GPU support (NVIDIA/AMD/Intel) - COMPLETED
  • GPU per-process memory breakdown
  • Package for major distributions (AUR, deb, rpm) - AUR COMPLETED
  • Add plugin system for custom modules

Made with ❤️ by Ninso112