Agent Health

GET /health/agent

Get comprehensive agent node health with dependency analysis

Performs dynamic health checks for all agent node dependencies including Host API connectivity, KVM module status, Libvirt socket availability, network bridge configuration, NTP synchronization, and Ceph storage health. Calculates overall health percentage and provides detailed dependency status. Returns WARNING if some dependencies are down, DOWN if all are down, UP if all are healthy.

Status Codes:

  • 200 OK – Complete agent health assessment” example({“overall_status”:”WARNING”,”health_percentage”:71.4,”total_checks”:7,”healthy_checks”:5,”unhealthy_checks”:2,”check_duration_ms”:1250,”dependencies”:[{“name”:”Host API”,”status”:”UP”,”latency_ms”:45},{“name”:”KVM Module”,”status”:”UP”,”latency_ms”:12},{“name”:”Libvirt Socket”,”status”:”DOWN”,”latency_ms”:5000,”error”:”Libvirt daemon not running”,”error_count”:1}]})

  • 500 Internal Server Error – Internal server error during health checks” example({“error”:”Failed to perform health checks”})

Response JSON Object:

  • check_duration_ms (integer)

  • dependencies[].error (string)

  • dependencies[].error_count (integer)

  • dependencies[].latency_ms (integer)

  • dependencies[].name (string)

  • dependencies[].services[].failed (integer)

  • dependencies[].services[].instances[].container_id (string)

  • dependencies[].services[].instances[].host (string)

  • dependencies[].services[].instances[].name (string)

  • dependencies[].services[].instances[].status (string)

  • dependencies[].services[].running (integer)

  • dependencies[].services[].service_type (string)

  • dependencies[].services[].status (string)

  • dependencies[].services[].total (integer)

  • dependencies[].status (string)

  • dependencies[].summary.failed (integer)

  • dependencies[].summary.running (integer)

  • dependencies[].summary.total (integer)

  • dependencies[].system_vm_summary.non_running (integer)

  • dependencies[].system_vm_summary.running (integer)

  • dependencies[].system_vm_summary.total (integer)

  • dependencies[].system_vms[].agent_state (string)

  • dependencies[].system_vms[].name (string)

  • dependencies[].system_vms[].public_ip (string)

  • dependencies[].system_vms[].state (string) – State is the hypervisor VM state; AgentState is the CloudStack agentstate (control-plane reachability). A system VM is healthy only when BOTH are positive — see common.SystemVMHealthy (the single health authority).

  • dependencies[].system_vms[].zone_name (string)

  • health_percentage (number)

  • healthy_checks (integer)

  • overall_status (string)

  • timestamp (string)

  • total_checks (integer)

  • unhealthy_checks (integer)

GET /health/agents/error-trends

Get agent node error trends

Retrieve time-series error metrics for agent nodes from InfluxDB

Query Parameters:

  • node (string) – Agent node hostname

  • dependency (string) – Specific dependency name

  • granularity (string) – Time granularity: hour, day, week, month

  • from (string) – Start time (RFC3339 format)

  • to (string) – End time (RFC3339 format)

Status Codes:
Response JSON Object:

  • data_points[] (object)

  • dependency (string)

  • from (string)

  • granularity (string)

  • node (string)

  • to (string)

GET /health/agents/latency-trends

Get agent node latency trends

Retrieve time-series latency metrics for agent nodes from InfluxDB

Query Parameters:

  • node (string) – Agent node hostname

  • dependency (string) – Specific dependency name

  • granularity (string) – Time granularity: hour, day, week, month

  • from (string) – Start time (RFC3339 format)

  • to (string) – End time (RFC3339 format)

Status Codes:
Response JSON Object:

  • data_points[] (object)

  • dependency (string)

  • from (string)

  • granularity (string)

  • node (string)

  • to (string)