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.
| 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 |
- 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
Pre-built x86_64-unknown-linux-gnu binaries are attached to every
GitHub release.
No Rust toolchain required.
# Download and unpack the latest release
curl -L https://github.com/Ninso112/rustwhy/releases/latest/download/rustwhy-v0.1.0-x86_64-unknown-linux-gnu.tar.gz \
| sudo tar -xz -C /usr/local/bin rustwhy
# Verify
rustwhy --versionArch 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 -srigit clone https://github.com/Ninso112/rustwhy.git
cd rustwhy
cargo build --release
sudo cp target/release/rustwhy /usr/local/bin/cargo build --release --features nvidia
sudo cp target/release/rustwhy /usr/local/bin/# 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# 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# 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# 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
rustwhy completions powershell > _rustwhy.ps1Or from the project root: make completions. Generated scripts land in
assets/completions/.
- Module Documentation - Detailed information about each diagnostic module
- GPU Support - Comprehensive GPU diagnostics guide (NVIDIA/AMD/Intel)
- Architecture Overview - How RustWhy is structured internally
- API Documentation - Complete API reference for using RustWhy as a library
- Development Guide - Building, testing, and extending RustWhy
- Contributing Guidelines - How to contribute to the project
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
- Operating System: Linux (kernel 4.0+)
- Rust: 1.70 or newer
- System Access: Some modules require
/procand/sysaccess - Optional:
systemdfor boot analysis- NVIDIA drivers for GPU diagnostics (with
--features nvidia) - Root access for some advanced diagnostics
Contributions are welcome! Please see our Contributing Guidelines for details.
# 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 -- cpuThis project is licensed under the GPL-3.0 License – see the LICENSE file for details.
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
If you find RustWhy useful, please consider giving it a star on GitHub!
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- 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