ResourceUsageAPI/README_v2.md

Resource Monitor Service for Unraid VM

A comprehensive system monitoring service specifically designed for Windows VMs running on Unraid servers. This service provides real-time monitoring of CPU, memory, GPU, disk, network, and system resources through a RESTful API.

🚀 Features

Core Monitoring

• CPU Monitoring: Per-core usage, frequency, temperature, and throttling detection
• Memory Monitoring: RAM usage, available memory, committed memory, and paging
• GPU Monitoring: NVIDIA GPU usage, memory, temperature (via NVML)
• Disk Monitoring: I/O statistics, space usage, and performance counters
• Network Monitoring: Bandwidth usage, packet statistics, and interface data
• Temperature Monitoring: CPU and hard drive temperature sensors

VM-Specific Features

• VM Detection: Automatically detects virtualization environment
• Hypervisor Identification: Identifies VMware, VirtualBox, Hyper-V, KVM, etc.
• Unraid Optimization: Optimized for Unraid VM environments
• Resource Alerting: Configurable thresholds for resource usage alerts

Advanced Features

• Game Detection: Multi-platform game detection with fullscreen monitoring
• Process Management: View top processes, terminate processes via API
• Smart Alerting: Duration-based alerting to prevent false positives
• System Control: Remote shutdown/restart capabilities
• Health Monitoring: Comprehensive health checks and uptime tracking

📡 API Endpoints

The service runs on http://localhost:5000 by default and provides the following endpoints:

System Information

• GET /api/system-info - Complete system information including VM details
• GET /api/vm/info - VM-specific information (hypervisor, uptime, etc.)
• GET /api/health - Service health status and monitoring capabilities
• GET /api/metrics - Service metrics and performance overview
• GET /api/config - Current configuration settings

Resource Monitoring

• GET /api/resource-usage - Complete resource usage overview
• GET /api/cpu-usage - Detailed CPU metrics with per-core data
• GET /api/memory-usage - Memory utilization and statistics
• GET /api/gpu-usage - GPU usage, memory, and temperature
• GET /api/disk-usage - Disk I/O and space usage for all drives
• GET /api/network-usage - Network interface statistics
• GET /api/top-processes?count=10 - Top processes by CPU/memory usage

Game Detection

• GET /api/current-game - Currently running game information
• GET /api/all-games - All detected games on the system
• GET /api/fullscreen-status - Check if any game is running fullscreen

Alerting System

• GET /api/alerts/active - Currently active alerts
• GET /api/alerts/history?count=100 - Alert history
• POST /api/alerts/{alertId}/resolve - Manually resolve an alert
• GET /api/alerts/enabled - Check if alerting is enabled

System Control

• POST /api/process/kill - Terminate a process (requires process ID and optional force flag)
• POST /api/system/shutdown - Shutdown, restart, or cancel system operations
• POST /api/service/stop - Stop the monitoring service

🛠️ Installation & Usage

Option 1: Console Application (Development/Testing)

cd C:\Work\DEV\ResourceUsageAPI
dotnet run --configuration Release

Option 2: Windows Service (Production)

# Run as Administrator
cd C:\Work\DEV\ResourceUsageAPI\publish
.\install-service.bat

Option 3: Standalone Executable

cd C:\Work\DEV\ResourceUsageAPI\publish
.\ResourceMonitorService.exe

⚙️ Configuration

Configuration is managed through appsettings.json:

{
  "MonitoringSettings": {
    "UpdateIntervalMs": 5000,
    "EnableGpuMonitoring": true,
    "EnableDiskMonitoring": true,
    "EnableNetworkMonitoring": true,
    "EnableTemperatureMonitoring": true,
    "EnableProcessMonitoring": true,
    "EnableGameDetection": true,
    "EnableAlerts": true
  },
  "AlertThresholds": {
    "CpuUsageThreshold": 80.0,
    "MemoryUsageThreshold": 85.0,
    "GpuUsageThreshold": 90.0,
    "DiskUsageThreshold": 90.0,
    "TemperatureThreshold": 80.0,
    "AlertDurationSeconds": 30
  },
  "ApiSettings": {
    "RequireApiKey": false,
    "AllowedOrigins": ["http://localhost:4200", "http://unraid:4200"],
    "BasePath": "/api"
  }
}

