TransferData-main/Documentacion/Manejo_de_Errores.md

Manejo de Errores

Clasificación de Errores

DataTransferV2 clasifica los errores en tres categorías principales con diferentes impactos en el pipeline.

Estados de Ejecución

SUCCESS (✅)

Definición: Ejecución completamente exitosa Condiciones:

• Datos encontrados en base de datos
• Archivo Excel generado correctamente
• Todos los destinos de distribución exitosos

Ejemplo:

✅ Cobertura-2024-01-15: 1,500 registros procesados, FTP+SharePoint OK

COMPLETED_WITH_ERRORS (⚠️)

Definición: Datos procesados pero con fallos en distribución Condiciones:

• Datos encontrados y Excel generado
• Al menos un destino de distribución falló
• Otros destinos pueden haber sido exitosos

Impacto: No detiene el pipeline, continúa con siguientes reportes

Ejemplo:

⚠️ Checkout-2024-01-15: Datos OK, FTP falló (timeout), SharePoint OK

WARNING (ℹ️)

Definición: Sin datos disponibles Condiciones:

• Query ejecutada correctamente
• 0 registros retornados
• No se genera archivo Excel

Reglas de negocio:

• Si es domingo + sin datos → Ignorado
• 3+ warnings consecutivos → Se eleva a FAILED

Ejemplo:

ℹ️ Promociones-2024-01-15: Sin datos disponibles

FAILED (❌)

Definición: Fallo crítico que detiene el procesamiento Condiciones:

• Error en conexión a base de datos
• Error en query SQL
• Error en generación de Excel
• 3+ warnings consecutivos en mismo reporte

Impacto: Detiene procesamiento del reporte actual

Ejemplo:

❌ QualityDisplay-2024-01-15: Error de conexión DB - timeout

Tipos de Errores Técnicos

Errores de Base de Datos

Connection Timeout

Error: [08001] [Microsoft][ODBC SQL Server Driver]Timeout expired
Causa: Red lenta, servidor sobrecargado
Solución: Reintentar, verificar conectividad

Authentication Failed

Error: [28000] [Microsoft][ODBC SQL Server Driver]Login failed
Causa: Credenciales incorrectas
Solución: Verificar USERNAME/PASSWORD en config

Database Not Found

Error: [08004] [Microsoft][ODBC SQL Server Driver]Server does not exist
Causa: Servidor incorrecto o no accesible
Solución: Verificar SERVER en config

Query Syntax Error

Error: [42000] [Microsoft][ODBC SQL Server Driver]Incorrect syntax
Causa: Nombre de tabla/columna incorrecto
Solución: Verificar configuración de reportes

Errores de FTP

Connection Failed

Error: [Errno 110] Connection timed out
Causa: Firewall, red bloqueada
Solución: Verificar host/puerto, permisos de red

Authentication Failed

Error: 530 Login incorrect
Causa: Credenciales FTP incorrectas
Solución: Verificar FTP_CONFIG

Permission Denied

Error: 550 Permission denied
Causa: Usuario sin permisos de escritura
Solución: Verificar permisos en servidor FTP

Disk Full

Error: 452 Insufficient storage space
Causa: Espacio insuficiente en servidor
Solución: Liberar espacio, contactar administrador

Errores de SFTP

SSH Connection Failed

Error: [Errno 61] Connection refused
Causa: Puerto cerrado, servidor no responde
Solución: Verificar host/puerto SFTP

Host Key Verification

Error: Host key verification failed
Causa: Primera conexión, clave host no conocida
Solución: Agregar host a known_hosts o usar policy

File Transfer Error

Error: Permission denied (publickey,password)
Causa: Autenticación fallida
Solución: Verificar credenciales SFTP

Errores de SharePoint

Authentication Failed

Error: Invalid client credentials
Causa: client_id/tenant_id incorrectos
Solución: Verificar configuración Azure AD

Permission Denied

Error: Access denied
Causa: Usuario sin permisos en site/library
Solución: Verificar permisos en SharePoint

File Upload Failed

Error: The file exists
Causa: Archivo ya existe, no se puede sobrescribir
Solución: Verificar configuración de sobrescritura

Errores de Sistema

Disk Full

Error: [Errno 28] No space left on device
Causa: Disco local lleno
Solución: Liberar espacio, verificar partición

Memory Error

Error: MemoryError
Causa: DataFrame muy grande
Solución: Optimizar query, procesar en lotes

Encoding Error

Error: 'utf-8' codec can't decode byte
Causa: Datos con caracteres especiales
Solución: Especificar encoding correcto

Estrategias de Recuperación

Reintentos Automáticos

