---
title: "Fleet health and metric dashboards"
slug: "monitoring-fleet-health"
source: "https://app.cloudpe.com/help/monitoring-fleet-health"
updated: "2026-08-30T19:03:44.335Z"
---

# Fleet health and metric dashboards

## Overview

**Monitoring** is the fleet-wide view of the health of your virtual machines. The **Fleet Health** tab shows every VM that has the CloudPe monitoring agent installed, with its agent state and its most recent CPU, memory and disk readings, so you can spot a struggling or silent instance without opening each VM in turn. The **Active Alerts** tab lists the alert instances that are currently pending or firing across the same fleet.

Metrics come from the agent running inside each VM. The agent streams samples to the regional metrics collector for the VM's region, and the console queries that region when you open a chart. A VM with no agent installed appears in the console but reports no metrics.

Monitoring is a beta feature. Behaviour and layout can change between releases.

## Before you start

- Select the project whose VMs you want to inspect. Fleet Health is scoped to the organization and project you are working in.
- Install the monitoring agent on the VMs you want to see. See [Install the monitoring agent on a VM](/help/vm-monitoring-agent-install).
- You need the `vms:read` permission to read VM metrics and agent status.
- Monitoring carries a beta label in the sidebar; it appears under **PLATFORM** as **Monitoring**.

## Steps

1. In the sidebar, open **Monitoring** under **PLATFORM**.
2. Stay on the **Fleet Health** tab. Each VM is listed with its agent state and its latest reported CPU, memory and disk usage.

   ![](/kb/monitoring/monitoring-fleet-health-01-fleet-grid.png)

3. Check the agent state before reading the numbers. An agent that has stopped heartbeating is marked disconnected, and a disconnected agent's readings are stale by definition.
4. Select a VM to open its detail view and its time-series charts. Use the period selector to move between short raw windows and longer downsampled windows.
5. Switch to the **Active Alerts** tab to see which rules are currently pending or firing, on which VM, and at what severity.

   ![](/kb/monitoring/monitoring-fleet-health-02-active-alerts.png)

6. To change what fires, use **Alert Rules**, **Channels** and **Silences** on the same page — **Create Rule**, **Add Channel** and **Create Silence** are described in [Alert rules and notifications](/help/alert-rules-notifications).

## API

The console reads the same public endpoints you can call directly.

Latest snapshot for one VM:

```bash
curl -H "Authorization: Bearer <API_KEY>" \
  "https://app.cloudpe.com/api/v1/vms/<vm_id>/metrics/latest"
```

Time-series for one VM (the `period` query parameter selects the window):

```bash
curl -H "Authorization: Bearer <API_KEY>" \
  "https://app.cloudpe.com/api/v1/vms/<vm_id>/metrics?period=1h"
```

Currently pending and firing alert instances for the organization:

```bash
curl -H "Authorization: Bearer <API_KEY>" \
  "https://app.cloudpe.com/api/v1/alerts"
```

Every metrics response returns HTTP 200 and carries a `status` field that tells you why `data` may be empty: `ok` (rows returned), `no_data` (the query ran and the VM genuinely has nothing in that window), or `monitoring_unavailable` (the query could not run, so nothing can be concluded about the VM). When the status is `monitoring_unavailable`, a `reason` field distinguishes `region_not_configured` from `query_failed`. Treat `monitoring_unavailable` as "unknown", never as "healthy".

## Limits

- Fleet Health only covers VMs with a registered agent. VMs without one show no metrics and take no part in alert evaluation.
- Metric storage is tiered: raw samples are kept for a short window, five-minute averages for a medium window, and hourly averages for the longest window. Older data is aged out, so long periods are answered from averages rather than raw samples.
- The downsampled tables carry no disk-I/O, network-throughput or uptime columns. On the longest periods those series render as gaps and tooltips read `N/A` rather than a misleading flat line.
- Alert rules and scaling policies can only use the metrics the evaluator can resolve: CPU usage, CPU iowait, memory usage and disk usage for VMs, plus GPU utilisation, GPU memory and GPU temperature. Disk and network counters are not usable as rule metrics.
- Treat the disk and network `*_bps` and `*_iops` values as lifetime counters, not current rates. On a long-running VM they climb steadily and do not represent throughput at that moment.

## FAQ

**A VM shows no data at all — is it down?**
Not necessarily. Check the `status` in the metrics response or the empty-state message in the console. `no_data` means the agent has genuinely reported nothing for that window, usually because the agent is not installed, the VM has just booted, or the window predates the agent. `monitoring_unavailable` means the query itself failed and says nothing about the VM.

**Why is an agent marked disconnected when the VM is clearly up?**
The health sweep marks an agent disconnected when it has stopped appearing in its region's heartbeat data. The sweep is scoped to regions whose metrics store answered, so an outage in one region no longer flips healthy agents elsewhere. If a VM is up but disconnected, reinstall or re-register the agent — see [Install the monitoring agent on a VM](/help/vm-monitoring-agent-install).

**Does a disconnected agent still send alerts for that VM?**
No. While the VM's agent is disconnected, its other rule notifications are suppressed, because there is no trustworthy data behind them. Alert state is still tracked, so recovery is detected correctly once the agent reconnects.

**An alert stayed firing after the VM stopped reporting. Is that a bug?**
No. When metric data disappears, an alert already in the firing state is deliberately left firing rather than cleared on an absence of evidence. Rules that were still building up to the firing threshold are released instead.

**Why are the charts empty only on the longer periods?**
Longer periods read from the downsampled tables. If the agent has been installed for less time than the window, or the series has no downsampled column, the chart shows gaps.

## Related

- [Install the monitoring agent on a VM](/help/vm-monitoring-agent-install)
- [Alert rules and notifications](/help/alert-rules-notifications)