Diagnóstico de batch, scheduler y bots
Cuándo usar este documento
Cuando algo automático no ocurrió y no está claro por dónde empezar. Es el punto de entrada de los demás playbooks.
Audiencia
Soporte e infraestructura.
Estado documental
- Estado: Borrador
- Última actualización: 2026-08-02
- Owner: Pendiente
- SME requerido: soporte técnico / infraestructura
- Fuente resumida: arquitectura de ejecución del sistema y configuración de scheduler y colas.
La regla que resuelve la mitad de los casos
En sy-energy el trabajo se ejecuta por tres caminos, y cada uno falla en silencio de forma distinta:
| Camino | Cómo falla |
|---|---|
| Cron → scheduler | Si el cron está caído, no hay error: simplemente no hay entradas en el log. |
| Comando → cola | El comando reporta éxito al encolar. Si el worker está caído, nada se procesa y nadie lo reporta. |
| Comando → bot → Lambda | El comando reporta éxito al publicar el mensaje. Lo que pase después ocurre fuera de este sistema. |
Por eso la primera pregunta nunca es "¿qué error dio?" sino "¿llegó a ejecutarse?".
Diagnóstico en orden
Recorrer de arriba hacia abajo. Cada nivel supone que el anterior está sano.
Nivel 1 — ¿Corrió el motor?
bash
# ¿Existe el cron de esta instancia?
crontab -l
# ¿Están arriba los workers?
sudo supervisorctl status| Hallazgo | Qué significa |
|---|---|
| Cron ausente o comentado | Ninguna tarea programada corrió. Todo lo demás es consecuencia. |
Workers en estado distinto de RUNNING | Todo lo asíncrono está detenido: cálculos, facturas, respuestas de bots. |
Un log vacío es un síntoma, no una buena noticia.
Nivel 2 — ¿Corrió la tarea?
Revisar en storage/logs de la instancia:
| Log | Tareas que registra |
|---|---|
ecd-sync.log | Reintento de fallidos y sincronización de ECD. |
cenace-process.log | Facturas, carga a S3, carga al SIM, estatus y REA. |
service-process.log | Sincronización de demanda. |
| Hallazgo | Qué significa |
|---|---|
| No hay entrada del día | La tarea no se ejecutó. Volver al nivel 1. |
| Hay entrada y termina con error | La tarea corrió y falló. Ir al nivel 3. |
| Hay entrada, sin error, pero procesó menos de lo esperado | Una etapa anterior de la cadena no terminó a tiempo. |
Nivel 3 — ¿Se procesó el trabajo?
bash
php artisan queue:failed| Hallazgo | Qué significa |
|---|---|
| Vacío y sin efecto visible | Los trabajos se encolaron pero nadie los procesó. Revisar workers. |
| Fallidos de hoy | Leer el error antes de reintentar. |
| Fallidos acumulados de varios días | El reintento automático de las 05:00 no resuelve el problema de fondo. Escalar. |
Nivel 4 — ¿Respondió el sistema externo?
Cuando el trabajo sí se procesó y aun así no hay resultado, el problema está fuera:
| Integración | Cómo se ve la falla |
|---|---|
| API de CENACE | No llegan ECD; error en el log de sincronización. |
| Bots del SIM | El mensaje se publicó pero nunca hubo respuesta. |
| Factura.com | Facturas que no se timbran. |
| MEM | Cálculos de precios en cero. |
Preguntas para acotar
| Pregunta | Por qué importa |
|---|---|
| ¿En qué instancia de participante? | Cada una tiene su base, colas y logs. Un problema en una no se ve desde la otra. |
| ¿Qué fecha de operación, no qué día de ejecución? | Los procesos trabajan con desfase; confundirlas lleva a conclusiones falsas. |
| ¿Cuándo funcionó por última vez? | Acota si es un cambio reciente o un problema acumulado. |
| ¿Qué impacto tiene? | Facturación y demanda son prioritarios; un reporte puede esperar. |
| ¿Es seguro reintentar? | No todos los comandos son idempotentes. |
Antes de reintentar
Tres verificaciones obligatorias
- Instancia correcta. Confirmar el participante antes de escribir el comando.
- Fuera de la ventana automática. Entre 05:00 y 08:30 el scheduler está corriendo la cadena; ejecutar lo mismo a mano puede duplicar procesamiento.
- Alcance acotado. Empezar con un día o un centro de carga antes de lanzar un rango completo.
Escalar a desarrollo
Sin intentar corregir por cuenta propia, cuando:
- se emitieron documentos fiscales incorrectos o duplicados;
- los mismos trabajos fallan día tras día con el mismo error;
- un cálculo produce importes que no cuadran y la fuente sí está completa;
- hay que revertir algo que ya se escribió en base de datos.
Evidencia mínima
- Fecha y hora del incidente.
- Instancia del participante.
- Comando, tarea o bot involucrado.
- Fragmento de log sanitizado: sin credenciales, RFC ni datos personales.
- Qué se intentó y qué resultado dio.
Playbooks específicos
- Incidentes de scheduler
- Incidentes de CENACE / ECD
- Incidentes de CFDI / Factura.com
- Incidentes de demanda
Riesgos y gaps
- No hay alertamiento: todos los diagnósticos empiezan porque alguien notó algo.
- No existe un tablero de estado de la cadena diaria.
- No está documentada la idempotencia de los comandos, que es justo lo que hace falta saber para decidir si reintentar.
Próxima revisión
Tras la validación de soporte.