🚨 Runbook de Incidentes¶

Guia de diagnóstico e resolução para os cenários de falha mais comuns no Datalake Lavoro.

🔴 DAG Falhou no Airflow¶

Sintomas¶

Task com status failed no Airflow UI
Alerta no canal de monitoramento
Dados desatualizados nos dashboards

Diagnóstico¶

graph TD
    A[DAG falhou] --> B{Qual task falhou?}
    B --> C[Bronze - Extração]
    B --> D[Silver - Transformação]
    B --> E[Gold - Consumo]

    C --> F{Erro de conexão?}
    F -->|Sim| G[Verificar API/Banco de origem]
    F -->|Não| H[Verificar logs da task]

    D --> I{Erro de SQL?}
    I -->|Sim| J[Verificar query no BigQuery]
    I -->|Não| K[Verificar dados da Bronze]

    E --> L{Dados duplicados?}
    L -->|Sim| M[Verificar MERGE/dedup]
    L -->|Não| N[Verificar dependências Silver]

    style A fill:#ff5252,color:#fff
    style G fill:#e8f5e9
    style J fill:#e8f5e9
    style M fill:#e8f5e9

Passos de Resolução¶

Acesse o Airflow UI e localize a DAG com falha
Clique na task vermelha → aba "Log" para ver o erro detalhado
Identifique o tipo de erro:

Erro Comum	Causa Provável	Ação
`Connection refused`	API/banco de origem fora do ar	Verificar status da fonte de dados
`Table not found`	Dataset ou tabela renomeado/deletado	Conferir nome no BigQuery
`Duplicate key`	MERGE sem filtro adequado	Revisar cláusula MERGE/dedup na query
`Quota exceeded`	Limite de slots do BigQuery atingido	Aguardar ou solicitar aumento de quota
`Timeout`	Query muito pesada ou dados volumosos	Otimizar query (filtros, partições)
`Permission denied`	Service Account sem permissão	Verificar IAM da SA no GCP

Corrija o problema e faça re-run da task:
- No Airflow UI: clique na task → "Clear" → confirme
- A task será re-executada automaticamente

Cuidado ao fazer Clear

Fazer "Clear" em uma task Bronze re-executa a extração completa. Se o volume de dados for alto, prefira corrigir o erro e re-executar apenas a task que falhou, não o DAG inteiro.

🟡 Dados Desatualizados nos Dashboards¶

Sintomas¶

Dashboard mostrando dados de dias anteriores
Stakeholders reportando "dados antigos"

Diagnóstico¶

Verifique se a DAG executou:
- Airflow UI → DAG → aba "Grid" → verificar última execução
Verifique se a tabela Gold foi atualizada:

-- Verificar última atualização da tabela
SELECT
  TIMESTAMP_MILLIS(last_modified_time) AS ultima_atualizacao
FROM `projeto.__TABLES__`
WHERE table_id = 'nome_da_tabela'

Verifique se há task pendente ou em retry

Resolução¶

Cenário	Ação
DAG não executou	Verificar schedule e trigger manual
Task em retry	Aguardar ou investigar erro
Dados chegaram incompletos	Re-executar a camada Bronze
Query Gold incorreta	Corrigir SQL e re-executar task Gold

🔴 Cloud Composer Indisponível¶

Sintomas¶

Airflow UI inacessível
DAGs não executando no horário agendado
Erro 502/504 ao acessar o webserver

Diagnóstico¶

Verifique o status no GCP Console:
- Console → Cloud Composer → Ambientes → Status do Composer
Verifique logs do Composer:
- Cloud Logging → Filtrar por resource.type="cloud_composer_environment"
Verifique recursos:
- Memória e CPU dos workers podem estar saturados

Resolução¶

Cenário	Ação
Composer em estado `UPDATING`	Aguardar (pode levar 20-30 min)
Workers sem recursos	Escalar manualmente no GCP Console
Erro de rede	Verificar VPC e firewalls
Problema persistente	Abrir ticket no Google Cloud Support

Prevenção

O Cloud Composer tem autoscaling configurado. Se os problemas de recursos forem recorrentes, considere aumentar os limites mínimos de workers na configuração do ambiente.

