Heartbeats

El SDK puede hacer ping a un heartbeat en el servidor Quiet Guard cada vez que se ejecuta una de sus tareas programadas. El servidor funciona como un interruptor de hombre muerto: una vez que el heartbeat está armado con un periodo esperado, la ausencia de pings dispara una alerta de retraso. Una entrada cron perdida, un schedule:run olvidado, una tarea desactivada "temporalmente": el silencio se convierte en la propia alerta. El concepto completo (estados, armado, canales de alerta) se detalla en la documentación del servidor.

La macro del scheduler (recomendada)

El SDK registra una macro monitorHeartbeat() en los eventos programados de Laravel. Encadénela directamente a la tarea que desea vigilar, en routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:send')->daily()->monitorHeartbeat('reports-send');

Dos propiedades hacen de la macro el cableado recomendado:

• Solo hace ping cuando la tarea tiene éxito (se engancha al onSuccess del scheduler). Una tarea que falla o termina con un código distinto de cero no envía nada, permanece silenciosa y por lo tanto dispara la alerta de retraso. Hacer ping antes de la tarea, o incondicionalmente después, anularía todo el sentido del mecanismo.
• Respeta las salvaguardas del SDK en el momento de la ejecución: si MONITOR_ENABLED=false, o si el entorno actual no figura en la lista MONITOR_ENVIRONMENTS, el ping se omite. Un scheduler de staging que ejecuta el mismo código nunca hace ping, por tanto, a sus heartbeats de producción. Consulte Configuración.

Ping manual

También puede hacer ping desde cualquier código con el comando Artisan, por ejemplo desde una línea cron directa después de un script de shell:

php artisan monitor:heartbeat reports-send

Si MONITOR_ENABLED=false, el comando muestra una advertencia y no envía nada. Termina con un código de fallo cuando el ping no puede entregarse (verifique MONITOR_URL / MONITOR_KEY).

Heartbeats automáticos

Desde la versión 0.4, el SDK vigila dos cosas por sí solo, en producción, sin una línea por su parte:

• El scheduler. Cada vez que schedule:run arranca (desde cron, y en cada subproceso que lanza schedule:work), hace ping al heartbeat scheduler. El primer arranque solo registra la hora; a partir del segundo, el ping lleva el intervalo observado como periodo (1 a 1440 minutos) y una tolerancia de periodo más 4 minutos, topada en 1440 minutos. Así, con un cron cada minuto, el heartbeat aparece a los dos minutos; con un cron horario, a las dos horas. Un schedule:run escrito a mano en una terminal se ignora, ni se registra ni se hace ping, para que una prueba manual nunca arme una cadencia equivocada. Varios servidores que lanzan el mismo cron sobre una caché compartida cuentan como un solo scheduler: un arranque a menos de 30 segundos del registrado se toma por ese mismo arranque.
• Sus colas. Cada worker queue:work (Horizon incluido) hace ping, en cada vuelta de su bucle e incluso sin ningún job que procesar, a un heartbeat queue-{conexión}-{cola} por cada cola que consume y que está vigilada, como máximo una vez por minuto y por cola. No se añade nada a la cola, ningún job de prueba: el ping viene de la propia vuelta del bucle. La tolerancia es de nueve minutos, o el --timeout del worker más un minuto cuando es mayor (Laravel 13.10 o posterior; las versiones anteriores mantienen nueve minutos), topada en 1440 minutos. Un heartbeat de cola con retraso alerta por sí mismo, con independencia del scheduler. El retraso de la cola que se muestra en la pestaña Heartbeats es la espera más corta observada, desde el ping anterior, entre que un job se pone en cola y un worker lo toma; un valor ausente significa que el worker que envió el ping no midió ninguna, aunque otros workers de la cola hayan podido tomar jobs, y un reintento nunca se mide. En Laravel 11, y en Laravel 12 antes de la 12.11, cuyo job no lleva marca de creación, no se mide nada y el retraso permanece vacío.

