# Machine metrics

> CPU, memory, disk, disk I/O, and network use for each machine, with one-minute history, live samples, and disk warnings.

Every machine's host samples it every 5 seconds. VMYard keeps the latest values and one-minute history for the last 24 hours. Every member of the organization can read them, and so can every API key preset.

## What is measured

| Value | Meaning |
| --- | --- |
| CPU | Millicores used over the host's last sampling interval (1000 = one core), as a share of the machine's CPU limit. |
| Memory | Memory charged to the machine (RAM in use, page cache, and the virtual machine monitor), as a share of its limit. |
| Disk | Blocks the machine's disk image holds, as a share of its size. It is an upper bound: blocks the machine freed stay allocated. |
| Disk I/O | Bytes per second read from and written to the disk. |
| Network | Bytes per second received (`rx`) and sent (`tx`) by the machine. |

A value the host didn't measure is absent, never zero: CPU and memory while the machine is asleep, and Docker machines on macOS. Metrics describe resource use only. They are not used for billing.

## In the console

The machine list has a **CPU / RAM / Disk / IO** column with a bar and a number for each value. Hover or focus it for the used amount, the limit, and the I/O and network rates. On a phone the same values appear in each machine's card. A machine that hasn't been sampled yet shows "—".

The machine's **Overview** has a **Metrics** section with charts for CPU, memory, disk, disk I/O, and network over the last hour, 6 hours, or 24 hours. Hover or focus a chart (then use the arrow keys) to read the values at one minute; the table under the charts gives the latest, average, and peak of each value.

**Live** follows the host's own samples, about 5 seconds apart, for as long as it stays on. Live needs a running or sleeping machine. When it isn't available the console says why and goes back to one-minute history.

### Stale values

When VMYard couldn't read a machine recently, its values are kept and marked **Stale** with the reason. They are the last values known, not zero.

| Reason | Meaning |
| --- | --- |
| Host unreachable | The machine's host couldn't be read. |
| Not reported | The host no longer reports this machine, for example after it stopped. |
| Poll overdue | No reading confirmed the values in the last three polling intervals. |

## Disk warnings

| Flag | Meaning |
| --- | --- |
| `disk_almost_full` | At least 90% of the machine's disk is used. |
| `disk_full` | At least 98% is used. Writes in the machine may fail. |
| `host_disk_low` | The host the machine runs on is low on disk. This is not your machine's disk; nothing for you to clean up. |

The disk flags come from the machine's own filesystem report while it is fresh, otherwise from the disk image, so treat them as advisory: VMYard enforces nothing on them. To free space, find large directories from the terminal (`du -sh /work/* | sort -h`), then delete what you don't need, or read files you want to keep from the [Files](/docs/guides/files) tab first. Owners, admins, and operators also get the `disk_almost_full` and `disk_full` [email alerts](/docs/guides/email-alerts) by default, at most once an hour per machine.

## Guest-reported values

The response may include `guest_reported`: memory and filesystem totals that the machine's own agent reports. Code inside the machine can change them, so the console shows them in a separate, labelled block. They never reach the history, billing, or enforcement.

## Read metrics with the API

The latest values come with every machine as `metrics`, or `null` until it is first sampled:

```json
"metrics": {
  "sampled_at": "2026-10-12T11:59:30Z",
  "stale": false,
  "stale_reason": null,
  "state": "running",
  "cpu_percent": 37.5,
  "cpu_millis": 1500,
  "cpu_limit_millis": 4000,
  "memory_percent": 62.0,
  "memory_bytes": 5325918208,
  "memory_limit_bytes": 8589934592,
  "disk_percent": 91.2,
  "disk_used_bytes": 78383153152,
  "disk_size_bytes": 85899345920,
  "io_read_bps": 1250000,
  "io_write_bps": 420000,
  "net_rx_bps": 96000,
  "net_tx_bps": 18000,
  "flags": ["disk_almost_full"]
}
```

History is one request per machine:

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/metrics?resolution=1m&since=2026-10-12T11:00:00Z" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

- `resolution=1m` (the default) returns stored minutes, oldest first, from `since` (default: the last 24 hours). Each point averages the minute, with `cpu_millis_max` and `memory_bytes_max` for its peak. A response holds at most 1440 points; when `next_since` is set, ask again with it as `since`.
- `resolution=live` returns the host's retained samples (about 5 seconds apart, for about 15 minutes) newer than `since`. Poll with the last point's `t` as `since`. A machine that isn't running or sleeping answers `409 machine_not_running`; an unreachable host `503 runtime_unavailable`; a server without a runtime `503 metrics_unavailable`. On any of these, read `1m` instead.

Rates are bytes per second. The console shows them in decimal units (1 kB/s = 1,000 B/s) and sizes in binary units (1 GiB = 1,073,741,824 bytes).