Leia antes:
README.md. Camadas empipeline-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:
[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):
| Tipo | MAX_ATTEMPTS | Conta |
|---|---|---|
| dashboard | 2 | requeues via [tentativa N] (2 requeues = até 3 execuções) |
| report | 3 | execuções (coluna attempt, incrementada no claim) |
| pipeline | 2 | execuçõ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:
- 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).
- A tentativa também falha → a execução vai para DLQ e a auditoria registra
job.dlqcom o motivo ("teto de tentativas atingido"). A agenda segue normal: o próximo horário do dia seguinte continua marcado. - 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:
| Limiar | Valor | Efeito |
|---|---|---|
| taxa de erro | ≥ 20% | degradado |
| p95 | > 30 s | degradado |
| freshness | > 26 h | degradado |
| freshness | > 72 h | parado |
Sem nenhum evento → parado.
Onde se lê isso hoje. Não existe painel self-service de saúde por conector. Cada operação de conector (teste, descoberta, extração) emite uma linha de telemetria no log da plataforma — com conector, operação, duração, sucesso e a classe do erro (nunca a mensagem, nunca segredo) —, e o agregador acima calcula execuções, taxa de erro, p50/p95, última execução e frescor a partir dessas linhas. Hoje essa leitura é feita pela operação da plataforma, não por uma tela do seu workspace. O que você vê por conta própria é indireto: o estado de cada execução em Orquestração → Execuções (com logs por tentativa), o resultado do Testar conexão e os alertas que você configurar. Os limiares da tabela acima são a régua usada quando essa saúde é avaliada; não são um compromisso por conector. O compromisso de disponibilidade da plataforma é o SLA (veja /legal/sla).#
Ficha (template dos 9 campos)#
- Estado — disponível. Agendamento, backoff, DLQ e reconciliação são cobertos por testes automáticos.
- O que faz — agenda cargas, re-tenta falhas transientes com backoff, isola falhas permanentes em DLQ e aponta buracos entre camadas.
- Como funciona — Postgres + crons de 5 min;
nextRunAtpré-computado; marcadores no campoerror; DLQ = status terminal; reconciliação read-only por workspace. - 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.
- Custo — retry/backoff reduz custo de re-execução cega; jitter evita martelar. Sem custo de plataforma no cálculo.
- Limites — tentativas: dashboard 2 / report 3 / pipeline 2; backoff base 5 min, teto 1 h, jitter 25%.
- Segurança — claim atômico (
updateManycondicionado) evita corrida; DLQ exige intervenção humana auditada; reconciliação escopada por workspace. - Como validar — no console, agende uma carga e acompanhe o
nextRunAte 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. - Em resumo — idempotência, nova tentativa com backoff, DLQ e reconciliação de camadas.