Hub de Solução de Problemas

Guia completo para diagnosticar e resolver problemas comuns no Fracttal ETL Hub.

Diagnóstico Rápido

Qual é o seu problema?

Problemas de Conexão

Timeouts, falha de autenticação, conexões recusadas

Ver soluções
Erros de Dados

Esquemas inválidos, transformações falhas, tipos incorretos

Ver soluções
Problemas de Performance

ETLs lentos, timeouts, alta memória, alta CPU

Ver soluções
Configuração JSON

Sintaxe incorreta, parâmetros ausentes, validação falha

Ver soluções

Problemas de Conexão

Timeout de Conexão

Sintomas:

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

Causas Comuns:

Causa	Diagnóstico	Solução
Firewall bloqueando	Sem conectividade de rede	Abrir portas necessárias
Credenciais incorretas	Erro de autenticação	Verificar usuário/senha
Servidor sobrecarregado	Resposta lenta do servidor	Aumentar timeout ou usar horários off-peak
Rede lenta	Alta latência	Otimizar query ou usar batch processing

Soluções:

Configuração de Timeout

{
  "source": {
    "id_type": 1,
    "host": "seu-banco.com",
    "timeout": 60,
    "connection_timeout": 30,
    "read_timeout": 120
  }
}

Pool de Conexão

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

Estratégia de Retry

{
  "source": {
    "id_type": 1,
    "retry_attempts": 3,
    "retry_delay": 5,
    "backoff_factor": 2
  }
}

Falha de Autenticação

Sintomas:

{
  "error": "Access denied for user 'etl_user'@'host'",
  "code": "AUTH_ERROR"
}

Soluções:

Conexões de Banco:

-- Conceder permissões necessárias
GRANT SELECT, INSERT, UPDATE ON database.* TO 'etl_user'@'%';
FLUSH PRIVILEGES;

Conexões de API:

{
  "source": {
    "id_type": 2,
    "authentication": {
      "type": "bearer",
      "token": "seu-token-valido"
    }
  }
}

Conexão Recusada

Sintomas:

{
  "error": "Connection refused to localhost:3306",
  "code": "CONNECTION_REFUSED"
}

Passos de Diagnóstico:

Verificar status do serviço:

# MySQL
sudo systemctl status mysql

# PostgreSQL
sudo systemctl status postgresql

Verificar disponibilidade da porta:

netstat -tlnp | grep :3306
telnet seu-host 3306

Verificar regras de firewall:

# Ubuntu/Debian
sudo ufw status

# CentOS/RHEL
sudo firewall-cmd --list-all

Erros de Dados

Falha na Validação de Esquema

Sintomas:

{
  "error": "Column 'campo_esperado' not found in source data",
  "code": "SCHEMA_ERROR",
  "expected": ["id", "nome", "email"],
  "received": ["id", "nome_completo", "endereco_email"]
}

Soluções:

Mapeamento de Campos

{
  "transform": [
    {
      "rename": {
        "nome_completo": "nome",
        "endereco_email": "email"
      }
    }
  ]
}

Esquema Dinâmico

{
  "source": {
    "id_type": 1,
    "form": {
      "sql": "SELECT id, nome_completo as nome, endereco_email as email FROM usuarios"
    }
  }
}

Validação de Esquema

{
  "transform": [
    {
      "validate_schema": {
        "required_fields": ["id", "nome", "email"],
        "action_on_missing": "fill_default"
      }
    }
  ]
}

Incompatibilidade de Tipo de Dados

Sintomas:

{
  "error": "Cannot convert 'abc' to integer",
  "code": "TYPE_ERROR",
  "field": "idade",
  "value": "abc",
  "expected_type": "integer"
}

Soluções:

Conversão de Tipo

{
  "transform": [
    {
      "convert_type": {
        "field": "idade",
        "from_type": "string",
        "to_type": "integer",
        "default_value": 0
      }
    }
  ]
}

Limpeza de Dados

{
  "transform": [
    {
      "clean_data": {
        "field": "telefone",
        "remove_chars": ["-", "(", ")", " "],
        "format": "numbers_only"
      }
    }
  ]
}

Campos Obrigatórios Ausentes

Sintomas:

{
  "error": "Required field 'customer_id' is null or missing",
  "code": "REQUIRED_FIELD_ERROR"
}

Soluções:

Valores Padrão

{
  "transform": [
    {
      "fill_missing": {
        "customer_id": "DESCONHECIDO",
        "data_pedido": "1900-01-01",
        "status": "PENDENTE"
      }
    }
  ]
}

Filtrar Registros Inválidos