Estos heartbeats se arman solos en el primer ping que lleve lo necesario para armarse: no se crea nada hasta que el scheduler o un worker haya funcionado al menos una vez, y una aplicación sin colas nunca recibe una alerta al respecto. El periodo y la tolerancia se fijan al crearse: el SDK nunca vuelve a armar un heartbeat existente, ni siquiera el suyo propio.

Para vigilar otras colas, o ninguna:

# Varias colas, con el formato conexión:cola
MONITOR_QUEUE_HEARTBEATS=redis:default,redis:emails
# Ninguna cola
MONITOR_QUEUE_HEARTBEATS=false
# Sin heartbeat del scheduler
MONITOR_SCHEDULER_HEARTBEAT=false
# Entornos afectados (producción por defecto)
MONITOR_HEARTBEAT_ENVIRONMENTS=production

Estos heartbeats usan su store de caché por defecto. El del scheduler necesita uno que sobreviva al proceso (archivo, base de datos, Redis): con el store array cada schedule:run parte de una caché vacía, así que el heartbeat del scheduler nunca se envía, un fallo silencioso y sin consecuencias. Los pings de cola siguen saliendo con el store array, pero cada proceso worker hace entonces ping por su cuenta en lugar de un ping por cola para todos los workers. Cambiar MONITOR_KEY cambia las claves de caché, así que el siguiente arranque vuelve a contar como el primero. Un worker cuyo ping falla no envía ningún ping de cola durante el minuto siguiente: un servidor Quiet Guard inalcanzable le cuesta a cada worker un MONITOR_TIMEOUT por minuto, sea cual sea el número de colas. Para desactivar un heartbeat automático, cambie la variable y después elimine la fila en la pestaña Heartbeats: el SDK nunca vuelve a armar una fila existente.

Un heartbeat de cola puede quedar retrasado sin que nada esté roto, porque un worker solo hace ping entre dos jobs, y solo mientras recorre su bucle. Los casos conocidos:

• un modo de mantenimiento más largo que la tolerancia: el worker deja de recorrer su bucle hasta que la aplicación vuelve, salvo si se ejecuta con --force;
• un worker en pausa, mediante php artisan horizon:pause o una señal SIGUSR2 enviada a queue:work;
• un solo job más largo que la tolerancia, incluido un job cuyo propio $timeout supera el --timeout del worker: la tolerancia sigue la opción del worker, mientras que el valor del job prevalece durante la ejecución;
• workers que solo se inician de vez en cuando, por ejemplo queue:work --stop-when-empty desde cron o desde el scheduler, con menos frecuencia que la tolerancia (nueve minutos por defecto);
• queue:listen y queue:work --once, que nunca recorren un bucle y por tanto nunca hacen ping: una cola que pasa a ellos después de que un queue:work haya creado su heartbeat queda retrasada.

En cada uno de estos casos, amplíe la tolerancia de ese heartbeat en la pestaña Heartbeats (el SDK nunca vuelve a armar una fila existente, así que su valor se mantiene), o excluya la cola de MONITOR_QUEUE_HEARTBEATS y elimine su fila.

Ciclo de vida

• El primer ping registra automáticamente el heartbeat en su proyecto. Uno conectado con la macro o el comando nace sin armar: los pings se registran y nada alerta hasta que usted defina un periodo. Los heartbeats automáticos son la excepción: llegan con su periodo y nacen armados.
• El armado se hace en el panel de control: abra la pestaña Heartbeats del proyecto y defina el periodo esperado (más una tolerancia). El SDK solo arma sus propios heartbeats automáticos, y solo al crearlos.
• La recuperación es silenciosa: después de una avería, el siguiente ping exitoso devuelve el heartbeat al estado sano, sin notificación.

Reglas de slug

Un slug de heartbeat identifica la tarea: letras minúsculas, dígitos y guiones simples (reports-send, nightly-backup). El servidor normaliza todo lo demás; use ese alfabeto desde el principio y mantenga el slug idéntico entre la macro y el panel de control.

Siguiente paso

Continúe con las Copias de seguridad cifradas, el complemento natural: un heartbeat en su tarea de copia de seguridad le avisa el día en que deja de ejecutarse.