huey_heartbeat: latido del proceso de tareas y la alerta HueyWorkerStalled

Propósito

Antes de este cambio, si el proceso de tareas periódicas (Huey, que corre las tareas de fondo del backend sobre Valkey) se caía o se quedaba colgado, nada lo detectaba: las tareas dejaban de ejecutarse en silencio hasta que alguien notaba un síntoma indirecto (un informe que no llegaba, una limpieza que no corría). huey_heartbeat cierra ese hueco dando al proceso de tareas un pulso que Prometheus/VictoriaMetrics puede vigilar.

Contrato

• Tarea: core.tasks.huey_heartbeat, decorada @db_periodic_task(crontab(minute="*")) — corre cada minuto dentro del propio proceso de tareas.
• Qué hace: guarda la hora actual (time.time()) en la caché compartida Valkey bajo la clave huey:last_beat (constante HUEY_HEARTBEAT_CACHE_KEY en core/metrics.py), sin caducidad (timeout=None) — si el proceso muere, la hora se queda vieja y no desaparece.
• Qué expone la web (el proceso Daphne/Django, que es lo único que VictoriaMetrics puede recoger vía /metrics; el propio proceso de tareas no se recoge):
  • crearack_huey_heartbeat_age_seconds (Gauge con función _huey_heartbeat_age): segundos desde el último latido leído en Valkey; +Inf si nunca hubo latido o si Valkey no responde.
  • crearack_huey_queue_size (Gauge ya existente, ahora con función _huey_pending_count): tareas pendientes en la cola, vía HUEY.pending_count(); NaN si no se puede leer — nunca rompe la recogida de métricas.
• Alerta: regla HueyWorkerStalled en observability/victoriametrics/alerts.yml, que dispara sobre crearack_huey_heartbeat_age_seconds cuando la edad crece por encima del umbral — un proceso de tareas caído o colgado ya no falla en silencio.

Dependencias

• Usa la caché de Django (backend Valkey) para el propio latido, y prometheus_client (Gauge.set_function) para exponerlo sin bloquear la recogida si Valkey o Huey fallan (ambas funciones atrapan la excepción y devuelven +Inf/NaN).
• La consume vmalert (VictoriaMetrics) evaluando alerts.yml.
• Activar la alerta en PROD exige recargar vmalert — desplegar el código no basta, porque vmalert solo relee su configuración al reiniciarse o recargarse explícitamente.

Ejemplo de uso

No es un endpoint ni algo que un usuario dispare: se observa desde fuera, vía /metrics o directamente en el panel de alertas de VictoriaMetrics. Sirve como plantilla para dar “latido” a cualquier otro proceso de fondo que hoy no se sabe si sigue vivo.

Véase también

• [[concept—general—escalabilidad-de-crearack-que-limites-tiene-la-arq]]
• [[entity—monitoring—test—metrics-read-write-contract]]