{
  "transform": [
    {
      "filter": {
        "condition": {
          "and": [
            {"customer_id": {"!=": null}},
            {"customer_id": {"!=": ""}}
          ]
        }
      }
    }
  ]
}

Problemas de Performance

Execução Lenta do ETL

Sintomas:

{
  "execution_time": "45 minutos",
  "records_processed": 10000,
  "avg_records_per_second": 3.7
}

Estratégias de Otimização:

Processamento em Lote

{
  "source": {
    "id_type": 1,
    "form": {
      "sql": "SELECT * FROM tabela_grande WHERE id BETWEEN ? AND ?",
      "batch_size": 1000,
      "parallel_batches": 4
    }
  }
}

Otimização de Query

{
  "source": {
    "id_type": 1,
    "form": {
      "sql": "SELECT id, nome, email FROM usuarios WHERE data_criacao >= '2024-01-01' AND status = 'ativo'",
      "use_index": "idx_data_status"
    }
  }
}

Compressão

{
  "target": {
    "id_type": 3,
    "compression": "gzip",
    "compression_level": 6
  }
}

Alto Uso de Memória

Sintomas:

Processo ETL: 8.2GB uso de RAM
Disponível: 2.1GB

Soluções:

Processamento Streaming

{
  "processing": {
    "mode": "streaming",
    "buffer_size": 1000,
    "memory_limit": "2GB"
  }
}

Processamento Chunked

{
  "source": {
    "id_type": 1,
    "form": {
      "sql": "SELECT * FROM usuarios",
      "chunk_size": 5000,
      "process_chunks_separately": true
    }
  }
}

Configuração JSON

Erros de Sintaxe

Sintomas:

{
  "error": "Invalid JSON syntax at line 15, column 23",
  "code": "JSON_SYNTAX_ERROR"
}

Erros Comuns:

Erro	Exemplo	Correção
Vírgula no final	`{"a": 1,}`	`{"a": 1}`
Aspas ausentes	`{key: "value"}`	`{"key": "value"}`
Aspas erradas	`{'key': 'value'}`	`{"key": "value"}`
Chave ausente	`{"a": 1`	`{"a": 1}`

Ferramentas de Validação:

# Usar JSONLint
cat config.json | python -m json.tool

# Usar jq
jq . config.json

# Validação do VS Code (automática)

Parâmetros Obrigatórios Ausentes

Sintomas:

{
  "error": "Missing required parameter 'host' in source configuration",
  "code": "MISSING_PARAMETER"
}

Parâmetros Obrigatórios por Tipo de Conexão:

Banco de Dados (id_type: 1)

{
  "source": {
    "id_type": 1,
    "host": "obrigatório",
    "port": "obrigatório",
    "database": "obrigatório",
    "username": "obrigatório",
    "password": "obrigatório"
  }
}

API HTTP (id_type: 2)

{
  "source": {
    "id_type": 2,
    "url": "obrigatório",
    "method": "obrigatório"
  }
}

Google Sheets (id_type: 10)

{
  "target": {
    "id_type": 10,
    "credentials_path": "obrigatório",
    "form": {
      "spreadsheet_id": "obrigatório",
      "range": "obrigatório"
    }
  }
}

Debug Avançado

Ativar Log de Debug

{
  "config": {
    "debug": {
      "enabled": true,
      "level": "DEBUG",
      "log_sql_queries": true,
      "log_data_samples": true,
      "max_sample_records": 5
    }
  }
}

Monitoramento de Performance

{
  "config": {
    "monitoring": {
      "track_performance": true,
      "log_execution_time": true,
      "log_memory_usage": true,
      "alert_thresholds": {
        "execution_time_minutes": 30,
        "memory_usage_gb": 4
      }
    }
  }
}

Recuperação de Erros

{
  "config": {
    "error_handling": {
      "on_connection_error": "retry",
      "on_data_error": "skip_record",
      "on_transform_error": "log_and_continue",
      "max_errors_per_batch": 10
    }
  }
}

Obtendo Ajuda

Canais de Suporte

Documentação: Guia Completo ETL
Referência API: Tipos de Conexão
Comunidade: Slack #etl-support
Enterprise: support@fracttal.com

Informações a Incluir

Ao reportar problemas, inclua:

Configuração ETL (sanitizada)
Logs de erro (últimas 50 linhas)
Detalhes do ambiente (SO, versão Python)
Amostras de dados (anonimizadas)
Passos para reproduzir

Lembre-se: A maioria dos problemas ETL são relacionados à configuração. Verifique duas vezes sua sintaxe JSON e parâmetros obrigatórios antes de buscar suporte.