Retry, DLQ e reconciliação · Ingestia Academy

Selo de estado: Preview (teto atual do produto) · Curso ACD-230 — Operação: orquestração, falhas e recuperação · Aula 3 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai identificar um item parado na DLQ, corrigir a causa e reprocessá-lo de forma auditada, sem reprocessar cegamente o que vai voltar para lá.

Vídeo#

Identificador no manifesto: acd-230-03-retry-backoff-dlq · duração-alvo 8 min · tela do produto: /dags.

Roteiro (6 capítulos):

#	Minutagem-alvo	Capítulo	Rota do produto
1	0:00–0:50	Duas classes de falha: retryable (transiente) e poison (configuração/validação). Só a primeira ganha nova tentativa.	`/dags`
2	0:50–2:40	Retry com backoff: os marcadores `[tentativa N]` e `[apos <ISO>]` no erro da execução; base 5 min, teto 1 h, jitter determinístico.	`/dags/[id]`
3	2:40–4:20	Tetos por tipo (dashboard 2 · report 3 · pipeline 2) e o que acontece ao estourar: status parada (DLQ).	`/dags`
4	4:20–6:00	A DLQ na prática: o item sai de todos os filtros executáveis e só volta pela mão de uma pessoa, com auditoria. Ler o motivo, corrigir a causa, reprocessar.	`/dags/[id]`
5	6:00–7:10	Reconciliação de camadas: o relatório que aponta o buraco Bronze→Silver→Gold depois de uma interrupção — diagnóstico, não correção automática.	`/sources/[id]`
6	7:10–8:00	Os três erros do curso e o "faça você mesmo".	`/dags`

Conteúdo#

A DLQ é para

execuções, não para linhas de dado Um item em DLQ é uma execução (job) que falhou o suficiente para sair da fila. Linhas de dado reprovadas na qualidade são outra coisa — ver qualidade, deduplicação e rejeitados. E o reprocessamento a partir da DLQ é sempre uma intervenção manual de operador, com auditoria: nunca automática.

O conceito: nem toda falha merece uma nova tentativa

O produto classifica a falha antes de decidir o que fazer com ela:

Classe	Exemplos	O que acontece
retryable (transiente ou desconhecida)	timeout, 5xx, erro de rede	re-tenta com backoff até o teto
poison (configuração/validação — retry não conserta)	`not found`, `syntax error`, `unrecognized name`, `invalid_grant`, `access denied`, `sem saldo de créditos`	vai direto para a DLQ, sem queimar tentativas

Note a assimetria deliberada: o desconhecido fica retryable (o teto protege), mas a falha que claramente não se resolve repetindo vai para a DLQ na primeira. Repetir uma credencial expirada dez vezes não renova a credencial — só consome recurso e atrasa o diagnóstico.

Retry com backoff (o que você vê na tela)

O estado da repetição aparece em marcadores no próprio erro da execução:

código

[tentativa 2] [apos 2026-09-08T13:40:00Z] connection reset by peer

[tentativa N] diz quantas vezes já re-tentou; [apos <ISO>] é um "não execute antes de" — é assim que o backoff é implementado. O cálculo é exponencial, base × 2^(n-1), com base de 5 minutos (um tique do cron), teto de 1 hora e jitter determinístico de até 25%. Determinístico de propósito: o mesmo cenário produz o mesmo atraso, e a produção não depende de sorteio.

Os tetos de tentativa diferem por tipo: dashboard 2, relatório 3, pipeline 2. Estourado o teto, o run vira DLQ — status cujo rótulo na tela é parada (DLQ), com a descrição "Falhou o número máximo de vezes e saiu da fila — precisa de operador."

As telas e os botões reais

Em /dags, um pipeline com item parado aparece sob Falha na última execução, e o estado da execução é parada (DLQ) — visualmente distinto de uma falha comum. Abra a execução (/dags/[id]), desça até a tarefa e a tentativa (aula 2) e leia o motivo: a mensagem já vem redigida, com segredos removidos. Em /sources/[id], o painel de ingestão mostra o histórico daquela fonte e é de lá que você dispara um novo processamento depois de corrigir. O ciclo correto é sempre o mesmo: ler o motivo → corrigir a causa na origem → reprocessar. Reprocessar antes de corrigir devolve o item à DLQ.

