# Metrics Reference

All exporter-specific metric names start with `pve_`. The Go Prometheus client
also exposes its standard `go_*`, `process_*`, and HTTP handler metrics.

Metric names follow the [Prometheus naming conventions](https://prometheus.io/docs/practices/naming/):
base units only (seconds, bytes, ratios) and a `_total` suffix on every metric
exported as a counter. Counters hold the absolute value reported by the PVE API
and reset when the guest or node restarts, so query them with `rate()` or
`increase()`. All remaining metrics are gauges.

## Common labels and lifecycle

Most resource metrics use these labels:

| Label | Description |
| --- | --- |
| `cluster` | PVE cluster name. A standalone installation uses `Standalone node - <node>`. |
| `node` | Proxmox node name. |
| `vmid` | QEMU VM or LXC container ID. |
| `name` | Guest name. |

Metric label sets are retained for five minutes after their last update and are
then removed. Consequently, metrics available only while a guest is running can
remain visible for up to five minutes after it stops.

## Exporter

| Metric | Labels | Description |
| --- | --- | --- |
| `pve_metrics_collection_duration_seconds` | `collector` | Summary of successful collector execution time in seconds. |

## Cluster state

Enabled with `metrics.clusterState`. Labels: `cluster`.

| Metric | Description |
| --- | --- |
| `pve_cluster_mode` | `1` when PVE is configured as a cluster, `0` for a standalone node. A configured one-node cluster still reports `1`. |
| `pve_cluster_nodes` | Number of nodes reported by the cluster status record. Standalone mode reports `0`. |
| `pve_cluster_quorate` | Cluster quorum state: `1` quorate, `0` not quorate or standalone. |

## Node status

Enabled with `metrics.nodeStatus`. Unless noted otherwise, labels are `cluster`
and `node`.

| Metric | Description |
| --- | --- |
| `pve_node_state` | Node online state: `1` online, `0` offline. |
| `pve_node_uptime_seconds` | Node uptime in seconds. |
| `pve_node_cpus` | Number of logical CPUs. |
| `pve_node_cpu_usage_ratio` | CPU usage reported by PVE as a ratio between `0` and `1`. |
| `pve_node_memory_total_bytes` | Total memory in bytes. |
| `pve_node_memory_used_bytes` | Used memory in bytes. |
| `pve_node_memory_free_bytes` | Free memory in bytes. |
| `pve_node_ksm_bytes` | Memory shared by Kernel Same-page Merging in bytes. |
| `pve_node_cgroup_mode` | PVE cgroup mode. |
| `pve_node_load1` | One-minute load average. |
| `pve_node_load5` | Five-minute load average. |
| `pve_node_load15` | Fifteen-minute load average. |
| `pve_node_rootfs_free_bytes` | Root filesystem free bytes. |
| `pve_node_rootfs_used_bytes` | Root filesystem used bytes. |
| `pve_node_rootfs_total_bytes` | Root filesystem total bytes. |
| `pve_node_rootfs_avail_bytes` | Root filesystem bytes available to unprivileged processes. |
| `pve_node_time_seconds` | Node UTC Unix timestamp. |
| `pve_node_localtime_seconds` | Node local Unix timestamp. |
| `pve_node_cpu_info` | Constant `1` carrying `flags`, `cores`, `model`, `sockets`, `cpus`, and `hvm` labels. |
| `pve_node_system_info` | Constant `1` carrying `kversion`, `pveversion`, `machine`, `sysname`, and `release` labels. |

## Physical disks

Enabled with `metrics.disk`. Labels are `cluster`, `node`, `wwn`, `type`,
`model`, `serial`, `vendor`, `used`, and `osd_id`.

| Metric | Description |
| --- | --- |
| `pve_node_disk_healthy` | SMART health state: `1` for `OK` or `PASSED`, otherwise `0`. |
| `pve_node_disk_wearout_percent` | Device wearout percentage when supplied by the PVE API. |
| `pve_node_disk_size_bytes` | Physical disk size in bytes. |

## ZFS

Enabled with `metrics.zfs`. The exporter discovers all pools on every node,
retrieves each pool detail, and recursively flattens pool, vdev, section, cache,
and leaf-device entries.

Labels are `cluster`, `node`, `pool`, `component`, `path`, and `leaf`.
`component` is the current topology entry, `path` identifies its complete
hierarchy, and `leaf` is `true` for a device entry.

| Metric | Description |
| --- | --- |
| `pve_node_zfs_state` | Numeric component state: `0=UNKNOWN`, `1=ONLINE`, `2=DEGRADED`, `3=FAULTED`, `4=OFFLINE`, `5=REMOVED`, `6=UNAVAIL`. |
| `pve_node_zfs_read_errors_total` | ZFS read error count reported for the component. |
| `pve_node_zfs_write_errors_total` | ZFS write error count reported for the component. |
| `pve_node_zfs_checksum_errors_total` | ZFS checksum error count reported for the component. |

ZFS section entries that do not contain a counter do not produce a false zero
series. A counter explicitly returned as zero is exported normally.

Example alert expressions:

```promql
pve_node_zfs_state != 1
```

```promql
(pve_node_zfs_read_errors_total > 0)
or (pve_node_zfs_write_errors_total > 0)
or (pve_node_zfs_checksum_errors_total > 0)
```

## PVE storage

Enabled with `metrics.storage`. Disabled storages are skipped. Labels are
`cluster`, `node`, `storage`, `type`, `content`, and `shared`.

| Metric | Description |
| --- | --- |
| `pve_storage_up` | Storage active state: `1` active, `0` inactive. |
| `pve_storage_total_bytes` | Total storage capacity in bytes. |
| `pve_storage_avail_bytes` | Available storage capacity in bytes. |
| `pve_storage_used_bytes` | Used storage capacity in bytes. |

## Node subscriptions

Enabled with `metrics.subscription`. The common labels are `cluster` and
`node`; `pve_node_subscription_info` also has `productname` and `serverid`.

| Metric | Description |
| --- | --- |
| `pve_node_subscription_info` | Constant `1` carrying subscription product and server identifiers. |
| `pve_node_subscription_status` | `0` for API status `notfound`, `1` for `active`, `2` for expired or otherwise unusable states such as `invalid`, `suspended`, and `new`. |
| `pve_node_subscription_registration_timestamp_seconds` | Subscription registration date as a Unix timestamp, when available. |
| `pve_node_subscription_next_due_timestamp_seconds` | Next due date as a Unix timestamp, when available. |
| `pve_node_subscription_sockets` | Number of covered sockets reported by PVE. |

The PVE API cannot distinguish a node that never had a subscription from one
whose key was removed; both appear as `notfound` and therefore use value `0`.

## SDN

Enabled with `metrics.sdn`. Labels are `cluster`, `node`, `sdn`, and `sdn_id`.

| Metric | Description |
| --- | --- |
| `pve_sdn_state` | `1` when the SDN resource status is `ok`, otherwise `0`. |

PVE 8 reports SDN zones as `sdn` cluster resources, PVE 9 reports them as
`network` resources (zones and fabrics). Both are exported as `pve_sdn_state`;
the `sdn` label holds the zone or fabric name and `sdn_id` the resource ID,
which differs between the two formats (`sdn/<node>/<zone>` versus
`network/<node>/<network-type>/<name>`).

## LXC containers

Enabled with `metrics.lxc`. Templates are skipped. Labels are `cluster`,
`node`, `vmid`, and `name`.

| Metric | Description |
| --- | --- |
| `pve_ct_state` | `1` running, `0` stopped. |
| `pve_ct_uptime_seconds` | Uptime in seconds; updated only while running. |
| `pve_ct_cpus` | Configured CPU count. |
| `pve_ct_cpu_usage_ratio` | CPU usage reported by PVE as a ratio between `0` and `1`; updated only while running. |
| `pve_ct_memory_total_bytes` | Configured memory limit in bytes. |
| `pve_ct_memory_used_bytes` | Used memory in bytes; updated only while running. |
| `pve_ct_network_receive_bytes_total` | Received bytes since container start; updated only while running. |
| `pve_ct_network_transmit_bytes_total` | Transmitted bytes since container start; updated only while running. |
| `pve_ct_disk_read_bytes_total` | Disk bytes read; updated only while running. |
| `pve_ct_disk_write_bytes_total` | Disk bytes written; updated only while running. |
| `pve_ct_disk_used_bytes` | Used root disk bytes; updated only while running. |
| `pve_ct_disk_size_bytes` | Configured root disk size in bytes. |
| `pve_ct_swap_used_bytes` | Used swap in bytes; updated only while running. |

## QEMU virtual machines

Enabled with `metrics.qemu`. Templates are skipped. Base labels are `cluster`,
`node`, `vmid`, and `name`.

| Metric | Extra label | Description |
| --- | --- | --- |
| `pve_vm_state` | none | `1` running, `0` stopped. |
| `pve_vm_uptime_seconds` | none | Uptime in seconds; updated only while running. |
| `pve_vm_agent` | none | QEMU guest agent state reported by PVE; updated only while running. |
| `pve_vm_cpus` | none | Configured CPU count. |
| `pve_vm_cpu_usage_ratio` | none | CPU usage reported by PVE as a ratio between `0` and `1`; updated only while running. |
| `pve_vm_memory_total_bytes` | none | Configured maximum memory in bytes. |
| `pve_vm_memory_used_bytes` | none | Used memory in bytes; updated only while running. |
| `pve_vm_disk_used_bytes` | none | Root disk usage reported by PVE. |
| `pve_vm_disk_size_bytes` | none | Configured maximum root disk size in bytes. |
| `pve_vm_network_receive_bytes_total` | `interface` | Bytes received by a virtual interface. |
| `pve_vm_network_transmit_bytes_total` | `interface` | Bytes transmitted by a virtual interface. |
| `pve_vm_disk_read_operations_total` | `device` | Successful read operations. |
| `pve_vm_disk_write_operations_total` | `device` | Successful write operations. |
| `pve_vm_disk_read_bytes_total` | `device` | Bytes read from the block device. |
| `pve_vm_disk_write_bytes_total` | `device` | Bytes written to the block device. |
| `pve_vm_disk_failed_read_operations_total` | `device` | Failed read operations. |
| `pve_vm_disk_failed_write_operations_total` | `device` | Failed write operations. |
| `pve_vm_disk_read_time_seconds_total` | `device` | Total block-device read time in seconds. |
| `pve_vm_disk_write_time_seconds_total` | `device` | Total block-device write time in seconds. |

Interface and block-device metrics are collected only for running VMs.