diff --git a/.env.example b/.env.example index e591dbf9e..5fb520706 100644 --- a/.env.example +++ b/.env.example @@ -57,6 +57,24 @@ PROXMOX_TOKEN_SECRET=your-api-token-secret-uuid # Interval in milliseconds for fetching structural data (nodes, VM/CT list, storage) (default: 30000) # PULSE_DISCOVERY_INTERVAL_MS=30000 +# --- Alert System Configuration (Optional) --- +# Enable/disable specific alert types (default: true for all) +# ALERT_CPU_ENABLED=true +# ALERT_MEMORY_ENABLED=true +# ALERT_DISK_ENABLED=true +# ALERT_DOWN_ENABLED=true + +# Alert thresholds (percentages, defaults shown) +# ALERT_CPU_THRESHOLD=85 +# ALERT_MEMORY_THRESHOLD=90 +# ALERT_DISK_THRESHOLD=95 + +# Alert durations - how long condition must persist before alerting (milliseconds) +# ALERT_CPU_DURATION=300000 # 5 minutes +# ALERT_MEMORY_DURATION=300000 # 5 minutes +# ALERT_DISK_DURATION=600000 # 10 minutes +# ALERT_DOWN_DURATION=60000 # 1 minute + # --- Development Settings (Optional) --- # Enable/disable hot reloading for frontend changes (default: true) # ENABLE_HOT_RELOAD=true \ No newline at end of file diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md deleted file mode 100644 index 19ee50cd1..000000000 --- a/IMPROVEMENTS.md +++ /dev/null @@ -1,244 +0,0 @@ -# Pulse Application Improvements - -This document outlines the comprehensive improvements made to the Pulse for Proxmox VE monitoring application. - -## 🚀 Major Enhancements - -### 1. Advanced Alert Management System - -#### Real-time Alerting -- **Smart threshold monitoring** for CPU, Memory, Disk usage, and system status -- **Configurable alert rules** with customizable thresholds and durations -- **Multi-severity alerts** (Critical, Warning, Resolved) -- **Real-time notifications** with elegant toast notifications -- **Alert persistence** and history tracking - -#### Alert Features -- **Duration-based triggering**: Alerts only trigger after conditions persist for specified time -- **Automatic resolution**: Alerts auto-resolve when conditions return to normal -- **Visual indicators**: Header badge shows active alert count with color coding -- **Alert modal**: Comprehensive view of active alerts, rules, and statistics -- **WebSocket integration**: Real-time alert updates across all connected clients - -#### Configuration Options -Add these to your `.env` file to customize alert behavior: - -```env -# Alert System Configuration -ALERT_CPU_ENABLED=true -ALERT_MEMORY_ENABLED=true -ALERT_DISK_ENABLED=true -ALERT_DOWN_ENABLED=true - -# Alert thresholds (percentages) -ALERT_CPU_THRESHOLD=85 -ALERT_MEMORY_THRESHOLD=90 -ALERT_DISK_THRESHOLD=95 - -# Alert durations (milliseconds - how long condition must persist) -ALERT_CPU_DURATION=300000 # 5 minutes -ALERT_MEMORY_DURATION=300000 # 5 minutes -ALERT_DISK_DURATION=600000 # 10 minutes -ALERT_DOWN_DURATION=60000 # 1 minute -``` - -### 2. Enhanced Performance Monitoring - -#### Advanced State Management -- **Performance tracking** for discovery and metrics cycles -- **Connection health monitoring** for all Proxmox endpoints -- **Error tracking and reporting** with detailed diagnostics -- **Memory usage monitoring** and peak tracking -- **Response time analytics** with exponential moving averages - -#### Runtime Statistics -- **Guest statistics**: Total, running, stopped counts -- **Node health tracking**: Healthy, warning, error states -- **Average usage calculations**: CPU, Memory, Disk across all guests -- **Performance history**: 24 hours of performance snapshots - -#### New API Endpoints -- `GET /api/health` - Comprehensive health summary -- `GET /api/performance` - Performance metrics and history -- `GET /api/alerts` - Active alerts and statistics -- `GET /api/alerts/history` - Alert history -- `GET /api/alerts/rules` - Alert rule management (GET/POST/PUT/DELETE) - -### 3. Improved User Experience - -#### Enhanced UI Components -- **Alert notifications**: Elegant slide-in notifications with auto-dismiss -- **Connection status**: Enhanced connection indicator with reconnection progress -- **Performance indicators**: Real-time display of system health -- **Alert badge**: Header indicator showing active alert count -- **Modal interfaces**: Clean, accessible alert management interface - -#### Better Error Handling -- **Graceful degradation**: Application continues functioning during partial failures -- **Automatic reconnection**: Smart reconnection with exponential backoff -- **Error reporting**: Detailed error logging and user feedback -- **Connection resilience**: Better handling of network interruptions - -### 4. Code Quality Improvements - -#### Modular Architecture -- **Separated concerns**: Alert management, state management, UI handling -- **Event-driven design**: Loose coupling between components -- **Clean APIs**: Well-defined interfaces between modules -- **Error boundaries**: Isolated error handling prevents cascading failures - -#### Enhanced State Management -- **Centralized state**: Single source of truth for application state -- **Immutable updates**: Safe state updates with proper change detection -- **Performance optimization**: Efficient state updates and UI rendering -- **Memory management**: Proper cleanup and garbage collection - -#### Better Socket Handling -- **Robust reconnection**: Intelligent reconnection with retry limits -- **Event management**: Proper event listener management and cleanup -- **Error handling**: Comprehensive error handling for all socket events -- **Performance optimization**: Efficient data processing and UI updates - -### 5. Enhanced Monitoring Features - -#### Real-time Metrics -- **Continuous monitoring**: Real-time updates for all metrics -- **Historical data**: SQLite-based storage for metrics history -- **Chart enhancements**: Improved chart rendering and performance -- **Smart sampling**: Adaptive data sampling for optimal performance - -#### System Health -- **Endpoint monitoring**: Track health of all Proxmox connections -- **Performance metrics**: Monitor application performance and resource usage -- **Automated diagnostics**: Automatic health checks and reporting -- **Trend analysis**: Historical performance trend tracking - -## 🛠️ Technical Improvements - -### Server-Side Enhancements - -#### Alert Manager (`server/alertManager.js`) -- Event-driven alert system with configurable rules -- Automatic alert lifecycle management -- Historical tracking and cleanup -- Performance-optimized rule evaluation - -#### Enhanced State Manager (`server/state.js`) -- Comprehensive performance tracking -- Connection health monitoring -- Runtime statistics calculation -- Alert integration - -#### Improved Main Server (`server/index.js`) -- New API endpoints for monitoring and alerts -- Enhanced error handling and logging -- Graceful shutdown handling -- WebSocket alert forwarding - -### Client-Side Enhancements - -#### Alert Handler (`src/public/js/alertsHandler.js`) -- Real-time alert notifications -- Alert management interface -- Toast notification system -- WebSocket event handling - -#### Enhanced Socket Handler (`src/public/js/socketHandler.js`) -- Robust connection management -- Automatic reconnection with backoff -- Enhanced error handling -- Performance optimization - -## 📊 Performance Improvements - -### Optimized Data Flow -- **Efficient state updates**: Minimize unnecessary re-renders -- **Smart caching**: Intelligent caching of frequently accessed data -- **Batch processing**: Group related updates for better performance -- **Memory optimization**: Proper cleanup and memory management - -### Enhanced Monitoring -- **Performance tracking**: Monitor application performance in real-time -- **Resource usage**: Track memory and CPU usage patterns -- **Bottleneck identification**: Identify and address performance bottlenecks -- **Optimization metrics**: Measure and improve system efficiency - -## 🔧 Configuration - -### Environment Variables - -The application now supports comprehensive configuration through environment variables: - -```env -# Core Configuration -PORT=7655 -PULSE_METRIC_INTERVAL_MS=2000 -PULSE_DISCOVERY_INTERVAL_MS=30000 - -# Alert Configuration -ALERT_CPU_ENABLED=true -ALERT_CPU_THRESHOLD=85 -ALERT_CPU_DURATION=300000 - -ALERT_MEMORY_ENABLED=true -ALERT_MEMORY_THRESHOLD=90 -ALERT_MEMORY_DURATION=300000 - -ALERT_DISK_ENABLED=true -ALERT_DISK_THRESHOLD=95 -ALERT_DISK_DURATION=600000 - -ALERT_DOWN_ENABLED=true -ALERT_DOWN_DURATION=60000 -``` - -## 🎯 Benefits - -### For Users -- **Proactive monitoring**: Get notified before issues become critical -- **Better visibility**: Enhanced insights into system health and performance -- **Improved reliability**: More robust and resilient monitoring -- **Easier management**: Intuitive interfaces for managing alerts and monitoring - -### For Administrators -- **Reduced downtime**: Early warning system prevents outages -- **Better diagnostics**: Comprehensive performance and health data -- **Easier troubleshooting**: Detailed error reporting and logging -- **Scalable monitoring**: Efficient handling of large environments - -### For Developers -- **Clean architecture**: Well-structured, maintainable codebase -- **Comprehensive APIs**: Rich API set for integration and extension -- **Good documentation**: Clear documentation and examples -- **Testing ready**: Foundation for comprehensive testing - -## 🚀 Getting Started - -1. **Update your installation** to get the latest improvements -2. **Configure alerts** by adding alert settings to your `.env` file -3. **Access new features** through the enhanced UI -4. **Monitor performance** using the new API endpoints -5. **Customize alerting** based on your specific needs - -## 📈 Future Enhancements - -These improvements provide a solid foundation for future enhancements: - -- **External integrations**: Webhook support for external alert systems -- **Advanced analytics**: Machine learning-based anomaly detection -- **Mobile app**: Dedicated mobile application for monitoring -- **Multi-tenancy**: Support for multiple organizations/tenants -- **API extensions**: Additional API endpoints for advanced integration - -## 🤝 Contributing - -The improved architecture makes it easier to contribute: - -- **Modular design**: Easy to add new features without affecting existing code -- **Clear APIs**: Well-defined interfaces for new components -- **Testing framework**: Foundation for comprehensive testing -- **Documentation**: Clear documentation for developers - ---- - -These improvements significantly enhance the Pulse monitoring application, providing a more robust, feature-rich, and user-friendly solution for Proxmox VE monitoring. \ No newline at end of file diff --git a/README.md b/README.md index 5f5772a8b..3b01fa821 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,36 @@ Optional variables: - `PORT`: Port for the Pulse server to listen on. Defaults to `7655`. - *(Username/Password fallback exists but API Token is strongly recommended)* +#### Alert System Configuration (Optional) + +Pulse includes a comprehensive alert system that monitors resource usage and system status: + +```env +# Alert System Configuration +ALERT_CPU_ENABLED=true +ALERT_MEMORY_ENABLED=true +ALERT_DISK_ENABLED=true +ALERT_DOWN_ENABLED=true + +# Alert thresholds (percentages) +ALERT_CPU_THRESHOLD=85 +ALERT_MEMORY_THRESHOLD=90 +ALERT_DISK_THRESHOLD=95 + +# Alert durations (milliseconds - how long condition must persist) +ALERT_CPU_DURATION=300000 # 5 minutes +ALERT_MEMORY_DURATION=300000 # 5 minutes +ALERT_DISK_DURATION=600000 # 10 minutes +ALERT_DOWN_DURATION=60000 # 1 minute +``` + +Alert features include: +- Real-time notifications with toast messages +- Multi-severity alerts (Critical, Warning, Resolved) +- Duration-based triggering (alerts only fire after conditions persist) +- Automatic resolution when conditions normalize +- Alert history tracking + ***Note:** For a Proxmox cluster, you only need to provide connection details for **one** node. Pulse automatically discovers other cluster members.* @@ -461,6 +491,7 @@ For development purposes or running directly from source, see the **[DEVELOPMENT - Lightweight monitoring for Proxmox VE nodes, VMs, and Containers. - Real-time status updates via WebSockets. - Simple, responsive web interface. +- Advanced alert system with configurable thresholds and durations. - Efficient polling: Stops API polling when no clients are connected. - Docker support. - Multi-environment PVE monitoring support.