SKEEN-Proyecto/docs/healthcheck.md

Monitoreo SKEEN con alertas por WhatsApp (skeen-healthcheck)

Actualizado: 2026-09-08

Qué es

Healthcheck cada 15 minutos (systemd timer) de todos los servicios de la VM. Si un componente falla 2 corridas seguidas (con 1 reintento interno de 5 s por corrida para descartar reinicios transitorios), envía una alerta por WhatsApp a los destinatarios configurados. Al recuperarse, envía un aviso de recuperación. Una sola alerta por incidente (no re-alerta cada 15 min del mismo fallo).

Componentes monitoreados

Check	Qué verifica
odoo_web	HTTP 200 en :8069/web/login
frontend_nginx	HTTP 200 del vhost nginx (Host skeen.consultoria-as.com → /)
wacrm	HTTP 200 en :3000/login
hermes_gateway	HTTP 200 en :8080/health
hermes_bridge	HTTP 200 en :8090/health
cloudflare_tunel	HTTP 200 en https://skeen.consultoria-as.com/ (túnel + nginx)
svc_*	systemctl is-active de: odoo-skeen, hermes-gateway, hermes-bridge, cloudflared-skeen, nginx

Salida OK/FAIL por componente al journal (journalctl -u skeen-healthcheck). Exit code 1 si hubo fallos.

Archivos

Ruta	Uso
/root/scripts/healthcheck.py	Script principal (checks + lógica de alertas)
/root/scripts/healthcheck_alerts.conf	Destinatarios de WhatsApp, un número E.164 por línea (# = comentario). Ej. México: 526644990030. Editar el archivo y listo — no requiere reiniciar nada
/root/scripts/healthcheck_state.json	Estado persistente (fallos consecutivos, alertado, hora de caída). Se regenera solo; se puede borrar para resetear incidentes

Servicios systemd

• skeen-healthcheck.service — oneshot que corre el script.
• skeen-healthcheck.timer — cada 15 min (OnCalendar=*:0/15, Persistent=true).

systemctl list-timers skeen-healthcheck.timer   # ver próxima corrida
systemctl start skeen-healthcheck.service       # correr a mano
journalctl -u skeen-healthcheck -n 50           # ver resultados

Envío de alertas

Vía la API v1 del WACRM (envío real por Meta):

POST http://127.0.0.1:3000/api/v1/messages
Authorization: Bearer wacrm_live_ffac5531d76645acb239dba71ace6d1c
{"to": "+526644990030", "type": "text", "text": "⚠️ SKEEN: ..."}

Devuelve 201 en éxito; crea contacto/conversación automáticamente si no existen. Mensajes: ⚠️ SKEEN: <componente> NO responde desde las HH:MM. Revisar. (fallos agrupados en un mensaje) y ✅ SKEEN: <componente> recuperado. Si el envío falla, se reintenta en la siguiente corrida (no se marca alertado).

Cómo agregar/quitar checks

Editar la lista CHECKS en /root/scripts/healthcheck.py:

('id_check', 'http', ('http://127.0.0.1:PUERTO/ruta', {200})),          # web
('id_check', 'http', ('https://dominio/', {200}, None, 20)),            # web + timeout
('id_check', 'http', ('http://127.0.0.1/', {200}, {'Host': 'dom'})),    # vhost por Host
('svc_unidad', 'systemd', ('nombre-unidad',)),                          # systemd

Y su nombre legible en NOMBRES (es el que sale en el mensaje de WhatsApp).

⚠️ Limitación conocida (importante)

Meta rechaza la entrega de mensajes salientes a un número cuyo cliente no ha escrito en las últimas 24 horas (regla de WhatsApp; no hay plantillas aprobadas aún). Efecto observado en la prueba real del 2026-09-08: los 3 mensajes de alerta a Ivan salieron (Meta asignó wamid) pero quedaron en estado failed porque su ventana de 24 h estaba cerrada (último mensaje suyo: 3-sep).

• Mientras no haya plantillas: las alertas solo llegan a números que escribieron al número de la clínica en las últimas 24 h. Para activar a un destinatario nuevo, pedirle que mande un WhatsApp al número de la clínica (abre la ventana 24 h).
• Solución definitiva: cargar plantillas aprobadas en el WACRM (Settings → Templates) y enviar las alertas como plantilla. Pendiente del cliente.
• El estado failed no rompe el monitoreo: el script marca el incidente como alertado y no re-spamea.

Prueba real del 2026-09-08

1. systemctl stop hermes-bridge → 2 corridas del check → alerta enviada: ⚠️ SKEEN: Hermes Bridge NO responde desde las 06:04 y servicio hermes-bridge NO responde desde las 06:04. Revisar.
2. systemctl start hermes-bridge → corrida siguiente → 2 avisos: ✅ SKEEN: Hermes Bridge recuperado. / ✅ SKEEN: servicio hermes-bridge recuperado.
3. Entrega bloqueada por la ventana 24 h (ver arriba). Los mensajes quedaron guardados en el WACRM como evidencia.