Troubleshooting Hub

Guía completa para diagnosticar y resolver problemas comunes en Fracttal ETL Hub.

Diagnóstico Rápido

¿Cuál es tu problema?

• Problemas de Conexión

  ---

  Timeouts, autenticación fallida, conexiones rechazadas

  Ver soluciones

• Errores de Datos

  ---

  Esquemas inválidos, transformaciones fallidas, tipos incorrectos

  Ver soluciones

• Performance Issues

  ---

  ETLs lentos, timeouts, memoria alta, CPU alta

  Ver soluciones

• Configuración JSON

  ---

  Sintaxis incorrecta, parámetros faltantes, validación fallida

  Ver soluciones

---

Problemas de Conexión

Connection Timeout

Síntomas:

{
  "error": "Connection timeout after 30 seconds",
  "code": "TIMEOUT_ERROR",
  "connection": "my_database"
}

Causas Comunes:

Causa	Diagnóstico	Solución
Firewall bloqueando	No hay conectividad de red	Abrir puertos necesarios
Credenciales incorrectas	Error de autenticación	Verificar usuario/password
Servidor sobrecargado	Respuesta lenta del servidor	Aumentar timeout o usar horarios off-peak
Red lenta	Alta latencia	Optimizar query o usar batch processing

Soluciones:

Configuración de Timeout

{
  "source": {
    "id_type": 1,
    "id_connection": "my_database",
    "parameters": {
      "timeout": 60,          // Aumentar a 60 segundos
      "connect_timeout": 30,  // Timeout de conexión
      "read_timeout": 45      // Timeout de lectura
    }
  }
}

Retry Policy

{
  "source": {
    "id_type": 1,
    "id_connection": "my_database",
    "parameters": {
      "retry_policy": {
        "max_retries": 3,
        "backoff_factor": 2,
        "retry_delays": [1, 3, 6]
      }
    }
  }
}

Connection Pooling

{
  "source": {
    "id_type": 1,
    "id_connection": "my_database",
    "parameters": {
      "pool_size": 5,
      "max_overflow": 10,
      "pool_timeout": 30
    }
  }
}

Authentication Failed

Síntomas:

{
  "error": "Authentication failed: Invalid credentials",
  "code": "AUTH_ERROR"
}

Lista de verificación:

• Usuario existe en el sistema destino
• Password es correcto (no expirado)
• Permisos suficientes para leer/escribir
• IP whitelisted en el servidor
• Protocolo correcto (SSL/TLS si es requerido)

Soluciones por tipo de conexión:

Database

{
  "id_connection": "secure_db",
  "host": "db.company.com",
  "port": 5432,
  "database": "production",
  "username": "etl_user",
  "password": "secure_password",
  "ssl_mode": "require",  // Para conexiones seguras
  "connect_timeout": 30
}

API REST

{
  "id_connection": "api_service",
  "base_url": "https://api.company.com",
  "auth_type": "bearer",
  "token": "valid_bearer_token",
  "headers": {
    "User-Agent": "Fracttal-ETL/1.0",
    "Accept": "application/json"
  }
}

Google Sheets

{
  "id_connection": "google_sheets",
  "auth_type": "service_account",
  "service_account_email": "etl@project.iam.gserviceaccount.com",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "scopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive.file"
  ]
}

---

Errores de Datos

Schema Validation Failed

Síntomas:

{
  "error": "Schema validation failed",
  "details": {
    "field": "created_date",
    "expected": "datetime",
    "received": "string"
  }
}

Soluciones comunes:

Conversión de Tipos

{
  "transform": {
    "map": [
      {"var": ""},
      {
        "merge": [
          {"var": ""},
          {
            "created_date": {
              "format_date": [
                {"var": "created_date"},
                "%Y-%m-%d %H:%M:%S",
                "%Y-%m-%dT%H:%M:%S.%fZ"
              ]
            }
          }
        ]
      }
    ]
  }
}

Validación de Campos

{
  "transform": {
    "filter": [
      {"var": ""},
      {
        "and": [
          {"!=": [{"var": "id"}, null]},
          {"!=": [{"var": "name"}, ""]},
          {">": [{"var": "amount"}, 0]}
        ]
      }
    ]
  }
}

Campos Faltantes

{
  "transform": {
    "map": [
      {"var": ""},
      {
        "merge": [
          {"var": ""},
          {
            "status": {"or": [{"var": "status"}, "pending"]},
            "created_at": {"or": [{"var": "created_at"}, {"format_date": ["now", "%Y-%m-%dT%H:%M:%SZ"]}]}
          }
        ]
      }
    ]
  }
}

Data Transformation Error

Síntomas:

