Heartbeats: monitorización de tareas programadas

Un heartbeat vigila una tarea programada: un cron, una copia de seguridad nocturna, la limpieza de un worker, la generación de un informe. El principio es el del interruptor de hombre muerto, en lugar de que Quiet Guard pregunte a su tarea si se ha ejecutado, es su tarea la que avisa a Quiet Guard en cada ejecución (un "ping"). Cuando los pings se detienen, usted recibe una alerta.

El problema que resuelve

El seguimiento de excepciones atrapa el código que falla ruidosamente: algo lanza una excepción, usted recibe un informe. Pero las averías más traicioneras son silenciosas:

• la entrada cron se perdió durante una migración de servidor,
• el scheduler está mal configurado (schedule:run ya no se invoca),
• la tarea falla tan pronto que ningún manejador de excepciones la ve,
• alguien desactivó el job "temporalmente" hace tres meses.

En todos estos casos nada lanza una excepción, así que nada se reporta. Su copia de seguridad nocturna simplemente deja de existir, y usted lo descubre el día en que la necesita. El heartbeat invierte la lógica: el silencio se convierte en la propia alerta.

Inicio rápido

El cableado recomendado es la macro del scheduler, encadenada directamente a la tarea en routes/console.php:

Schedule::command('backup:run')->daily()->monitorHeartbeat('nightly-backup');

La macro solo hace ping si la tarea tiene éxito, una tarea que falla permanece silenciosa y por lo tanto dispara la alerta de retraso. También puede hacer ping manualmente desde cualquier código:

php artisan monitor:heartbeat nightly-backup

o por HTTP (cualquier stack, no solo Laravel):

curl -X POST https://votre-monitor.example/api/v1/heartbeats/nightly-backup \
  -H "Authorization: Bearer <clé API du projet>"

Registro y armado

• El primer ping registra automáticamente el heartbeat en el proyecto. En ese momento está sin armar: los pings se registran, nada alerta jamás. Es intencionado: primero se conecta el ping, después se decide qué significa "con retraso".
• El armado se hace en el panel de control: abra la pestaña Heartbeats del proyecto, edite el heartbeat y defina su periodo esperado (la frecuencia con la que la tarea debe hacer ping, en minutos) más una tolerancia (retraso adicional aceptado: un scheduler rara vez cae en el segundo exacto).
• Un heartbeat sin periodo esperado sigue siendo un registro pasivo de pings, inofensivo para siempre.

Estados

Cada minuto, el servidor comprueba cada heartbeat armado: pasado último ping + periodo + tolerancia, pasa a con retraso y dispara una alerta por avería a través de los canales de notificación del proyecto suscritos al evento heartbeat.overdue (correo electrónico, Slack o webhook, vea Alertas). La protección contra tormentas de alertas se aplica.

La recuperación es silenciosa por diseño: el siguiente ping exitoso devuelve el heartbeat al estado sano, sin notificación. La alerta le dijo que la tarea está bloqueada; el panel de control muestra que ha vuelto a funcionar.

Elegir periodo y tolerancia

• Periodo = la planificación de la tarea. Diaria → 1440. Horaria → 60.
• Tolerancia = el retraso normal para esa tarea. Una copia de seguridad que tarda de 5 a 40 minutos merece una tolerancia generosa (60 por ejemplo); una tarea corta puede quedarse con los 5 por defecto.
• En caso de duda, sea generoso. Un falso "con retraso" a las 3 de la madrugada enseña a ignorar el canal: lo único que una alerta no debe hacer jamás.

Límites y detalles

• Los slugs se normalizan a minúsculas-y-guiones (nightly-backup); créelos en la interfaz con el mismo alfabeto, o deje que el primer ping los cree.
• Un proyecto contiene como máximo 200 heartbeats: una clave de API filtrada no puede inundar la tabla.
• Los pings se autentican con la clave de API del proyecto, como cualquier llamada de ingesta (referencia de la API).
• Los heartbeats con retraso aparecen en la vista general del proyecto (estadísticas de salud) y cuentan como actividad en el resumen semanal.