Configuración de Jobs

La sección jobs del archivo de configuración controla cómo ejecutan los job workers los jobs de pump, load y dump: cómo detectan un job que ha dejado de avanzar o cuyo worker ha muerto, si esos jobs se reanudan solos, cuántos pipelines procesa un job en paralelo y cuánto se guarda del log de los jobs.

Todas las propiedades tienen un valor por defecto, así que la sección puede omitirse o contener solo las propiedades que quieras cambiar. Estos ajustes importan sobre todo en jobs largos sobre bases de datos grandes. Consulta Trabajar con bases de datos grandes para ver el conjunto.

Propiedades de Configuración

La sección jobs de tu archivo config/default.yaml, con sus valores por defecto:

jobs:
  stallTimeoutSec: 900
  finishTimeoutSec: 86400
  heartbeatSec: 15
  leaseStaleSec: 300
  autoResume: false
  maxAutoResumes: 3
  concurrent: 1
  shardWorkers: 0
  copy: true
  logTraceLevel: 1

Propiedad	Tipo	Valor por defecto	Para qué sirve
`stallTimeoutSec`	Entero, 0 o más	`900`	Termina un job que lleva este tiempo sin avanzar
`finishTimeoutSec`	Entero, 0 o más	`86400`	Cuánto espera un job fallido a que se restaure el sink
`heartbeatSec`	Entero, 1 o más	`15`	Cada cuánto renueva un job en ejecución su lease
`leaseStaleSec`	Entero, 30 o más	`300`	Cuándo un lease sin renovar es de un worker muerto
`autoResume`	Booleano	`false`	Reanudar los jobs de workers muertos en lugar de fallarlos
`maxAutoResumes`	Entero, 0 o más	`3`	Máximo de reanudaciones automáticas de un job
`concurrent`	Entero, 1 o más	`1`	Mínimo de pipelines que un job procesa en paralelo
`shardWorkers`	Entero, 0 o más	`0`	Job workers del mismo host que ayudan a un pump
`copy`	Booleano	`true`	Cargar los sinks Postgres con `COPY`
`logRetentionDays`	Entero, de 0 a 24855	Sin valor (`jobLogRetentionDays`, 90)	Días que se guardan las líneas del log de los jobs (0: siempre)
`logTraceLevel`	Entero, 0 o más	`1`	Nivel de traza más detallado que se guarda en el log de un job cuyo pipeline no tiene nivel de log

Detalles de las Propiedades

stallTimeoutSec

Tipo: Entero (mínimo 0)
Valor por defecto: 900 (15 minutos)
Descripción: Un job en ejecución que no informa de progreso, ni de heartbeat, ni escribe una línea de log durante estos segundos se detiene y termina fallido con el mensaje job stalled: no progress for N seconds. 0 desactiva la comprobación.
Cuándo cambiarlo: Las operaciones largas que no mueven registros (contar una tabla, reconstruir constraints, tomar un snapshot, guardar el diccionario) envían heartbeats, así que rara vez hace falta cambiar el valor. Súbelo si tu origen tiene consultas que tardan más de 15 minutos en devolver las primeras filas (por ejemplo, una consulta personalizada con una ordenación grande). No lo desactives: una caída silenciosa de la red puede dejar un job esperando para siempre.

finishTimeoutSec

Tipo: Entero (mínimo 0)
Valor por defecto: 86400 (24 horas)
Descripción: Cuando un error detiene un job, su ejecución todavía restaura el sink antes de que el job termine (por ejemplo, vuelve a crear las constraints y a habilitar los triggers que desactivó). El job espera como máximo estos segundos a que acabe ese trabajo. También deja de esperar cuando ese trabajo no envía ningún heartbeat durante stallTimeoutSec segundos. 0 espera lo que haga falta.
Cuándo cambiarlo: Reconstruir las constraints de tablas muy grandes puede llevar horas. Súbelo si restaurar tu sink puede tardar más de un día, para que el job no termine (y no se pueda reiniciar) mientras el sink aún se está restaurando.

heartbeatSec

Tipo: Entero (mínimo 1)
Valor por defecto: 15
Descripción: Cada cuántos segundos renueva un job en ejecución su lease en MongoDB. Consulta Leases y heartbeats.
Cuándo cambiarlo: Rara vez. Un valor menor solo detecta antes los workers muertos de otros hosts si también bajas leaseStaleSec. leaseStaleSec debe ser al menos 3 veces este valor.

leaseStaleSec

Tipo: Entero (mínimo 30, y al menos 3 × heartbeatSec)
Valor por defecto: 300 (5 minutos)
Descripción: Un lease que no se renueva durante estos segundos es de un worker muerto: el barrido de jobs abandonados termina el job, o lo reanuda con autoResume. Un worker que no consigue renovar su propio lease durante este tiempo detiene su job.
Cuándo cambiarlo: Bájalo para detectar antes los workers que mueren en otro host (un worker del mismo host se detecta por su identificador de proceso en menos de un minuto). Súbelo si MongoDB puede quedar inaccesible durante minutos, para que un MongoDB lento no se tome por un worker muerto.

autoResume