🟡 Dados Duplicados em Tabelas¶

Sintomas¶

Contagens maiores que o esperado após execução
Métricas infladas nos dashboards

Diagnóstico¶

-- Identificar duplicatas por chave
SELECT
  chave_primaria,
  COUNT(*) AS qtd
FROM `dataset.tabela`
GROUP BY chave_primaria
HAVING COUNT(*) > 1
ORDER BY qtd DESC
LIMIT 10

Resolução¶

Identifique a origem: Bronze (extração duplicou) ou Silver/Gold (JOIN multiplicou)
Se extração duplicou: verificar se a DAG rodou 2x no mesmo período
Se JOIN multiplicou: adicionar DISTINCT ou revisar granularidade do JOIN

-- Validar COUNT antes e depois de um JOIN
SELECT COUNT(*) FROM tabela_a;
SELECT COUNT(*) FROM tabela_a a JOIN tabela_b b ON a.id = b.id;
-- Se o segundo COUNT for maior, o JOIN está multiplicando

Regra de Ouro

Sempre valide COUNT(*) antes e depois de JOINs novos. Se o count aumentar, há multiplicação de registros.

🟡 Query Lenta no BigQuery¶

Sintomas¶

Task do Airflow com timeout
Queries demorando mais de 3 minutos

Diagnóstico¶

Verifique o plano de execução no BigQuery Console (aba "Execution details")
Identifique gargalos comuns:

Gargalo	Sintoma	Solução
Full table scan	Bytes processados muito alto	Adicionar filtro de partição (`WHERE data >= ...`)
JOIN sem filtro	Shuffle excessivo	Filtrar ambas as tabelas antes do JOIN
`LIKE` em JOIN	Performance degradada	Usar campos exatos no JOIN
Sem clustering	Queries lentas em filtros frequentes	Adicionar clustering na tabela

Boas Práticas¶

Sempre use WHERE na coluna de partição antes de JOINs
Limite escopo com LIMIT durante desenvolvimento
Evite SELECT * — selecione apenas colunas necessárias
Use EXPLAIN para analisar o plano de execução

💸 Problemas de Faturamento¶

Quando o Faturamento estiver divergente da contabilidade, siga este playbook na ordem.

1. Análise inicial (macro → micro)¶

Compare o fato_faturamento com o balancete em duas granularidades possíveis:

fato_balancete — granularidade de lançamento contábil, relacionar a dim_plano_de_contas.
fato_balancete_visao_saldo — dados consolidados por conta.

Comece a comparação a nível macro (totais por conta) e vá reduzindo a granularidade conforme identificar divergências. Sempre observe o campo desc_conta / descricao_conta ao navegar pelo plano de contas.

2. Sistema mais propenso a divergência¶

O sistema que mais gera divergências é o HPRO (Qualicitrus).

HPRO não é defeito, é design

A extração do HPRO segue um caminho diferente do padrão (Airflow → Pub/Sub → vm_legado → script → GCS). Esse fluxo é arquitetural (limitação do próprio HPRO), não um problema. Veja Caso especial: HPRO na arquitetura.

3. Recarga em PRD¶

Se a consolidação já estiver divergente da contabilidade, execute uma carga full em PRD.

QA é cópia de PRD

Em QA fazemos copy do faturamento de PRD para QA. Por isso recarregar QA não resolve nada — a fonte de verdade é PRD.

4. Conta de CutOff ou conta nova¶

Se persistir após a carga full, verifique se o problema é uma conta de CutOff ou uma conta nova que ainda não está contemplada na query de faturamento. Atualize a query para cobrir essas contas.

5. Volta para análise detalhada¶

Se ainda persistir, retorne ao passo 1 e desça mais um nível de granularidade na comparação (lançamento por lançamento, por dia, por nota fiscal) até identificar o registro/conta que está causando a divergência.

6. Acionar Controladoria¶

Se houver lançamento faltando e nem a carga full (passo 3) resolver, acione o time de Controladoria para verificar se o problema está no próprio ERP (lançamento não escriturado, registro pendente de aprovação, etc.). Nesses casos a divergência é da fonte, não do pipeline.

📅 Atualizado em Março 2026