Selo de estado:
Preview(teto atual do produto) · Curso ACD-230 — Operação: orquestração, falhas e recuperação · Aula 7 de 8 · Atualizado em 2026-10-04.
Objetivo#
Ao final desta aula você vai partir de um sintoma e chegar à ação certa em quatro passos fixos, sem reexecutar às cegas.
Vídeo#
Identificador no manifesto: acd-230-07-troubleshooting-pipeline · duração-alvo 6 min · tela do produto: /dags.
Roteiro (4 capítulos):
| # | Minutagem-alvo | Capítulo | Rota do produto |
|---|---|---|---|
| 1 | 0:00–1:10 | O método de quatro passos: qual tarefa → qual tentativa → config ou transiente → escopo mínimo. Por que a ordem importa. | /dags/[id] |
| 2 | 1:10–3:00 | Caso A — falha de schema: coluna nova que não apareceu, tipo que mudou. A tela Incompatibilidade detectada e Revisar transição de tipo. | /sources/[id] |
| 3 | 3:00–4:30 | Caso B — incremental sem linhas novas (watermark já avançou) e Caso C — execução verde, painel vazio. | /dags |
| 4 | 4:30–6:00 | Impedimentos — a execução está bloqueada: quando o sintoma não é dado, é acesso. Os três erros do curso; o "faça você mesmo". | /dags/[id] |
Conteúdo#
O método, antes da tabela
1. Qual tarefa falhou (não "a execução"). 2. Qual tentativa encerrou a tarefa — leia o log dela, não o agregado. 3. É configuração (não se resolve repetindo) ou transiente (o retry resolve sozinho)? 4. Qual é o escopo mínimo que corrige, e o que a prévia diz que vai rodar. Pular do sintoma direto para "reexecutar" é o que transforma um erro em dois.
O conceito: sintoma não é causa
"O pipeline falhou" não é diagnóstico — é a notificação. Em /dags, o produto já faz metade do trabalho ao separar Falha na última execução (precisa de ação hoje) de Falhas no período (histórico). O resto é descer a hierarquia da aula 2 e classificar a falha como na aula 3. Só então você escolhe o escopo da aula 4.
A tabela: sintoma → causa provável → diagnóstico → ação
| Sintoma | Causa provável | Diagnóstico | Próxima ação |
|---|---|---|---|
| Pipeline "preso" em execução | job travado ou dependência lenta | auditoria na categoria Pipeline + horário da rodada | aguarde o recuperador de runs presos; depois use o relatório de reconciliação |
| Execução marcada como falha | origem indisponível ou dado malformado | expanda o detalhe da tentativa que encerrou a tarefa | corrija a origem e recupere com escopo mínimo |
| Coluna nova na origem não apareceu | schema drift não propagado | compare o schema da fonte com o da Bronze | reexecute a descoberta/carga da fonte |
| Tipo de coluna mudou e quebrou Silver/Gold | mudança de tipo incompatível | a tela Incompatibilidade detectada mostra Tipo: atual → proposto | use Revisar transição de tipo e leia a preservação medida |
| Incremental não traz linhas novas | o watermark já avançou além do dado | confira a coluna de watermark | rode backfill da janela necessária |
| Esperava capturar updates e deletes | CDC verdadeiro é Roadmap | o incremental é por watermark | use watermark + backfill; deletes não são capturados |
| Fonte "vazia" num dia | a origem não tinha dados na janela | confira a origem no período | reexecute quando houver dado; não é defeito do pipeline |
| Execução verde, painel vazio | destino, materialização ou vínculo do painel | confira a Gold e o painel | a conclusão da DAG não garante painel atualizado |
| Silver/Gold "não executada" | bloqueio por dependência (aula 5) | leia o motivo registrado na tarefa | corrija a montante e recupere a partir da Bronze |
| Job cai por custo | teto de bytes atingido | custo/erro da rodada | reduza o escopo ou particione a fonte |
| Impedimentos — a execução está bloqueada | assinatura, papel ou capacidade desligada | leia a mensagem: ela diz qual é | aula 8 |
| Falha de autenticação | a conexão referenciada | teste a conexão | corrija na conexão, uma vez |
As telas e os botões reais
O painel de diagnóstico mais específico do produto é o de mudança de tipo. Quando uma coluna muda de tipo na origem, a página da fonte (/sources/[id]) mostra Incompatibilidade detectada, com Tipo: atual → proposto, o Formato encontrado (exemplos sintéticos) e as Formas encontradas na carga parada (mascaradas) — ou seja, ele mostra a evidência sem expor dado. O botão Revisar transição de tipo abre a análise, e duas seções dessa tela merecem leitura atenta: Preservação dos valores — medida, não presumida (o produto mede quantos valores sobrevivem à conversão, não chuta) e Significado temporal — a armadilha da meia-noite (uma data "sem horário" convertida ingenuamente inventaria um instante; a linha só-data continua visível e classificada, não desaparece). Se o seu papel não permite aplicar a transição, a tela diz isso em vez de falhar silenciosamente.
Na página da execução (/dags/[id]), quando a causa não é dado, o bloco Impedimentos — a execução está bloqueada lista o que impede executar — e isso é tema da próxima aula.
Reprocessar sem duplicar é esperado
Quando o retry re-executa uma carga idempotente, não duplicar é o comportamento normal — não é sorte. Confie no retry com backoff em vez de disparar manualmente por cima dele: disparos sobrepostos é que criam o estrago.
Exemplo: a Comércio Aurora — três casos em uma semana
Caso A — tipo mudou. O ERP passou a enviar data_venda como texto. A Silver quebra. Maria vê Incompatibilidade detectada com Tipo: atual → proposto, lê a preservação medida (quantos valores convertem sem perda) e o aviso da meia-noite, e só então aplica a transição. Depois recupera com Reexecutar tarefa e dependentes a partir da Silver — a Bronze estava íntegra.
Caso B — incremental sem linhas novas. A carga conclui verde, zero linhas. O watermark já estava além do dado que chegou atrasado na origem. Nada a "consertar" na execução: a ação é um backfill da janela.
Caso C — verde, painel vazio. A execução concluiu, mas o painel de receita não mudou. A Gold daquele ramo apareceu como não executada — bloqueio por dependência, porque a Bronze de filiais falhou na mesma rodada. A ação é corrigir a Bronze, não mexer no painel.
Erros comuns
| Sintoma | Causa provável | Próxima ação |
|---|---|---|
| Log não bate com o erro | Diagnóstico feito no log agregado ou na tentativa errada | Confirme o cabeçalho Logs da tarefa … · tentativa N (aula 2) |
| Reexecutei e duplicou linhas | Ação tomada antes do diagnóstico, com escopo grande | Diagnostique, corrija, depois escolha o escopo mínimo (aula 4) |
| Confundi pausar com executar | Pausar a agenda para "parar o erro" — mas a execução em curso continua | Pausar só impede novos agendamentos (aula 1) |
| Abri chamado e o problema era watermark | Sintoma classificado como defeito do produto | Rode os quatro passos antes; leve tarefa, tentativa e mensagem exata |
| "Vou marcar como sucesso para destravar" | Confundir estado com dado | Marcar sucesso não produz dado (aula 4) |
Estado do produto
O catálogo de diagnóstico é documentação de Preview: ele mapeia sintomas às respostas reais do produto, mas não há SLA de resolução, nem tempo de execução publicado, e latência e custo de nuvem continuam NÃO MEDIDO. CDC verdadeiro é Roadmap — o incremental é por watermark, e deletes não são capturados; isso é limite conhecido, não defeito a diagnosticar. Diagnosticar custa R$ 0; só a reexecução consome nuvem.
Faça você mesmo#
No workspace de treino Aurora Varejo (abra /dags no console), como dono. Meta: resolver 3 casos aplicando o método.
- Escreva os quatro passos do método num papel e mantenha à vista: tarefa → tentativa → config ou transiente → escopo mínimo.
- Caso A (schema): mude o tipo de uma coluna na origem de treino (por exemplo, uma data que passa a vir como texto) e execute. Localize Incompatibilidade detectada, leia Tipo: atual → proposto e a seção de preservação medida; só então use Revisar transição de tipo.
- Recupere o Caso A com o escopo mínimo que resolve e confira a contagem no destino.
- Caso B (watermark): num pipeline incremental, confirme uma execução verde com zero linhas e identifique a coluna de watermark. Conclua qual é a ação (backfill da janela) sem reexecutar o pipeline inteiro.
- Caso C (dependência): provoque uma falha numa Bronze e confirme que a Gold ficou não executada com o motivo. Classifique o sintoma "painel não atualizou" corretamente: a causa está a montante.
- Para cada um dos três casos, registre em uma linha: sintoma → causa → diagnóstico (onde você leu) → ação tomada.
- Confira a auditoria e confirme que suas ações ficaram registradas com autor e horário.
Você terminou quando os três casos estiverem resolvidos, cada um com a sua linha de sintoma → ação escrita, e nenhuma linha duplicada no destino.
Checagem rápida#
Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.
Documentação relacionada#
Capacidades ensinadas#
(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".