📊 Example API Responses

Health Check

{
  "status": "Healthy",
  "timestamp": "2025-08-07T02:30:00Z",
  "uptime": "1.16:55:30",
  "activeAlerts": 0,
  "monitoringEnabled": {
    "gpu": true,
    "disk": true,
    "network": true,
    "temperature": true,
    "processes": true,
    "games": true,
    "alerts": true
  }
}

CPU Usage

{
  "usage": 15.5,
  "coreUsages": [12.1, 18.3, 14.7, 16.2],
  "temperature": 65.0,
  "maxFrequency": 4400,
  "currentFrequency": 3200,
  "isThrottling": false
}

VM Information

{
  "isVirtualMachine": true,
  "hypervisorVendor": "VMware",
  "uptime": "1.16:55:30",
  "bootTime": "2025-08-05T09:34:04Z",
  "machineName": "WIN11-VM",
  "domain": "WORKGROUP"
}

🔧 PowerShell Usage Examples

# Get system health
$health = Invoke-RestMethod -Uri "http://localhost:5000/api/health"
Write-Host "System Status: $($health.status)"

# Get CPU usage
$cpu = Invoke-RestMethod -Uri "http://localhost:5000/api/cpu-usage"
Write-Host "CPU Usage: $($cpu.usage)%"

# Get current game
$game = Invoke-RestMethod -Uri "http://localhost:5000/api/current-game"
if ($game.isGameRunning) {
    Write-Host "Currently playing: $($game.gameName)"
}

# Shutdown system with 60-second delay
$shutdownRequest = @{
    Action = "shutdown"
    DelaySeconds = 60
    Message = "Scheduled maintenance shutdown"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:5000/api/system/shutdown" -Method Post -Body $shutdownRequest -ContentType "application/json"

🚨 Known Warnings (Non-Critical)

The service may show warnings in VM environments that don't affect functionality:

• Performance Counter Warnings: Some performance counters may not be available in VMs
• Temperature Sensor Access: Some temperature sensors require elevated privileges
• Process Access Denied: Some system processes require elevated privileges to access
• Windows.Forms Compatibility: Game detection works despite .NET Framework compatibility warnings

These warnings are expected in VM environments and the service continues to function normally.

🎯 Perfect for Unraid

This service is specifically optimized for Windows VMs running on Unraid:

• VM Detection: Automatically detects and reports virtualization status
• Resource Monitoring: Tracks VM resource allocation and usage
• Gaming Support: Detects games and monitors performance impact
• Remote Management: Full API control for integration with Unraid dashboard
• Alert System: Configurable alerts for resource thresholds
• Health Monitoring: Comprehensive health checks for VM status

📝 Logging

The service uses Serilog for structured logging:

• Console output for real-time monitoring
• File logging for persistent records
• Configurable log levels (Debug, Information, Warning, Error)
• Smart error suppression to prevent log spam in VM environments

🔐 Security

• Optional API key authentication
• CORS support for web dashboard integration
• Process termination requires explicit API calls
• System shutdown/restart requires explicit API calls
• Configurable allowed origins for API access

📈 Performance

• Lightweight background monitoring (5-second intervals by default)
• Efficient memory usage with smart caching
• Non-blocking async operations
• Graceful error handling for VM-specific limitations
• Configurable monitoring intervals and features

🆘 Support

For issues or questions:

1. Check the console output for warnings/errors
2. Review the configuration in appsettings.json
3. Test individual API endpoints using PowerShell or curl
4. Check Windows Event Logs if running as a service

---

Version: 2.0.0
Target Framework: .NET 9.0
Platforms: Windows (VM optimized)
License: Open Source