Incidentes de scheduler y colas

Cuándo usar este documento

Cuando una tarea programada no corrió, corrió a medias, o cuando el procesamiento asíncrono se detuvo.

Audiencia

Soporte e infraestructura.

Estado documental

• Estado: Borrador
• Última actualización: 2026-08-02
• Owner: Pendiente
• SME requerido: soporte técnico / infraestructura
• Fuente resumida: configuración de scheduler, cron y workers de cola.

Síntomas

Síntoma	Ir a
Ninguna tarea del día corrió	El cron está caído
Una tarea no corrió, las demás sí	Una tarea concreta falló
Los comandos terminan bien pero nada cambia	Los workers están caídos
Se acumulan trabajos fallidos	Trabajos fallidos que no se resuelven
Una etapa procesó menos de lo esperado	La cadena se desfasó

El cron está caído

Síntoma: los logs del día están vacíos. No hay errores porque no hay nada.

Diagnóstico:

crontab -l

Debe existir una entrada de schedule:run para cada instancia de participante.

Recuperación:

1. Restaurar la entrada de cron. Vive en el repositorio server-configs.
2. Ejecutar manualmente las tareas del día que no corrieron, respetando el orden de la cadena y fuera de la ventana automática.
3. Verificar que la siguiente tarea programada corre sola.

No basta con arrancar el cron

Restaurar el cron no recupera lo que no corrió hoy. Hay que ejecutar las tareas perdidas a mano, en orden.

Una tarea concreta falló

Diagnóstico: buscar la entrada del día en el log correspondiente.

Tarea	Log
queue:retry all, ecd:sync	ecd-sync.log
ecd:create_invoices, ecd:upload_invoices_to_s3, ecd:upload_invoices, ecd:invoices_status, bot de REA	cenace-process.log
service:demand-sync	service-process.log

Recuperación: reejecutar la tarea con los mismos parámetros que usa el scheduler, fuera de la ventana de 05:00 a 08:30.

La fecha importa

ecd:sync usa la fecha de hace 5 días. Al reejecutarlo, pasar la fecha de operación correcta, no la de hoy.

Los workers están caídos

Síntoma: los comandos reportan éxito, la cola crece y nada se procesa.

Diagnóstico:

sudo supervisorctl status

Todos los programas deben estar en RUNNING.

Recuperación:

sudo supervisorctl restart <programa>

Después, reintentar los trabajos que quedaron pendientes:

php artisan queue:failed
php artisan queue:retry all

Causa frecuente: un despliegue reinicia los workers. Si un worker no volvió a levantar después de un despliegue, es aquí donde se nota.

Trabajos fallidos que no se resuelven

Síntoma: los mismos trabajos aparecen en queue:failed día tras día, pese al reintento automático de las 05:00.

Diagnóstico: leer el error concreto. Reintentar sin entenderlo solo repite el resultado.

Error típico	Causa
Credenciales o permisos de AWS	Configuración de la instancia.
Timeout contra un servicio externo	El servicio externo no responde.
Dato faltante o inconsistente	El trabajo depende de información que no llegó.
Memoria o tiempo excedido	El volumen del trabajo superó el límite del worker.

Recuperación: corregir la causa y después reintentar. Si el error es de datos, reintentar no ayuda: hay que corregir el origen.

La cadena se desfasó

Síntoma: una etapa corrió, no dio error, pero procesó menos de lo esperado.

Causa: la cadena diaria tiene tiempos fijos entre etapas. Si una tarda más de su ventana, la siguiente arranca igual y solo procesa lo que ya estaba listo.

Diagnóstico: comparar cuántos elementos procesó cada etapa contra lo esperado, revisando los logs en orden cronológico.

Recuperación: reejecutar las etapas posteriores una vez que la etapa lenta terminó, en orden y fuera de la ventana automática.

Validación posterior

1. La tarea aparece en su log con resultado correcto.
2. queue:failed no creció.
3. Los datos esperados existen: ECD, facturas, demanda, según el caso.
4. La siguiente ejecución programada corre sola.

Escalamiento

• El cron o los workers vuelven a caer sin causa identificada.
• Los trabajos fallidos se repiten tras corregir la causa aparente.
• El desfase de la cadena afectó documentos fiscales.

Evidencia mínima

• Fecha, hora e instancia del participante.
• Tarea o comando afectado.
• Fragmento de log sanitizado.
• Estado de cron y de Supervisor al momento del incidente.
• Acción tomada y resultado.

Riesgos y gaps

• No hay alerta cuando el cron se detiene.
• No hay alerta cuando un worker cae.
• No está documentado el tiempo esperado de cada etapa, así que "se desfasó" es hoy un juicio, no una medición.

Próxima revisión

Tras la validación de infraestructura.