Reconciliação: o relatório do buraco

Uma interrupção no meio da execução pode deixar Bronze carregada sem Silver, ou Gold anterior à Silver. O produto compara os três rastros — execução do pipeline, tabelas Bronze e transformações — e produz um relatório acionável, escopado por workspace. Ele diagnostica; a correção é do operador. Não existe correção automática hoje, e isso é uma escolha: corrigir sozinho exigiria adivinhar qual camada é a verdade.

Exemplo: a Comércio Aurora

Na quarta-feira, a execução das 06:00 falha com [tentativa 1] [apos 2026-09-08T13:35:00Z] ETIMEDOUT. É retryable: o despachante re-executa cerca de cinco minutos depois, sozinho, e passa. Ninguém precisa fazer nada — e reexecutar manualmente nesse momento só atropelaria o backoff.

Na quinta, o token do conector de vendas expira e a execução falha com invalid_grant: token expired. Isso é poison: vai direto para a DLQ, sem consumir as duas tentativas do pipeline. João vê o estado parada (DLQ) em /dags, lê o motivo na tentativa, vai à conexão e substitui a credencial — a correção é na conexão, uma vez, e vale para todos os pipelines que a referenciam. Só então ele reprocessa a partir da DLQ, pelo painel de ingestão da fonte. O evento fica na auditoria com o nome de quem reprocessou.

Erros comuns

Sintoma	Causa provável	Próxima ação
Volta sempre para a DLQ	Causa permanente não corrigida	Corrija a origem (permissão, SQL, crédito, credencial) antes de reprocessar
"Nunca re-tenta"	Erro classificado como poison	É o comportamento esperado: poison vai direto à DLQ
Run "preso" em execução	Processo morreu no meio	O recuperador de runs presos ("reaper") trata; a reconciliação aponta o buraco
Reexecutei e duplicou linhas	Reprocessamento com escopo maior que o necessário	Escolha o escopo mínimo e leia a prévia (aula 4)
Confundi pausar com executar	Pausar a agenda não esvazia a DLQ nem cancela o que está rodando	Pausar só impede novos agendamentos
Log não bate com o erro	Marcador `[tentativa N]` de uma tentativa, mensagem de outra	Leia o log da tentativa cujo cabeçalho a tela cita (aula 2)

Estado do produto

As regras de retry, backoff, DLQ e reconciliação são determinísticas e provadas por teste — a capacidade C01.4 é o motor assíncrono idempotente. O teto segue Preview: a execução real em fila de nuvem é NÃO MEDIDO, não há SLA e o custo faturado em BRL também é NÃO MEDIDO. O que isso significa na prática: a decisão de re-tentar ou isolar é previsível e você pode confiar nela; o tempo que a fila leva para processar, não. O retry com backoff reduz o custo da reexecução cega, e o jitter evita martelar a origem.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dags no console), como dono. Meta: reprocessar um item da DLQ.

Provoque uma falha poison controlada: numa conexão de treino, deixe a credencial inválida (ou aponte para uma tabela que não existe) e execute o pipeline com Executar agora.
Em /dags, confirme que o pipeline aparece sob Falha na última execução e que o estado da execução é parada (DLQ) — e não uma falha em repetição.
Abra a execução, desça até a tarefa e a tentativa, e leia o motivo. Confirme que a mensagem não traz nenhum segredo.
Confira se existe marcador [tentativa N]: numa falha poison não deve haver sequência de repetições, porque ela não queima tentativas.
Corrija a causa — substitua a credencial na conexão, ou corrija a tabela de origem. A correção é na conexão, não dentro do pipeline.
Reprocesse a partir do painel de ingestão em /sources/[id] e acompanhe a nova execução em /dags.
Confira na auditoria que o reprocessamento ficou registrado com autor e horário.
Confira o destino (contagem de linhas), não só o selo verde.

Você terminou quando o item tiver saído de parada (DLQ) por uma ação sua depois da correção, o reprocessamento estiver na auditoria e você conseguir explicar por que esse erro não ganhou nenhuma tentativa automática.

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#

C01.4 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".