Tipo: Booleano
Valor por defecto: false
Descripción: Con true, un job de pump, load o dump cuyo worker ha muerto o se ha detenido se pone en cola para ejecutarse de nuevo en el acto y reanudarse desde sus checkpoints, en lugar de terminar fallido. Funciona como la acción Restart del job: las entidades terminadas se saltan y las demás continúan donde se quedaron (consulta Reanudar un job fallido o interrumpido).
Cuándo cambiarlo: Actívalo para jobs largos sobre bases de datos grandes, donde un reinicio del servidor, un despliegue o un proceso terminado no deberían tirar horas de trabajo.

maxAutoResumes

Tipo: Entero (mínimo 0)
Valor por defecto: 3
Descripción: Cuántas veces se reanuda un job automáticamente. A partir de ahí, la siguiente interrupción falla el job. La cuenta se mantiene entre las ejecuciones del job; un Rerun la pone a cero.
Cuándo cambiarlo: Súbelo para jobs que duran días en una infraestructura que se reinicia a menudo.

concurrent

Tipo: Entero (mínimo 1)
Valor por defecto: 1
Descripción: El número mínimo de pipelines (lector, transformación y escritor) que un job procesa en paralelo, diga lo que diga la Concurrencia de sus opciones: el job usa el mayor de los dos. Los pipelines se reparten entre las entidades que se procesan en paralelo y los rangos de una tabla grande.
Cuándo cambiarlo: Súbelo para dar lecturas en paralelo a todos los jobs de la instancia sin editar las opciones de cada regla o job. Cada pipeline mantiene conexiones con el origen y el destino: mantenlo dentro de lo que aceptan tus bases de datos.

shardWorkers

Tipo: Entero (mínimo 0)
Valor por defecto: 0 (desactivado)
Descripción: Cuántos job workers más del mismo host ayudan a un job de pump a procesar los rangos de sus tablas grandes. Consulta Workers auxiliares de shards.
Cuándo cambiarlo: Configúralo cuando un único proceso job worker (un proceso Node.js) sea el cuello de botella de los pumps grandes. El host debe ejecutar suficientes job workers: consulta start (-j).

copy

Tipo: Booleano
Valor por defecto: true
Descripción: Los sinks Postgres cargan cada lote con COPY FROM STDIN en lugar de sentencias INSERT. Consulta Escrituras COPY en Postgres. Se aplica a todos los sinks Postgres de la instancia, salvo a un sink con copy: false en sus Custom Params, que usa siempre INSERT.
Cuándo cambiarlo: Ponlo a false solo si COPY da problemas con tu instalación de Postgres (por ejemplo, un proxy o pooler que no lo soporta).

logRetentionDays

Tipo: Entero (de 0 a 24855)
Valor por defecto: sin valor: se aplica jobLogRetentionDays, 90 días por defecto
Descripción: Días que se guardan en MongoDB las líneas de los logs de los jobs, 0 las guarda siempre. Si tiene valor, tiene prioridad sobre jobLogRetentionDays. Un índice TTL elimina las líneas más antiguas. Las líneas de un job que dura más que esto también se eliminan, mientras el job se ejecuta.
Cuándo cambiarlo: Configúralo cuando los logs de los jobs hagan crecer demasiado la base de datos MongoDB, como ocurre con muchos jobs largos sobre bases de datos grandes.

logTraceLevel

Tipo: Entero (mínimo 0)
Valor por defecto: 1
Descripción: Las líneas de traza más detalladas que se guardan en el log de un job cuyo pipeline no tiene nivel de log; si lo tiene, se aplica el del pipeline. El nivel 3 añade el SQL de cada consulta y el nivel 4 añade las líneas de cada lote. Con el valor por defecto 1 se omiten.
Cuándo cambiarlo: Súbelo a 3 o 4 durante un tiempo para diagnosticar un job. En tablas grandes estos niveles escriben líneas por cada lote y cada consulta, lo que puede suponer millones de líneas.

Cómo Funciona

Leases y heartbeats

Un job worker que inicia un job toma un lease sobre él, un documento de MongoDB con el dueño del job (host e identificador de proceso) y un número de época. Mientras el job se ejecuta, el worker renueva el lease cada heartbeatSec segundos.

La época protege el job: cada escritura de la ejecución (estado del job, checkpoints) comprueba que sigue teniendo la época con la que empezó. Si otro worker toma el job, la ejecución anterior ve que ha perdido su lease y se detiene sin volver a escribir en el job. Dos workers nunca escriben el mismo job.

worker A   toma el lease (época 7)
           |--beat--|--beat--|--beat--|    X  proceso terminado
                                             :
barrido                                      :  ...sin beat durante leaseStaleSec
                                             :  (o pid inexistente en el mismo host)
                                             v
                                       época 8: job fallido, o en cola para
                                       reanudarse con autoResume
worker B                                         toma el lease (época 9), reanuda

Barrido de jobs abandonados

Cada job worker ejecuta un barrido aproximadamente una vez por minuto. Revisa los jobs bloqueados como en ejecución y termina aquellos cuyo worker ya no está:

el dueño del lease está en el mismo host y su proceso ya no existe,
el lease no se ha renovado durante leaseStaleSec segundos,
o el job lleva leaseStaleSec segundos bloqueado y ningún worker llegó a tomar su lease.

El barrido protege primero el lease antiguo y después falla el job indicando el motivo (job interrupted: ...) o, con autoResume, lo pone en cola para reanudarse mientras le queden reanudaciones. Todos los workers hacen el barrido, pero solo uno actúa sobre cada job.

Cuando se detiene un job worker (SIGTERM o SIGINT, como hace gig stop), primero interrumpe sus jobs en ejecución: con autoResume los entrega para que se reanuden; si no, terminan fallidos con job interrupted: worker stopped.

Solo se reanudan los jobs de pump, load y dump. Los demás jobs (scans, discovery) cuyo worker ha muerto los falla el barrido.

Detección de jobs atascados

Además del lease, cada ejecución vigila su propio progreso: registros leídos y escritos, líneas de log y heartbeats. Las operaciones largas que no mueven registros (conteos, planificación, snapshots, reconstrucción de constraints, guardado del diccionario) envían heartbeats, que también aparecen en el log del job como mucho una vez por minuto por fase. Si no llega nada durante stallTimeoutSec segundos, el job falla como atascado. Un job atascado no se reanuda automáticamente: usa Restart para continuarlo desde sus checkpoints.

Workers auxiliares de shards

Cada proceso job worker ejecuta un job a la vez. Con shardWorkers mayor que 0, un pump que lee tablas grandes en rangos paralelos publica esos rangos como unidades en MongoDB y pone en cola hasta shardWorkers jobs auxiliares llamados pump-shard@<host>. Los job workers libres del mismo host los recogen y procesan unidades en paralelo con el pump, que también procesa unidades.

Los auxiliares solo se ejecutan en el host del pump: comparten el archivo de diccionario del job en su disco.
Escriben en el log del pump y no aparecen en las listas de jobs.
El pump suma su progreso al suyo y falla las unidades de un auxiliar que muere.
Una tabla grande se divide entonces en hasta Concurrencia × (1 + shardWorkers) rangos, para que todos los workers tengan trabajo.

Los auxiliares solo se usan cuando:

el job es un pump hacia un datasource de un driver de sink soportado: PostgreSQL, MySQL, Oracle o MongoDB (SQL Server mantiene ajustes de sesión como IDENTITY_INSERT en el proceso que preparó la carga, DB2 guarda las constraints que eliminó, y SQLite y los archivos tienen un único escritor);
el modo de carga no es merge ni update.

Si no hay ningún job worker libre en el host, los auxiliares esperan en la cola y el pump procesa las unidades él mismo.

Escrituras COPY en Postgres

Con copy: true un sink Postgres carga cada lote con COPY FROM STDIN, que es mucho más rápido que INSERT en cargas grandes. Las cargas merge y update hacen COPY a una tabla temporal de staging y ejecutan desde ella el upsert o el update en la misma transacción. Un lote que COPY no puede cargar se carga con INSERT; tras 3 lotes así, la tabla continúa con INSERT. Las tablas con columnas de tipo compuesto siempre usan INSERT.

Retención de logs

Con una retención mayor que 0 (logRetentionDays, o jobLogRetentionDays si no tiene valor), el servidor y los job workers crean (o modifican) un índice TTL sobre la fecha de las líneas del log de los jobs al arrancar, y MongoDB elimina en segundo plano las líneas más antiguas. Una retención de 0 elimina el índice. Reinicia el servidor después de cambiarlo.

Ejemplos

Configuración por defecto

La sección puede omitirse. Esto es equivalente:

jobs:
  stallTimeoutSec: 900
  autoResume: false
  concurrent: 1
  shardWorkers: 0

Perfil para bases de datos grandes

Un punto de partida para una instancia que ejecuta pumps de varias horas sobre bases de datos de muchos terabytes, en un host con al menos 5 job workers (gig start -j=6):

jobs:
  # consultas largas en el origen antes de las primeras filas
  stallTimeoutSec: 1800
  # reconstrucción de constraints de tablas muy grandes
  finishTimeoutSec: 172800
  heartbeatSec: 15
  leaseStaleSec: 300
  # un reinicio del servidor no pierde el trabajo hecho
  autoResume: true
  maxAutoResumes: 5
  # al menos 4 pipelines por job, tablas grandes leídas en rangos
  concurrent: 4
  # 3 workers más del host ayudan a cada pump
  shardWorkers: 3
  copy: true
  # guardar un mes de logs de jobs
  logRetentionDays: 30
  logTraceLevel: 1

Validación

El servidor comprueba la sección al arrancar y no arranca con un valor no válido, por ejemplo un número negativo, o un leaseStaleSec menor que 30 o menor que 3 veces heartbeatSec. El error indica la propiedad, por ejemplo:

leaseStaleSec must be 3 times heartbeatSec at least

Aplicar Cambios de Configuración

Reinicia la aplicación después de modificar la configuración de jobs:

./gig stop
./gig start

Los jobs que se están ejecutando cuando el servidor se detiene se interrumpen: con autoResume: true se reanudan cuando los job workers vuelven a arrancar.