Heartbeat (cron y jobs)

El monitor Heartbeat invierte el modelo del monitoreo activo: en lugar de que StatusInspector compruebe un endpoint, es tu sistema quien envía periódicamente una señal de que un proceso sigue vivo y terminó correctamente.

Disponible en planes Pro y Enterprise.

---

¿Cuándo usarlo?

Usa Heartbeat para procesos que no tienen una URL pública que puedas monitorear externamente:

• Tareas cron y trabajos batch (backups nocturnos, sincronizaciones, generación de reportes).
• Pipelines ETL y workers internos.
• Scripts de renovación de certificados.
• Cualquier proceso periódico donde el silencio es la señal de fallo.

---

¿Cómo funciona?

1. Creas un monitor Heartbeat y configuras period (con qué frecuencia esperamos la señal) y grace (cuánto tiempo extra toleramos antes de declarar fallo).
2. StatusInspector te asigna una URL única con token con el formato https://statusinspector.com/h/<token>, visible en el panel.
3. Tu proceso llama a esa URL — con GET o POST — cada vez que termina una ejecución exitosa.
4. Si no llega ningún ping válido dentro de period + grace, el monitor pasa a DOWN y se abre un incidente.

---

Estados del monitor

Estado	Qué significa
unknown	El monitor fue creado pero aún no ha recibido el primer ping válido.
up	El último ping válido llegó dentro del periodo esperado.
degraded	El periodo venció pero aún está dentro del grace. El ping puede llegar a tiempo.
down	No hubo ping válido dentro de period + grace. Se abre un incidente.

El estado degraded (tardío) puede generar alertas si activas la opción Avisar cuando llegue tarde en la configuración del monitor. Cuando el ping finalmente llega, el monitor vuelve a UP y recibes la alerta de recuperación.

---

Parámetros de configuración

Parámetro	Descripción
Period	Intervalo esperado entre pings (ej. 1h, 24h, 15m). Define la frecuencia con la que tu proceso debe reportar.
Grace	Tiempo extra de tolerancia antes de pasar a DOWN. Debe cubrir el drift natural del sistema.
Avisar cuando llegue tarde	Si está activo, se envían alertas al entrar en estado tardío (degraded) y al recuperarse de él. Si está inactivo, solo se alerta en DOWN y en recuperación.

¿Cómo dimensionar el grace?

Los crons y trabajos reales no ejecutan exactamente en el segundo teórico: hay carga del servidor, colas, cambios de horario y retrasos operativos. Configura el grace para cubrir esa variabilidad habitual, no solo un margen mínimo. Por ejemplo:

• Un backup diario que tarda entre 20 y 40 minutos: grace de 60 minutos.
• Un ETL horario que puede demorarse por volumen variable: grace de 15–20 minutos.

---

Validación de payload (opcional)

Puedes hacer que StatusInspector no solo compruebe si llegó el ping, sino si el proceso terminó bien.

Sin validación (por defecto)

Cualquier petición válida al endpoint con el token correcto se cuenta como ping aceptado.

Con validación de estado

El cuerpo de la petición debe ser JSON con una clave específica (por defecto status) igual a ok. Si el payload no cumple la condición, el ping se registra como inválido y el monitor no avanza a UP.

{ "status": "ok" }

Puedes configurar la clave con notación de punto para campos anidados — por ejemplo result.state para una respuesta con estructura { "result": { "state": "ok" } }.

Esta validación detecta casos donde el proceso se ejecutó pero la lógica interna falló — algo que un check HTTP externo no podría detectar.

---

Timeline de eventos en el panel

Desde el detalle del monitor puedes ver el historial de pings recibidos:

• Fecha y hora de cada ping.
• Si el ping fue válido (avanzó el estado) o rechazado (payload inválido, según tu configuración).
• Las transiciones de estado (up → degraded → down → up).

Esta vista permite diagnosticar si un proceso dejó de ejecutarse, si llegó fuera de tiempo, o si empezó a reportar errores en el payload.

---

Rotación del token

Puedes rotar el token desde el panel en cualquier momento sin perder el historial del monitor. Después de rotar, actualiza la URL en tu proceso antes de que el token anterior expire.

---

Seguridad y rate limiting

El endpoint de ping tiene rate limiting por token y por IP para evitar abuso. Si superas el límite recibes una respuesta 429 con el header Retry-After indicando cuándo puedes reintentar.

Trata el token como un secreto: no lo registres en logs ni lo incluyas en código fuente sin cifrar. Cualquiera que tenga la URL puede enviar pings a tu monitor.

---

Integración en scripts

Copia la URL del monitor desde el panel (incluye el token ya incorporado).

Bash

#!/bin/bash

# Tu proceso aquí...
pg_dump mydb > /backups/mydb.sql.gz

# Señal al completar con éxito
curl -s "https://statusinspector.com/h/TU_TOKEN" > /dev/null

Bash con validación de payload

curl -s -X POST "https://statusinspector.com/h/TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"ok"}'

Python

import requests

def run_backup():
    # Tu proceso aquí
    pass

if __name__ == "__main__":
    run_backup()
    requests.get("https://statusinspector.com/h/TU_TOKEN", timeout=10)

Node.js

const https = require("https");

async function runJob() {
  // Tu proceso aquí
}

runJob().then(() => {
  https.get("https://statusinspector.com/h/TU_TOKEN").on("error", () => {});
});

PHP

// Tu proceso aquí

// Señal al completar con éxito
file_get_contents('https://statusinspector.com/h/TU_TOKEN');

tip

Envía el ping después de que el proceso termine correctamente — no al inicio. Así detectas tanto la ausencia de ejecución como los fallos durante la ejecución.

---

Diferencia con otros tipos de monitor

Aspecto	Heartbeat	HTTP / TCP / DNS
¿Quién inicia?	Tu sistema (push)	StatusInspector (pull)
¿Qué detecta?	Ausencia de señal / proceso no ejecutó	Endpoint no responde
¿Requiere URL pública?	No	Sí
Señal de fallo	Silencio superado el grace	Resultado del check activo