|
| 1 | +# Hyperbyte Process Monitor |
| 2 | + |
| 3 | +A powerful terminal-based process monitor built in Go, featuring real-time process monitoring with ASCII graphs and an intuitive interface. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +### Main View (Process List) |
| 8 | +- **Live Process Monitoring**: Real-time display of all running processes |
| 9 | +- **Sortable Columns**: Sort by PID, Name, CPU usage, or Memory usage |
| 10 | +- **Search Functionality**: Filter processes by name or PID |
| 11 | +- **Color-coded Usage**: Visual indicators for resource consumption |
| 12 | + - 🟢 Green: Normal usage (< 25%) |
| 13 | + - 🟡 Yellow: Medium usage (25-50%) |
| 14 | + - 🟠 Orange: High usage (50-80%) |
| 15 | + - 🔴 Red: Critical usage (> 80%) |
| 16 | +- **Auto-refresh**: Updates every second automatically |
| 17 | + |
| 18 | +### Detail View (Process Graphs) |
| 19 | +- **Real-time ASCII Graphs**: Visual representation of process metrics |
| 20 | + - CPU usage percentage over time |
| 21 | + - Memory usage in MB over time (scaled to machine's total memory) |
| 22 | + - Disk I/O activity as percentage of system I/O - sparkline format |
| 23 | + - Network I/O activity (sent/received KB/s) - sparkline format |
| 24 | +- **Process Information Panel**: Detailed info including current I/O rates |
| 25 | +- **Rolling Window**: Keeps 60 seconds of historical data |
| 26 | +- **Accurate Scaling**: Memory graph shows true machine limits, I/O as percentages |
| 27 | + |
| 28 | +## Installation |
| 29 | + |
| 30 | +### Prerequisites |
| 31 | +- Go 1.19 or later |
| 32 | +- Unix-like system (Linux/macOS) - Windows support is optional |
| 33 | + |
| 34 | +### Build from Source |
| 35 | +```bash |
| 36 | +git clone <repository-url> |
| 37 | +cd hyperbyte-proc-monitor |
| 38 | +go mod download |
| 39 | +go build -o proc-monitor |
| 40 | +``` |
| 41 | + |
| 42 | +### Run |
| 43 | +```bash |
| 44 | +./proc-monitor |
| 45 | +``` |
| 46 | + |
| 47 | +## Usage |
| 48 | + |
| 49 | +### Keyboard Controls |
| 50 | + |
| 51 | +#### Main View |
| 52 | +| Key | Action | |
| 53 | +|-----|--------| |
| 54 | +| `↑/↓` | Navigate process list | |
| 55 | +| `Enter` | View detailed graphs for selected process | |
| 56 | +| `q` | Quit application | |
| 57 | +| `/` | Start search mode | |
| 58 | +| `ESC` | Clear search / Cancel current action | |
| 59 | +| `c` | Sort by CPU usage (descending) | |
| 60 | +| `m` | Sort by Memory usage (descending) | |
| 61 | +| `p` | Sort by PID (ascending) | |
| 62 | +| `n` | Sort by Name (ascending) | |
| 63 | +| `h` | Show help dialog | |
| 64 | + |
| 65 | +#### Detail View |
| 66 | +| Key | Action | |
| 67 | +|-----|--------| |
| 68 | +| `ESC` | Return to main view | |
| 69 | +| `q` | Return to main view | |
| 70 | + |
| 71 | +#### Search Mode |
| 72 | +| Key | Action | |
| 73 | +|-----|--------| |
| 74 | +| `Any character` | Add to search query | |
| 75 | +| `Backspace` | Remove last character | |
| 76 | +| `ESC` | Exit search mode | |
| 77 | + |
| 78 | +## Technical Architecture |
| 79 | + |
| 80 | +### Components |
| 81 | + |
| 82 | +1. **Monitor Package** (`internal/monitor/`) |
| 83 | + - Process data collection using `gopsutil` |
| 84 | + - System metrics gathering |
| 85 | + - Time-series data management |
| 86 | + - Configurable sorting and filtering |
| 87 | + |
| 88 | +2. **UI Package** (`internal/ui/`) |
| 89 | + - Terminal interface using `tview` |
| 90 | + - ASCII graph rendering |
| 91 | + - Keyboard event handling |
| 92 | + - Multi-view management |
| 93 | + |
| 94 | +3. **App Package** (`internal/app/`) |
| 95 | + - Application lifecycle management |
| 96 | + - Goroutine coordination |
| 97 | + - Signal handling for graceful shutdown |
| 98 | + |
| 99 | +### Performance Features |
| 100 | +- **Non-blocking UI**: Uses goroutines and channels for data updates |
| 101 | +- **Efficient Rendering**: Only updates changed data |
| 102 | +- **Memory Management**: Automatic cleanup of old process metrics |
| 103 | +- **Error Resilience**: Continues operation even if some processes can't be read |
| 104 | +- **Smart Process Prioritization**: Monitors top 150 processes by resource usage |
| 105 | +- **Optimized Update Frequencies**: Different intervals for system vs process metrics |
| 106 | +- **Reduced System Calls**: Minimal expensive operations like network enumeration |
| 107 | +- **Process Object Reuse**: Caches process objects to avoid repeated allocations |
| 108 | + |
| 109 | +### Graph Types |
| 110 | +- **Bar Graphs**: CPU usage (0-100%) & Memory usage (scaled to system total) |
| 111 | +- **Sparkline Graphs**: Disk I/O as percentage, Network I/O as KB/s rates |
| 112 | +- **Accurate Scaling**: Memory shows actual machine limits, not timeframe max |
| 113 | +- **Rate Calculations**: I/O metrics show real-time rates, not cumulative totals |
| 114 | +- **Historical Data**: 60-second rolling window with per-second granularity |
| 115 | +- **Color Coding**: Visual indicators for different usage levels |
| 116 | + |
| 117 | +### Metrics Details |
| 118 | +- **CPU**: Process CPU percentage (can exceed 100% on multi-core systems) |
| 119 | +- **Memory**: Physical RAM usage in MB, scaled against total system memory |
| 120 | +- **Disk I/O**: Combined read/write activity as percentage of system I/O capacity |
| 121 | +- **Network**: Estimated per-process network activity (approximation based on connections) |
| 122 | + |
| 123 | +## Dependencies |
| 124 | + |
| 125 | +- [github.com/rivo/tview](https://github.com/rivo/tview) - Terminal UI framework |
| 126 | +- [github.com/shirou/gopsutil](https://github.com/shirou/gopsutil) - System and process monitoring |
| 127 | +- [github.com/gdamore/tcell](https://github.com/gdamore/tcell) - Terminal handling (via tview) |
| 128 | + |
| 129 | +## System Requirements |
| 130 | + |
| 131 | +- **Memory**: ~10MB RAM |
| 132 | +- **CPU**: Low impact (~2-5% CPU usage) |
| 133 | +- **Permissions**: Read access to `/proc` filesystem (Linux) or equivalent system APIs |
| 134 | +- **Terminal**: Any terminal supporting ANSI colors and Unicode characters |
| 135 | + |
| 136 | +## Performance Optimizations |
| 137 | + |
| 138 | +The process monitor has been optimized to minimize system resource usage: |
| 139 | + |
| 140 | +### CPU Usage Optimizations |
| 141 | +- **Process Prioritization**: Only monitors top 150 processes by resource usage instead of all processes |
| 142 | +- **Two-Phase Processing**: Quick scan for all processes, detailed monitoring for top processes only |
| 143 | +- **Removed Expensive Operations**: Eliminated costly network connection enumeration per process |
| 144 | +- **Process Object Caching**: Reuses process objects to reduce allocations |
| 145 | +- **Batched Processing**: Processes data in chunks with occasional yielding to other goroutines |
| 146 | +- **Optimized Update Frequencies**: |
| 147 | + - System metrics: 1 second intervals |
| 148 | + - Process metrics: 2 second intervals |
| 149 | + - UI updates: 1.5 second intervals |
| 150 | + |
| 151 | +### Disk I/O Graph Improvements |
| 152 | +- **Fixed Percentage Calculations**: Uses consistent baseline for I/O percentage calculations |
| 153 | +- **Proper Time Series**: Stable rate calculations that don't fluctuate wildly |
| 154 | +- **Meaningful Baselines**: 100 MB/s system I/O baseline for realistic percentages |
| 155 | + |
| 156 | +### Network Monitoring |
| 157 | +- **Simplified Implementation**: Removed expensive per-process network connection enumeration |
| 158 | +- **Placeholder Implementation**: Network graphs show zeros to avoid performance impact |
| 159 | +- **Future Enhancement**: Can be improved with eBPF or more efficient monitoring techniques |
| 160 | + |
| 161 | +## Platform Support |
| 162 | + |
| 163 | +- ✅ Linux (fully tested) |
| 164 | +- ✅ macOS (should work with gopsutil) |
| 165 | +- ⚠️ Windows (basic support via gopsutil, some features may be limited) |
| 166 | + |
| 167 | +## Troubleshooting |
| 168 | + |
| 169 | +### Common Issues |
| 170 | + |
| 171 | +1. **Permission Denied**: Some process information requires elevated privileges |
| 172 | + ```bash |
| 173 | + sudo ./proc-monitor |
| 174 | + ``` |
| 175 | + |
| 176 | +2. **Display Issues**: Ensure terminal supports Unicode and colors |
| 177 | + ```bash |
| 178 | + export TERM=xterm-256color |
| 179 | + ``` |
| 180 | + |
| 181 | +3. **Build Errors**: Make sure Go modules are downloaded |
| 182 | + ```bash |
| 183 | + go mod tidy |
| 184 | + go mod download |
| 185 | + ``` |
| 186 | + |
| 187 | +### Performance Tuning |
| 188 | + |
| 189 | +- The application auto-manages memory by cleaning up old metrics every 30 seconds |
| 190 | +- Process list updates every second - this interval is configurable in the code |
| 191 | +- Historical data is limited to 60 data points per process (about 1 minute) |
| 192 | + |
| 193 | +## Contributing |
| 194 | + |
| 195 | +1. Fork the repository |
| 196 | +2. Create a feature branch |
| 197 | +3. Make your changes |
| 198 | +4. Add tests if applicable |
| 199 | +5. Submit a pull request |
| 200 | + |
| 201 | +## License |
| 202 | + |
| 203 | +[Add your license here] |
| 204 | + |
| 205 | +## Future Enhancements |
| 206 | + |
| 207 | +- [ ] Configurable refresh intervals |
| 208 | +- [ ] Export metrics to file |
| 209 | +- [ ] Process filtering by user/group |
| 210 | +- [ ] System-wide resource usage graphs |
| 211 | +- [ ] Plugin system for custom metrics |
| 212 | +- [ ] Configuration file support |
| 213 | +- [ ] Theme customization |
0 commit comments