def retry_operation(operation, max_retries=3, delay=5):
    for attempt in range(max_retries):
        try:
            return operation()
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(delay * (attempt + 1))  # Backoff exponencial
            else:
                raise e

Aplicado a:

• Conexiones de red (FTP, SFTP, SharePoint)
• Queries de base de datos
• Uploads de archivos

Fallback Strategies

1. Múltiples Destinos: Si FTP falla, intentar SFTP
2. Modo Degradado: Continuar sin notificaciones si webhook falla
3. Cache Local: Guardar archivos localmente si uploads fallan

Circuit Breaker

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=300):
        self.failure_count = 0
        self.last_failure_time = None
        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN
    
    def call(self, func):
        if self.state == 'OPEN':
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = 'HALF_OPEN'
            else:
                raise CircuitBreakerError("Circuit is OPEN")
        
        try:
            result = func()
            self._on_success()
            return result
        except Exception as e:
            self._on_failure()
            raise e

Logging y Monitoreo

Niveles de Log

• DEBUG: Detalles técnicos, queries ejecutadas
• INFO: Progreso normal, estadísticas
• WARNING: Situaciones no críticas
• ERROR: Errores que requieren atención
• CRITICAL: Errores que detienen el sistema

Formato de Logs

2024-01-15 08:30:15,123 - ETL - INFO - Starting ETL for PG project
2024-01-15 08:30:16,456 - DB - DEBUG - Executing query: SELECT * FROM Cobertura WHERE Fecha = '2024-01-15'
2024-01-15 08:30:18,789 - REPORT - INFO - Generated Excel: Reportes/PG/Cobertura/Cobertura-20240115.xlsx
2024-01-15 08:30:20,012 - FTP - ERROR - Upload failed: Connection timeout
2024-01-15 08:30:25,345 - FTP - INFO - Retry 1/3 successful

Base de Datos de Auditoría

Cada error se registra en ExecutionLog:

INSERT INTO ExecutionLog (
    ProcedureID, StartTime, EndTime, Status, 
    ErrorType, ErrorMessage, RetryCount
) VALUES (
    1001, '2024-01-15 08:30:15', '2024-01-15 08:30:25', 'COMPLETED_WITH_ERRORS',
    'FTP_TIMEOUT', 'Connection timed out after 30s', 1
)

Alertas y Notificaciones

Umbrales de Alerta

• Error Rate > 10%: Notificación inmediata
• 3+ fallos consecutivos: Alerta crítica
• Tiempo de ejecución > 2x promedio: Warning
• Disco > 90% usado: Alerta de capacidad

Canales de Notificación

1. WhatsApp: Resúmenes diarios
2. Email: Alertas críticas
3. Logs: Registro detallado
4. Dashboard: Métricas en tiempo real (futuro)

Debugging

Herramientas de Diagnóstico

Verificar Conectividad

# Base de datos
sqlcmd -S sql.glmanalytics.com -U $USERNAME -P $PASSWORD -Q "SELECT 1"

# FTP
ftp $FTP_HOST

# SFTP
sftp $SFTP_USER@$SFTP_HOST

Analizar Logs

# Últimos errores
tail -f Logs/etl.log | grep ERROR

# Errores por tipo
grep "ERROR" Logs/etl.log | cut -d' ' -f4 | sort | uniq -c

Probar Componentes Individualmente

# Probar DB
from App.Utils.db_utils import DatabaseManager
db = DatabaseManager()
data = db.execute_query("SELECT TOP 1 * FROM Cobertura")

# Probar FTP
from App.Utils.ftp_utils import FTPManager
ftp = FTPManager()
ftp.test_connection()

Checklist de Troubleshooting

• Credenciales correctas en config
• Servidores accesibles (ping, telnet)
• Puertos abiertos (1433 DB, 21 FTP, 22 SFTP, 443 HTTPS)
• Espacio en disco suficiente
• Permisos de archivo correctos
• Dependencias Python instaladas
• Zona horaria correcta
• Configuración de reportes válida

Mejores Prácticas

Prevención

1. Validación de Configuración: Verificar al inicio
2. Health Checks: Monitorear componentes críticos
3. Backup: Mantener copias de configuraciones
4. Versionado: Control de cambios en config

Respuesta

1. Documentar Incidentes: Registrar causa y resolución
2. Automatizar Recuperación: Scripts para reintentos
3. Escalada: Definir cuándo notificar a equipo
4. Post-mortem: Análisis después de incidentes críticos

Mejora Continua

1. Métricas: Recopilar estadísticas de errores
2. Análisis de Tendencias: Identificar patrones
3. Optimización: Reducir puntos de fallo
4. Testing: Cobertura de escenarios de error