HyperV Monitor — Monitor de Clusters Hyper-V

1. Acceso al sistema

2. Qué hace el sistema

1. Polling de clusters — Cada 5 minutos (configurable) ejecuta remotamente via PowerShell collect_cluster_data.ps1 en cada cluster habilitado. El script usa Invoke-Command para obtener el estado de nodos y CSVs sin credenciales explícitas (usa la cuenta de servicio del proceso Windows).
2. Persistencia — Hace upsert del estado actual de nodos y volúmenes, y guarda un punto en la serie temporal de cada CSV para las gráficas de historial.
3. Evaluación de umbrales — Para cada volumen, compara el espacio libre (en % y en GB) con los umbrales configurados (por volumen, por cluster o global). Si cualquiera de los dos umbrales se supera, activa la alerta.
4. Notificación SisAlerts — POST a /api/ingest de SisAlerts con deduplicación por external_id. Respeta un cooldown (default 4h) para no enviar spam, pero siempre reenvía si la severidad empeora.
5. Auto-resolución — Cuando el espacio se recupera por encima del umbral, la alerta se cierra automáticamente.

3. Sistema de umbrales en cascada

Tanto el umbral en porcentaje de espacio libre como en GB libres se evalúan independientemente. La alerta salta si cualquiera de los dos se supera.

Severidades

4. Panel web

Dashboard (/)

• Estado global: número de clusters, nodos up/down, alertas activas.
• Por cluster: tabla de CSVs con espacio libre (%), espacio libre (GB), tamaño total, nodo propietario, estado y barra visual de uso.
• Alertas activas en color rojo/naranja con enlace a SisAlerts.
• Botón Poll ahora: fuerza un ciclo de polling inmediato.

Detalle de cluster

• Gráfica de historial de espacio libre para cada volumen (últimas 24h / 7d / 30d).
• Estado de los nodos (Up/Down, tiempo de actividad).
• Log de los últimos ciclos de polling (duración, errores).

Alertas (/alerts)

• Historial de alertas con fechas de creación, envío y resolución.
• Indicador de si la alerta fue enviada correctamente a SisAlerts.

5. Integración SisAlerts

Cuando un volumen supera el umbral, se envía un POST al endpoint /api/ingest de SisAlerts:

POST {sisalerts.url}/api/ingest
X-Api-Key: {sisalerts.api_key}
Content-Type: application/json

{
  "source":      "hyperv-monitor",
  "sender":      "hyperv-monitor",
  "priority":    "critical" | "high",
  "external_id": "hvmon-{cluster_id}-{volume_name}",
  "subject":     "CSV crítico: {volume_name} — X% libre (Yz GB)",
  "body_html":   "...",
  "rule_id":     5
}

6. Administración

7. Configuración (app-config.json)

8. Arquitectura técnica

Flujo completo

scheduler._run_loop() cada 300s
  → por cada cluster habilitado:
     collect_cluster_data.ps1 (Invoke-Command remoto)
       NDJSON: nodos + CSVs con tamaño/espacio libre
     update_db(): upsert nodos, csvs, csv_history
     alert_manager.evaluate_thresholds():
       por cada CSV:
         resolver umbral_pct y umbral_gb (volumen → cluster → global)
         si free_pct ≤ umbral_pct OR free_gb ≤ umbral_gb:
           crear/actualizar alerta en DB
           si cooldown superado o sent_at es NULL: POST /api/ingest → SisAlerts
         si espacio recuperado: auto-resolver alerta
  → purge cada hora (csv_history + poll_log + alertas resueltas antiguas)

Tablas de base de datos

9. PowerShell Remoting

El script scripts/collect_cluster_data.ps1 usa Invoke-Command -ComputerName <ClusterName> sin credenciales explícitas. La cuenta del servicio Windows debe tener permisos de administrador Hyper-V en todos los clusters.

# Salida NDJSON por stdout (un objeto JSON por línea):
{"type":"node","name":"HV01","state":"Up","uptime_hours":720}
{"type":"csv","name":"Cluster Disk 1","size_bytes":1099511627776,"free_bytes":219902325555,"state":"Online","owner_node":"HV01"}

10. Despliegue

Requisitos

• Windows Server con Python 3.x
• SisAlerts funcionando y accesible (para las notificaciones)
• Acceso WinRM/PowerShell Remoting hacia los clusters Hyper-V
• Cuenta de servicio con permisos de administrador en los clusters

Deploy

cd C:\apps\jmfernandez\hypervmonitor

# deploy.ps1: git pull + pip install sisapps-ui + restart servicio
.\deploy.ps1

# O deploy global de todas las apps:
cd C:\apps\jmfernandez\sisapps-hub
.\sisapps_deploy.ps1