pve-exporter/docs/metrics.md

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: 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:

pve_node_zfs_state != 1

(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.