Monitoreo de trabajos cron con heartbeats: un tutorial práctico

Los trabajos cron que se ejecutan correctamente son fáciles. Los trabajos cron que fallan de forma ruidosa también son fáciles: el correo de error llega a tu bandeja de entrada. Los difíciles son los trabajos cron que dejan de ejecutarse por completo. El servidor se reinicia, el contenedor es desalojado, la cuenta de usuario se deshabilita, el temporizador de systemd queda enmascarado por un cambio de configuración. El trabajo nunca se ejecuta, no se produce ningún error y te enteras tres semanas después, cuando los respaldos que asumías que estaban ocurriendo ya no existen. El monitoreo por heartbeats detecta exactamente este modo de fallo.

Cómo funciona el monitoreo por heartbeats

Un monitor de heartbeats invierte la relación habitual de sondeo. En lugar de que un sondeador externo llame a tu servicio, es tu trabajo el que llama al monitor. Defines una ventana de gracia (por ejemplo, «este trabajo debe enviar ping cada hora, dale cinco minutos de margen»). Cuando el monitor deja de recibir pings, abre un evento de inactividad y te alerta.

El resultado es un interruptor de hombre muerto. Mientras el trabajo se ejecute e informe de su éxito, el monitor permanece en silencio. En el momento en que no logra enviar ping (porque se ha caído, porque el servidor está apagado, porque alguien desactivó el temporizador), salta la alerta. Tres semanas de fallo silencioso de respaldos se convierten en un incidente de cinco minutos.

Cuándo usar heartbeats frente a comprobaciones regulares

Los heartbeats no son un reemplazo del monitoreo HTTP. Cubren una clase distinta de trabajo: cualquier cosa que se ejecute fuera de banda según un horario.

• Trabajos de respaldo: volcados nocturnos, sincronización con S3, rsync externo.
• Ejecuciones de canalizaciones de datos: trabajos ETL, generación de informes diarios, conciliación de facturación.
• Correos de marketing programados: boletín semanal, campañas de goteo.
• Trabajos de renovación de SSL: certbot, acme.sh.
• Cualquier cosa que se ejecute en cron, temporizadores de systemd, programaciones de GitHub Actions, cron de Cloudflare Workers o AWS EventBridge.

Cómo añadir un heartbeat a un trabajo cron de bash

El patrón más sencillo es una única llamada curl al final del script. La URL del heartbeat es única para cada monitor; no la subas al control de versiones.

Un patrón que gestiona fallos de forma elegante: `do_the_work && curl -fsS --retry 3 https://your-monitor.example/heartbeat`. El && solo dispara el heartbeat si el trabajo real se completa con éxito. El --retry 3 cubre las interrupciones puntuales de red. El -fsS hace que curl sea silencioso en caso de éxito y ruidoso en caso de fallo, que es lo que cron necesita.

Heartbeats desde Python y Node

El mismo patrón en dos lenguajes habituales. Ambos envuelven el trabajo en un try/except y solo notifican el éxito tras una ejecución limpia.

• Python: `try: do_the_work(); requests.post('https://your-monitor.example/heartbeat', timeout=10); except Exception: logger.exception('job failed')`
• Node: `try { await doTheWork(); await fetch('https://your-monitor.example/heartbeat', { method: 'POST' }); } catch (err) { console.error('job failed', err); }`
• Importante: no envíes el heartbeat en un bloque finally. Finally se ejecuta tanto en caso de éxito como de fallo. El heartbeat debe ser una señal positiva, no una señal de «se ejecutó».

Configurar la ventana de gracia

La ventana de gracia es la perilla que más se suele ajustar mal. Demasiado corta y obtienes falsas alarmas cuando el trabajo se ejecuta con unos segundos de retraso. Demasiado larga y un fallo real pasa desapercibido durante horas.

Una buena regla general es 2 veces la duración normal del trabajo más 5 minutos. Una copia de seguridad nocturna que normalmente tarda 8 minutos requiere una ventana de gracia de 8 * 2 + 5 = 21 minutos. Un trabajo semanal que tarda 2 horas requiere una ventana de gracia de 2 * 2 + 0,5 = 4,5 horas. La ventana de gracia te protege de variaciones inofensivas, no de fallos reales.

Patrones de heartbeat habituales que conviene configurar primero

Si empiezas desde cero, tres heartbeats capturan la mayoría de los fallos silenciosos que afectan a la gente. Un monitor de copia de seguridad nocturna con una ventana de gracia de 6 horas. Un monitor de renovación de SSL en el cron que ejecuta certbot o acme.sh, con una ventana de gracia de una semana. Un monitor de informe diario o de conciliación de facturación con una ventana de gracia de 90 minutos. Juntos, estos tres capturan los modos de fallo con las ejecuciones desapercibidas más largas y las mayores consecuencias. Una vez establecidos, añade con el tiempo un heartbeat a cada uno de los demás trabajos programados.