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).

Ciclo de vida

• El primer ping registra automáticamente el heartbeat en su proyecto, sin armar: los pings se registran, nada alerta jamás. Primero conecta el ping, después decide qué significa "con retraso".
• 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 no expone el armado; solo hace ping.
• 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.