# autoSMART v1.0 - Intelligent HDD Monitoring & Failure Prediction

autoSMART este un sistem inteligent de monitorizare SMART pentru HDD-urile din cluster-ul Proxmox, cu predicții de defectare bazate pe AI și stocare optimizată în PostgreSQL.

## 🎯 **Scopul Proiectului**

- **Monitorizare continuă** a parametrilor SMART pentru toate HDD-urile din cluster
- **Predicții AI** pentru defectări iminente folosind OpenAI API
- **Stocare long-term** în PostgreSQL pentru analize temporale
- **Alerting proactiv** pentru mentenanță preventivă

## Key Features

- **🔍 Hardware-based HDD tracking**: Permanent identification using serial numbers and model names (not volatile /dev/sdX paths)
- **🔄 Migration detection**: Automatic detection and logging when HDDs move between nodes or device paths
- **💾 Differential storage optimization**: Store only SMART readings with changes, reducing database size by 60-80%
- **🤖 AI-powered failure prediction**: Uses OpenAI GPT for intelligent drive failure forecasting
- **🏥 Health monitoring**: Continuous SMART parameter analysis with configurable thresholds
- **📊 Comprehensive reporting**: Detailed drive health reports and predictive analytics
- **🔧 Proxmox cluster integration**: Designed for distributed Proxmox VE environments
- **⚡ High performance**: PostgreSQL backend with optimized indexing and queries

## 🚀 Quick Start

### Prerequisites
- **PostgreSQL 13+** for data storage
- **Perl 5.20+** with required modules
- **Proxmox VE** cluster environment
- **smartmontools** for SMART data collection
- **OpenAI API key** for failure predictions

### Installation
```bash
# 1. Download autoSMART and run automated deployment
git clone <repository-url>
cd autoSMART
sudo ./scripts/deploy.sh install

# The deployment script automatically:
# - Installs all dependencies (Perl modules, smartmontools, etc.)
# - Creates system directories and sets permissions
# - Deploys application files to /opt/autoSMART/
# - Creates configuration files in /etc/autosmart/
# - Registers and starts systemd services
# - Performs initial system validation

# 2. Configure database connection (interactive prompts during install)
# 3. Configure OpenAI API key (interactive prompts during install)
# 4. System is ready - services are automatically started
```

### Verification
```bash
# Check system status (all services should be active)
sudo systemctl status autosmart

# View recent SMART data collection
sudo journalctl -u autosmart-collector -f

# Generate initial health report
sudo /opt/autoSMART/scripts/autosmart-report.pl --summary
```

## 📚 Documentation

### Getting Started
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes

### System Configuration
- **[API.md](API.md)** - OpenAI API integration and configuration

## 🏥 Monitoring Dashboard

autoSMART provides comprehensive monitoring capabilities:

### Health Status Overview
- Real-time drive health status for all cluster nodes
- Critical parameter alerts and warnings
- AI-powered failure predictions with confidence scores
- Storage efficiency metrics

### Historical Analysis
- Long-term SMART parameter trends
- Performance degradation tracking
- Migration history between nodes
- Predictive analytics reports

### Alerting System
- Configurable thresholds for all SMART parameters
- Email/webhook notifications
- Integration with monitoring systems
- Escalation procedures for critical alerts

## 🔧 System Architecture

autoSMART operates as a distributed system across your Proxmox cluster:

### Data Collection
- Continuous SMART data collection from all nodes
- Hardware-based drive identification
- Migration detection and logging
- Differential storage for efficiency

### Analysis Engine
- AI-powered failure prediction
- Threshold-based alerting
- Trend analysis and reporting
- Performance optimization recommendations

### Storage Layer
- PostgreSQL database with optimized schema
- Differential storage reducing size by 60-80%
- Historical data retention policies
- Automated backup and maintenance

## 📁 Installed File Structure

When autoSMART is installed on your system, it creates the following directory structure:

### System Directories

```
/opt/autoSMART/                    # Main installation directory
├── scripts/                      # Executable scripts and utilities
│   ├── autosmart-collector.pl    # Main data collection daemon
│   ├── autosmart-predictor.pl    # AI prediction processing
│   ├── autosmart-report.pl       # Report generation engine
│   ├── autosmart-migration-report.pl # Hardware migration analysis
│   ├── smart-collector-daemon.pl # Background collection service
│   ├── uninstall.sh             # System removal script
│   ├── monitor-cluster.sh        # Cluster health monitoring
│   └── test-*.pl                # Testing and validation utilities
├── lib/                         # Perl modules and core libraries
│   ├── SmartCollector.pm        # SMART data collection and hardware tracking
│   └── PredictionEngine.pm      # AI-powered failure prediction engine
├── config/                      # Configuration templates and examples
│   └── (template files)        # Default configuration templates
├── docs/                        # End-user documentation
│   ├── README.md               # System overview and quick start
│   ├── CHANGELOG.md            # Release notes and version history
│   └── API.md                  # OpenAI API configuration guide

/etc/autosmart/                   # System configuration directory
├── autosmart.conf              # Main system configuration
├── cluster.conf                # Cluster topology and node definitions
├── database.conf               # PostgreSQL connection settings
├── openai.conf                 # OpenAI API configuration and prompts
└── smart.conf                  # SMART parameter thresholds and monitoring rules

/etc/systemd/system/             # Systemd service files
├── autosmart.service           # Main autoSMART service
├── autosmart-collector.service # Data collection service
└── autosmart-predictor.service # AI prediction service
```

### Configuration Files Detail