{
  "error": "Transformation failed at step 3",
  "step": "format_date",
  "input": "invalid-date-string"
}

Debugging paso a paso:

1. Verificar datos de entrada

   {
     "transform": {
       "debug": [
         {"var": ""},
         {"message": "Input data", "level": "info"}
       ]
     }
   }
   

2. Transformación segura con fallbacks

   {
     "transform": {
       "map": [
         {"var": ""},
         {
           "merge": [
             {"var": ""},
             {
               "safe_date": {
                 "if": [
                   {"and": [
                     {"!=": [{"var": "date_field"}, null]},
                     {"!=": [{"var": "date_field"}, ""]}
                   ]},
                   {"format_date": [{"var": "date_field"}, "%Y-%m-%d", "%Y-%m-%dT%H:%M:%SZ"]},
                   null
                 ]
               }
             }
           ]
         }
       ]
     }
   }
   

---

Performance Issues

ETL Muy Lento

Síntomas: - ETL que toma > 5 minutos para < 10K registros - Uso de memoria > 1GB - CPU al 100% durante la ejecución

Diagnóstico:

Métrica	Normal	Problemático	Acción
Tiempo/1K registros	< 2s	> 10s	Optimizar query
Memoria usada	< 512MB	> 1GB	Activar batch processing
Registros/segundo	> 500	< 100	Revisar transformaciones

Optimizaciones:

Query Optimization

{
  "source": {
    "parameters": {
      "query_string": {
        "table": "orders",
        "fields": "id,name,amount,created_at",  // Solo campos necesarios
        "where": "created_at >= '2024-01-01'",  // Filtrar en origen
        "order_by": "id ASC",
        "limit": 5000  // Limitar resultados
      }
    }
  }
}

Batch Processing

{
  "target": {
    "parameters": {
      "batch": true,
      "batch_size": 100,
      "parallel_workers": 4
    }
  }
}

Memory Optimization

{
  "extract": {
    "apply_jsonpath": "$.data[*]",  // Reducir datos en memoria
    "streaming": true,              // Procesar en chunks
    "chunk_size": 1000
  }
}

Rate Limiting

Síntomas:

{
  "error": "Rate limit exceeded: 100 requests per minute",
  "retry_after": 60
}

Soluciones:

Request Throttling

{
  "target": {
    "parameters": {
      "rate_limit": {
        "requests_per_minute": 50,
        "burst_limit": 10,
        "backoff_strategy": "exponential"
      }
    }
  }
}

Batch Requests

{
  "target": {
    "parameters": {
      "batch": true,
      "batch_size": 50,  // Enviar múltiples registros por request
      "concurrent_requests": 2
    }
  }
}

---

Configuración JSON

JSON Syntax Error

Errores comunes:

Comas faltantes

// ❌ Incorrecto
{
  "source": {
    "id_type": 1
    "id_connection": "db"  // Falta coma
  }
}

// ✅ Correcto
{
  "source": {
    "id_type": 1,
    "id_connection": "db"
  }
}

Quotes incorrectas

// ❌ Incorrecto
{
  'source': {  // Comillas simples no válidas
    "id_type": 1
  }
}

// ✅ Correcto
{
  "source": {
    "id_type": 1
  }
}

Trailing commas

// ❌ Incorrecto
{
  "source": {
    "id_type": 1,
    "id_connection": "db",  // Coma final no válida
  }
}

// ✅ Correcto
{
  "source": {
    "id_type": 1,
    "id_connection": "db"
  }
}

Herramientas de Validación

1. JSON Validator Online: jsonlint.com
2. VS Code Extension: JSON Schema validator
3. CLI Tool: fracttal-etl validate config.json

---

Escalación de Problemas

Cuándo contactar soporte:

• Has seguido esta guía sin éxito
• Error persiste después de 3 intentos
• Problema afecta producción
• Datos críticos no se procesan

Información a incluir:

## Descripción del Problema
- Qué ETL está fallando
- Cuándo empezó el problema
- Frecuencia del error

## Configuración
```json
{
  // Tu configuración JSON completa (sin credenciales)
}

Logs de Error

[Timestamp] ERROR: Mensaje completo del error
[Timestamp] STACK: Stack trace si está disponible

Entorno

• Ambiente: production/staging/development
• Volumen de datos: X registros
• Tiempo de ejecución esperado vs actual ```

Canales de soporte:

• Emergencias: emergency@fracttal.com
• Slack: #etl-support
• Email: tech@fracttal.com
• Issues: GitHub Issues

---

Recursos Adicionales

• Performance Optimization
• Monitoring Best Practices
• Error Handling Patterns
• Security Guidelines