Pular para o conteúdo

Agendamento, retry, DLQ e reconciliação

Nesta página (7)

Leia antes: README.md. Camadas em pipeline-medalhao.md.


Agendamento#

  • O horário da agenda é escolhido e mostrado em horário de Brasília, na tela do pipeline (ETL/ELT → Pipelines → o pipeline → Agenda). Veja Agenda e fuso.
  • O sistema confere as agendas a cada 15 minutos: um pipeline marcado para 07:00 começa entre 07:00 e 07:15.
  • A próxima execução já fica calculada assim que você salva ou edita a agenda — é ela que aparece na tela do pipeline.
  • Execuções que travarem são encerradas sozinhas e contam como falha (entram nas regras de nova tentativa abaixo).

Retry / backoff#

Política central pura (sem I/O); quem grava no banco são os dispatchers com updateMany condicionado (claim atômico). Sem coluna nova (schema congelado): o estado de retry vive em marcadores no campo error que já existe:

código
[tentativa N] [apos <ISO>] <mensagem original>
  • [tentativa N] — marcador vigente do reaper (formato preservado byte a byte).
  • [apos <ISO>] — "não execute antes de" (implementa backoff sem coluna de agenda).

Teto de tentativas por tipo (semântica difere por herança dos modelos):

TipoMAX_ATTEMPTSConta
dashboard2requeues via [tentativa N] (2 requeues = até 3 execuções)
report3execuções (coluna attempt, incrementada no claim)
pipeline2execuções consecutivas com falha da mesma fonte

Backoff: exponencial base × 2^(n-1) com jitter determinístico (hash FNV-1a do seed, ex. runId). Base = 5 min (1 tick do cron), teto = 1 h, jitter até 25%. Determinístico de propósito: o teste prova o valor exato e produção não depende de Math.random.

Classificação da falha:

  • poison (config/validação — retry não conserta) → DLQ direto, sem queimar tentativas. Padrões conservadores: not found, syntax error, unrecognized name, invalid_grant, access/permission denied, unauthorized, forbidden, sem saldo de créditos, sem consultas configuradas.
  • retryable (transiente/desconhecida) → tenta de novo até o teto (o desconhecido fica retryable; o teto protege).

A decisão pós-falha devolve {acao:"retry", tentativa, delayMs, executarApos} ou {acao:"dlq", motivo}.

DLQ — Dead Letter Queue#

DLQ = status "dlq" (novo valor de status). Um run em DLQ sai de todos os filtros executáveis (dispatchers leem queued, reaper lê running) e só volta pela mão de um humano: o reprocessamento a partir da DLQ é uma intervenção manual de um operador, com auditoria — nunca automática.

Um run vai para DLQ quando: erro poison, ou teto de tentativas atingido.

Na prática — o que você vê

Conferido de ponta a ponta no teste integral de 06/10/2026, com um pipeline agendado cuja origem ficou fora do ar:

  1. A execução agendada falha → a próxima tentativa é antecipada para daqui a alguns minutos (a espera vem de Operação › Retentativas do pipeline; o padrão é 1 retentativa com 5 min de espera).
  2. A tentativa também falha → a execução vai para DLQ e a auditoria registra job.dlq com o motivo ("teto de tentativas atingido"). A agenda segue normal: o próximo horário do dia seguinte continua marcado.
  3. Para reprocessar o que caiu na DLQ, abra um chamado (ou peça ao Aiô): o reprocesso é feito pelo time, com auditoria. Pela tela, o caminho equivalente é Execuções › Recuperar… › Executar o pipeline de novo.

Execução parcial conta como falha, mas não roda mais cedo

Se só uma tarefa falha (por exemplo, uma Silver com SQL quebrado) e as outras terminam, a execução fica parcial. Na execução agendada, a parcial conta para o teto de retentativas como uma falha: parciais seguidas levam a execução para a DLQ, e um erro de configuração vai para a DLQ na hora. A diferença é que a parcial não antecipa a próxima execução: parte das tabelas já carregou, então a nova tentativa é o próprio próximo horário da agenda. O aviso de falha é enviado; para corrigir antes disso, ajuste a tarefa e use Recuperar… › Nova tentativa da tarefa só nela.

Reconciliação de camadas (só leitura)#

Um kill no meio deixa buraco entre camadas (bronze carregada sem silver, gold anterior à silver, bronze prometida que nunca chegou). O produto compara os três rastros (execução do pipeline, tabelas Bronze e transformações) e produz um relatório acionável — a correção fica com o operador (zero correção automática nesta onda).

Regras (sempre condicionadas a haver expectativa real):

  • Bronze — fonte com run ok + tabela selecionada: nunca processada → buraco; carga anterior ao início do último run ok → carga velha.
  • Silver — há bronze processada: transform nunca executada → buraco bronze→silver; anterior à bronze mais recente → desatualizada.
  • Gold — há silver processada: transform nunca executada → buraco silver→gold; anterior à silver mais recente → desatualizada.

A coleta do estado é toda escopada por workspaceId (invariante: carimbo de um cliente nunca lê o de outro).

Observabilidade por conector#

Agrega os eventos de extração (uma linha por operação) em execuções, taxa de erro, p50/p95, última execução e freshness:

LimiarValorEfeito
taxa de erro≥ 20%degradado
p95> 30 sdegradado
freshness> 26 hdegradado
freshness> 72 hparado

Sem nenhum evento → parado.

Ficha (template dos 9 campos)#

  1. Estado — disponível. Agendamento, backoff, DLQ e reconciliação são cobertos por testes automáticos.
  2. O que faz — agenda cargas, re-tenta falhas transientes com backoff, isola falhas permanentes em DLQ e aponta buracos entre camadas.
  3. Como funciona — Postgres + crons de 5 min; nextRunAt pré-computado; marcadores no campo error; DLQ = status terminal; reconciliação read-only por workspace.
  4. Plano · Permissão — núcleo · verificação de acesso · chaves de desligamento para execução de ingestão / execução de relatórios / atualização de painéis.
  5. Custo — retry/backoff reduz custo de re-execução cega; jitter evita martelar. Sem custo de plataforma no cálculo.
  6. Limites — tentativas: dashboard 2 / report 3 / pipeline 2; backoff base 5 min, teto 1 h, jitter 25%.
  7. Segurança — claim atômico (updateMany condicionado) evita corrida; DLQ exige intervenção humana auditada; reconciliação escopada por workspace.
  8. Como validar — no console, agende uma carga e acompanhe o nextRunAt e o histórico de execuções; force uma falha transiente e confirme o re-agendamento com backoff; uma falha de configuração vai direto para a DLQ, de onde só sai por ação manual auditada.
  9. Em resumo — idempotência, nova tentativa com backoff, DLQ e reconciliação de camadas.

Links relacionados