#### `/etc/autosmart/autosmart.conf`
Main system configuration file containing:
- Database connection parameters
- Collection intervals and scheduling
- Local node identification and settings
- Log levels and debugging options

#### `/etc/autosmart/cluster.conf`
Cluster-wide configuration shared across all nodes:
- Node topology and IP addresses
- Shared monitoring parameters
- Cluster-wide alert settings
- Inter-node communication settings

#### `/etc/autosmart/database.conf`
PostgreSQL database connection settings:
- Database host, port, and credentials
- Connection pooling configuration
- SSL settings and security parameters
- Performance tuning options

#### `/etc/autosmart/openai.conf`
OpenAI API integration configuration:
- API key and model selection
- Prompt templates for failure prediction
- Response parsing and confidence thresholds
- Rate limiting and cost management

#### `/etc/autosmart/smart.conf`
SMART parameter monitoring configuration:
- Parameter thresholds for different drive types
- Critical parameter definitions
- Alert escalation rules and notifications
- Drive-specific monitoring settings

### Service Integration

#### Systemd Services
- **`autosmart.service`**: Main system service that manages other components
- **`autosmart-collector.service`**: Background data collection service
- **`autosmart-predictor.service`**: AI prediction processing service

#### Service Management
```bash
# Start/stop services
sudo systemctl start autosmart
sudo systemctl stop autosmart

# Enable/disable automatic startup
sudo systemctl enable autosmart
sudo systemctl disable autosmart

# Check service status
sudo systemctl status autosmart

# View service logs using systemd journal
sudo journalctl -u autosmart -f                    # Follow main service logs
sudo journalctl -u autosmart-collector -f          # Follow data collection logs  
sudo journalctl -u autosmart-predictor -f          # Follow AI prediction logs

# View logs by time period
sudo journalctl -u autosmart --since "1 hour ago"  # Last hour
sudo journalctl -u autosmart --since today         # Today's logs
sudo journalctl -u autosmart --since yesterday     # Yesterday's logs

# View logs by priority level
sudo journalctl -u autosmart -p err                # Error level and above
sudo journalctl -u autosmart -p warning            # Warning level and above
```

### File Permissions

#### Executable Files
- All scripts in `/opt/autoSMART/scripts/` are executable (755)
- Perl modules in `/opt/autoSMART/lib/` are readable (644)
- Configuration files in `/etc/autosmart/` are readable by autosmart user (640)

#### Log Management
- All application logs are handled by systemd journal
- No separate log files created in filesystem
- Log retention managed by journald configuration
- Logs accessible via `journalctl` commands
- Automatic log rotation and cleanup by systemd

### Storage Requirements

#### Disk Space
- **Installation**: ~50MB for application files and documentation
- **Configuration**: ~1MB for all configuration files
- **Logs**: Managed by systemd journal (configurable retention)
- **Database**: Handled separately on PostgreSQL server

#### Network Requirements
- **Database Access**: Persistent connection to PostgreSQL server
- **OpenAI API**: HTTPS access for AI predictions (configurable)
- **Inter-node Communication**: SSH access between cluster nodes for deployment

This file structure provides a complete, organized installation that integrates seamlessly with Linux system conventions while maintaining clear separation between application code, configuration, and operational data.

## 📊 Performance Benefits

### Storage Optimization
- **60-80% reduction** in database storage through differential storage
- **Intelligent change detection** stores only modified SMART parameters
- **Baseline reconstruction** provides complete historical views
- **Configurable retention** policies for long-term storage

### Monitoring Efficiency
- **Hardware-based tracking** eliminates /dev/sdX path volatility
- **Migration detection** automatically tracks drive movements
- **Real-time analysis** with configurable collection intervals
- **Distributed architecture** scales across cluster nodes

## 🚨 Alert Examples

### Critical Alerts
- **Imminent Failure**: AI predicts drive failure within 24-48 hours
- **Temperature Critical**: Drive operating above safe temperature thresholds
- **Reallocated Sectors**: Increasing bad sector count detected
- **Spin Retry Count**: Mechanical issues detected

### Warning Alerts
- **Performance Degradation**: Slower response times detected
- **Temperature Warning**: Operating temperatures approaching limits
- **SMART Threshold**: Parameters approaching warning thresholds
- **Migration Detected**: Drive moved to different node or path

## 💡 Use Cases

### Preventive Maintenance
- Schedule drive replacements before failures occur
- Optimize workload distribution based on drive health
- Plan cluster maintenance windows effectively
- Track warranty and replacement schedules

### Capacity Planning
- Monitor storage growth trends
- Predict future storage requirements
- Optimize drive allocation across nodes
- Plan cluster expansion timing

### Performance Optimization
- Identify performance bottlenecks
- Balance load across healthy drives
- Optimize I/O patterns based on drive characteristics
- Monitor storage tier performance

## 🆘 Support & Troubleshooting

### Common Issues
- **Collection failures**: Check smartmontools installation
- **Database connectivity**: Verify PostgreSQL connection settings
- **API errors**: Validate OpenAI API key and quotas
- **Performance issues**: Review differential storage configuration

### Log Analysis
Use systemd journal for comprehensive log analysis:
- **All service logs**: `sudo journalctl -u autosmart*`
- **Data collection**: `sudo journalctl -u autosmart-collector`
- **AI predictions**: `sudo journalctl -u autosmart-predictor`
- **System errors**: `sudo journalctl -u autosmart* -p err`

### Getting Help
For detailed installation, configuration, and troubleshooting information, refer to the complete documentation in the `docs/` directory.

---

**autoSMART v1.0** - Intelligent drive monitoring for mission-critical infrastructure