# Sistema de Prioridades para PLC Recording

## 🔑 Objetivo Principal

**El recording de CSV debe tener MÁXIMA PRIORIDAD** y nunca ser interrumpido por operaciones de API, procesamiento de gráficas, o cualquier otra tarea secundaria.

## 🏗️ Arquitectura de Prioridades

### Niveles de Prioridad

```
CRITICAL (10)    🔥 CSV Recording threads
HIGH (7)         ⚡ PLC communication 
NORMAL (5)       📡 UDP streaming, basic APIs
LOW (3)          📊 Historical data processing
BACKGROUND (1)   📈 Plot generation, file operations
```

### Componentes Implementados

#### 1. `PriorityThreadManager`
- **Función**: Gestiona threads con diferentes prioridades
- **Ubicación**: `core/priority_manager.py`
- **Características**:
  - Recording threads tienen prioridad CRITICAL
  - API operations usan thread pools con prioridad NORMAL/LOW
  - Background tasks (plots, cleanup) usan prioridad BACKGROUND
  - Configuración automática de prioridades a nivel de OS (Windows/Linux)

#### 2. `RecordingProtector`
- **Función**: Protege operaciones de recording mediante rate limiting
- **Características**:
  - Limita APIs a máximo 10 requests/segundo cuando recording está activo
  - Previene sobrecarga del sistema durante recording crítico
  - Monitorea y reporta métricas de protección

#### 3. Thread Separation
- **Recording Threads**: Ejecutan SOLO operaciones de CSV
- **API Thread Pool**: Maneja requests HTTP con prioridad más baja
- **Background Thread Pool**: Procesa tareas no críticas

## 🔥 Protecciones Implementadas

### 1. Recording Thread Protection
```python
# Los threads de recording tienen:
- Prioridad CRITICAL (máxima disponible en el OS)
- No son daemon threads (no se terminan automáticamente)
- Shutdown controlado y seguro
- Separación completa de operaciones UDP/API
```

### 2. API Rate Limiting
```python
# Protección contra sobrecarga de APIs:
- Máximo 10 requests/segundo durante recording
- Timeout de 2 segundos para operaciones de cache
- Rate limiting automático con respuestas HTTP 429
```

### 3. Background Processing
```python
# Operaciones no críticas se ejecutan en background:
- UDP streaming a PlotJuggler
- Actualización de gráficas en tiempo real
- Cleanup de archivos CSV
- Procesamiento de datos históricos
```

## 📊 Monitoreo y Métricas

### Endpoint de Status: `/api/priority/status`
```json
{
  "success": true,
  "priority_protection": {
    "csv_recording_enabled": true,
    "priority_stats": {
      "active_recording_threads": 2,
      "recording_thread_names": ["Fast:recording_fast", "DAR:recording_dar"],
      "api_pool_active": 2,
      "background_pool_active": 1
    },
    "recording_protection": {
      "recording_protection_active": true,
      "api_requests_this_second": 3,
      "api_rate_limit": 10,
      "time_until_reset": 0.7
    }
  }
}
```

### Logs de Prioridad
```
🔥 CRITICAL PRIORITY: Dataset 'Fast' recording loop started (interval: 0.1s)
🔥 [2025-08-16 15:30:25.123] RECORDING Dataset 'Fast': 15 vars recorded
📡 Background: UDP sent 8 vars for dataset 'Fast'
📈 Background: Plot data updated for session abc123
```

## 🛡️ Garantías de Protección

### 1. Recording Never Stops
- **Thread isolation**: Recording threads completamente separados
- **OS Priority**: Máxima prioridad a nivel de sistema operativo
- **Resource protection**: Rate limiting de APIs para evitar competencia

### 2. Graceful Degradation
- **API timeout**: APIs responden con error si exceden tiempo límite
- **Rate limiting**: APIs se limitan automáticamente durante recording
- **Background processing**: Tareas no críticas se postergan

### 3. System Monitoring
- **Real-time stats**: Métricas en tiempo real de threads y protección
- **Logging detallado**: Logs específicos para operaciones críticas
- **Health checks**: Endpoints para verificar estado del sistema

## 🚀 Uso en Producción

### Configuración Automática
```python
# El sistema se configura automáticamente al inicializar:
streamer = PLCDataStreamer()
# - PriorityThreadManager configurado
# - RecordingProtector activado
# - Thread pools separados creados
# - Prioridades de OS configuradas
```

### APIs Protegidas
```python
# Estas APIs ahora usan protección de prioridad:
GET /api/datasets/{id}/variables/values  # Rate limited
POST /api/csv/cleanup                     # Background processing
GET /api/priority/status                  # Monitoring
```

### Shutdown Seguro
```python
# Shutdown respeta prioridades:
1. Para CSV recording gracefully
2. Para UDP streaming
3. Espera threads de recording (timeout 10s)
4. Cierra thread pools de API/background
5. Limpia recursos
```

## 📋 Checklist de Funcionamiento

### ✅ Recording Protection Active
- [ ] CSV recording threads tienen prioridad CRITICAL
- [ ] APIs limitadas a 10 req/s durante recording
- [ ] Background tasks no bloquean recording
- [ ] Logs muestran "🔥 CRITICAL PRIORITY"

### ✅ System Health
- [ ] `/api/priority/status` responde correctamente
- [ ] Recording threads aparecen en stats
- [ ] Rate limiting funciona (HTTP 429 cuando excede)
- [ ] Background tasks se ejecutan sin bloquear

### ✅ Performance Monitoring
- [ ] Recording intervals se mantienen estables
- [ ] No hay errores de timeout en recording
- [ ] APIs responden dentro de 2 segundos
- [ ] Cleanup se ejecuta en background

## 🔧 Troubleshooting

### Recording Lento
1. Verificar `/api/priority/status` - ¿threads críticos activos?
2. Revisar logs - ¿aparecen mensajes "🔥 CRITICAL"?
3. Comprobar rate limiting - ¿muchas APIs simultáneas?

### APIs Lentas
1. Verificar rate limiting en `/api/priority/status`
2. Reducir frecuencia de requests de frontend
3. Usar cache del browser para datos estáticos

### Threads Bloqueados
1. Revisar stats de thread pools
2. Verificar que recording threads no sean daemon
3. Comprobar shutdown order en logs

## 📚 Referencias

- `core/priority_manager.py`: Implementación completa del sistema
- `core/streamer.py`: Integration con DataStreamer
- `main.py`: APIs protegidas con rate limiting
- `application_events.json`: Logs de eventos de prioridad