Lee antes:
README.md. Capas enpipeline-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:
[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):
| Tipo | MAX_ATTEMPTS | Cuenta |
|---|---|---|
| dashboard | 2 | reencolados vía [tentativa N] (2 reencolados = hasta 3 ejecuciones) |
| report | 3 | ejecuciones (columna attempt, incrementada en el claim) |
| pipeline | 2 | ejecuciones 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:
- 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).
- El intento también falla → la ejecución va a la DLQ y la auditoría registra
job.dlqcon el motivo ("tope de intentos alcanzado"). La agenda sigue normal: el próximo horario del día siguiente sigue programado. - 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:
| Umbral | Valor | Efecto |
|---|---|---|
| tasa de error | ≥ 20% | degradado |
| p95 | > 30 s | degradado |
| freshness | > 26 h | degradado |
| freshness | > 72 h | detenido |
Sin ningún evento → detenido.
Ficha (plantilla de los 9 campos)#
- Estado — disponible. Programación, backoff, DLQ y reconciliación están cubiertos por pruebas automáticas.
- Qué hace — programa cargas, reintenta fallas transitorias con backoff, aísla fallas permanentes en la DLQ y señala huecos entre capas.
- Cómo funciona — Postgres + crons de 5 min;
nextRunAtprecalculado; marcadores en el campoerror; DLQ = status terminal; reconciliación de solo lectura por workspace. - Plan · Permiso — núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta / ejecución de informes / actualización de paneles.
- Costo — el reintento/backoff reduce el costo de reejecución a ciegas; el jitter evita martillar. Sin costo de plataforma en el cálculo.
- Límites — intentos: dashboard 2 / report 3 / pipeline 2; backoff base 5 min, tope 1 h, jitter 25%.
- Seguridad — el claim atómico (
updateManycondicionado) evita condiciones de carrera; la DLQ exige intervención humana auditada; reconciliación acotada por workspace. - Cómo validar — en la consola, programa una carga y sigue el
nextRunAty 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. - En resumen — idempotencia, reintento con backoff, DLQ y reconciliación de capas.