Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Programación, reintento, DLQ y reconciliación

En esta página (7)

Lee antes: README.md. Capas en pipeline-medalhao.md.


Programación#

  • La hora de la agenda se elige y se muestra en horario de Brasilia, en la pantalla del pipeline (ETL/ELT → Pipelines → el pipeline → Agenda). Consulta Agenda y zona horaria.
  • El sistema revisa las agendas cada 15 minutos: un pipeline programado para las 07:00 comienza entre las 07:00 y las 07:15.
  • La próxima ejecución queda calculada en cuanto guardas o editas la agenda — es la que aparece en la pantalla del pipeline.
  • Las ejecuciones que se traben se cierran solas y cuentan como falla (entran en las reglas de reintento de abajo).

Reintento / backoff#

Política central pura (sin I/O); quienes escriben en la base de datos son los dispatchers con updateMany condicionado (claim atómico). Sin columna nueva (schema congelado): el estado de reintento vive en marcadores en el campo error que ya existe:

código
[tentativa N] [apos <ISO>] <mensagem original>
  • [tentativa N] — marcador vigente del reaper (formato preservado byte a byte).
  • [apos <ISO>] — "no ejecutar antes de" (implementa backoff sin columna de agenda).

Tope de intentos por tipo (la semántica difiere por herencia de los modelos):

TipoMAX_ATTEMPTSCuenta
dashboard2reencolados vía [tentativa N] (2 reencolados = hasta 3 ejecuciones)
report3ejecuciones (columna attempt, incrementada en el claim)
pipeline2ejecuciones consecutivas con falla de la misma fuente

Backoff: exponencial base × 2^(n-1) con jitter determinístico (hash FNV-1a del seed, p. ej. runId). Base = 5 min (1 tick del cron), tope = 1 h, jitter de hasta 25%. Determinístico a propósito: la prueba comprueba el valor exacto y producción no depende de Math.random.

Clasificación de la falla:

  • poison (config/validación — reintentar no lo arregla) → directo a la DLQ, sin gastar intentos. Patrones conservadores: not found, syntax error, unrecognized name, invalid_grant, access/permission denied, unauthorized, forbidden, sem saldo de créditos, sem consultas configuradas.
  • retryable (transitoria/desconocida) → reintenta hasta el tope (lo desconocido queda como retryable; el tope protege).

La decisión posterior a la falla devuelve {acao:"retry", tentativa, delayMs, executarApos} o {acao:"dlq", motivo}.

DLQ — Dead Letter Queue#

DLQ = status "dlq" (nuevo valor de status). Un run en DLQ sale de todos los filtros ejecutables (los dispatchers leen queued, el reaper lee running) y solo vuelve por mano de una persona: el reprocesamiento desde la DLQ es una intervención manual de un operador, con auditoría — nunca automática.

Un run va a la DLQ cuando: hay un error poison, o se alcanza el tope de intentos.

En la práctica: lo que ves

Verificado de punta a punta en la prueba integral del 06/10/2026, con un pipeline programado cuyo origen quedó fuera de servicio:

  1. La ejecución programada falla → el próximo intento se adelanta para dentro de unos minutos (la espera viene de Operación › Reintentos del pipeline; el valor predeterminado es 1 reintento con 5 min de espera).
  2. El intento también falla → la ejecución va a la DLQ y la auditoría registra job.dlq con el motivo ("tope de intentos alcanzado"). La agenda sigue normal: el próximo horario del día siguiente sigue programado.
  3. Para reprocesar lo que cayó en la DLQ, abre un ticket (o pídeselo a Aiô): el reproceso lo hace el equipo, con auditoría. Por la pantalla, el camino equivalente es Ejecuciones › Recuperar… › Ejecutar el pipeline de nuevo.

La ejecución parcial cuenta como falla, pero no se adelanta

Si solo una tarea falla (por ejemplo, una Silver con SQL roto) y las demás terminan, la ejecución queda parcial. En la ejecución programada, la parcial cuenta para el tope de reintentos como una falla: varias parciales seguidas llevan la ejecución a la DLQ, y un error de configuración va a la DLQ en el acto. La diferencia es que la parcial no adelanta la próxima ejecución: parte de las tablas ya se cargó, así que el nuevo intento es el propio próximo horario de la agenda. Se envía el aviso de falla; para corregirlo antes, ajusta la tarea y usa Recuperar… › Nuevo intento de la tarea solo en ella.

Reconciliación de capas (solo lectura)#

Un kill a mitad de camino deja un hueco entre capas (bronze cargada sin silver, gold anterior a la silver, bronze prometida que nunca llegó). El producto compara los tres rastros (ejecución del pipeline, tablas Bronze y transformaciones) y genera un informe accionable — la corrección queda a cargo del operador (cero corrección automática en esta ola).

Reglas (siempre condicionadas a que haya una expectativa real):

  • Bronze — fuente con run ok + tabla seleccionada: nunca procesada → hueco; carga anterior al inicio del último run ok → carga vieja.
  • Silver — hay bronze procesada: transform nunca ejecutada → hueco bronze→silver; anterior a la bronze más reciente → desactualizada.
  • Gold — hay silver procesada: transform nunca ejecutada → hueco silver→gold; anterior a la silver más reciente → desactualizada.

La recolección del estado está toda acotada por workspaceId (invariante: el sello de un cliente nunca lee el de otro).

Observabilidad por conector#

Agrega los eventos de extracción (una fila por operación) en ejecuciones, tasa de error, p50/p95, última ejecución y freshness:

UmbralValorEfecto
tasa de error≥ 20%degradado
p95> 30 sdegradado
freshness> 26 hdegradado
freshness> 72 hdetenido

Sin ningún evento → detenido.


Ficha (plantilla de los 9 campos)#

  1. Estado — disponible. Programación, backoff, DLQ y reconciliación están cubiertos por pruebas automáticas.
  2. Qué hace — programa cargas, reintenta fallas transitorias con backoff, aísla fallas permanentes en la DLQ y señala huecos entre capas.
  3. Cómo funciona — Postgres + crons de 5 min; nextRunAt precalculado; marcadores en el campo error; DLQ = status terminal; reconciliación de solo lectura por workspace.
  4. Plan · Permiso — núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta / ejecución de informes / actualización de paneles.
  5. Costo — el reintento/backoff reduce el costo de reejecución a ciegas; el jitter evita martillar. Sin costo de plataforma en el cálculo.
  6. Límites — intentos: dashboard 2 / report 3 / pipeline 2; backoff base 5 min, tope 1 h, jitter 25%.
  7. Seguridad — el claim atómico (updateMany condicionado) evita condiciones de carrera; la DLQ exige intervención humana auditada; reconciliación acotada por workspace.
  8. Cómo validar — en la consola, programa una carga y sigue el nextRunAt y el historial de ejecuciones; fuerza una falla transitoria y confirma la reprogramación con backoff; una falla de configuración va directo a la DLQ, de donde solo sale por una acción manual auditada.
  9. En resumen — idempotencia, reintento con backoff, DLQ y reconciliación de capas.

Enlaces relacionados