Cluster, nodes, VMs, containers and storages from two cluster-wide API calls: the number of calls does not grow with the number of guests.
Up and running in 4 steps
- Install cv4pve-metrics-exporter
- Create an API token
- Run
cv4pve-metrics-exporter run - Scrape the metrics
Every Proxmox VE metric in Prometheus
Runs outside the nodes, API only. One endpoint for the whole cluster with nodes, VMs, containers and storage, plus what the built-in metrics leave out (HA, replication, guests without a backup, locks, subscription and SMART), ready for history, graphs and alerts.
By sysadmins, for sysadmins.
Built by Corsinvest, official Proxmox partner.
arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/;s/armv7l/arm/')wget https://github.com/Corsinvest/cv4pve-metrics-exporter/releases/latest/download/cv4pve-metrics-exporter-linux-$arch.zipunzip cv4pve-metrics-exporter-linux-$arch.zipchmod +x cv4pve-metrics-exporter./cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullcurl -s https://api.github.com/repos/Corsinvest/cv4pve-metrics-exporter/releases/latest | grep -o "https://[^\"]*-$(dpkg --print-architecture)\.deb" | xargs curl -LOsudo dpkg -i cv4pve-metrics-exporter-*-$(dpkg --print-architecture).debcv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullcurl -s https://api.github.com/repos/Corsinvest/cv4pve-metrics-exporter/releases/latest | grep -o "https://[^\"]*-$(rpm --eval %_target_cpu)\.rpm" | xargs curl -LOsudo rpm -i cv4pve-metrics-exporter-*-$(rpm --eval %_target_cpu).rpmcv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullyay -S cv4pve-metrics-exportercv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullbrew install corsinvest/tap/cv4pve-metrics-exportercv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullcurl -s https://api.github.com/repos/Corsinvest/cv4pve-metrics-exporter/releases/latest | grep -o "https://[^\"]*-$(uname -m)\.pkg" | xargs curl -LOsudo installer -target / -pkg cv4pve-metrics-exporter-*-$(uname -m).pkgcv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullarch=$(uname -m | sed 's/x86_64/x64/')curl -LO https://github.com/Corsinvest/cv4pve-metrics-exporter/releases/latest/download/cv4pve-metrics-exporter-osx-$arch.zipunzip cv4pve-metrics-exporter-osx-$arch.zipchmod +x cv4pve-metrics-exporter./cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullwinget install Corsinvest.cv4pve.metrics-exportercv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --full$arch = @{ AMD64 = 'x64'; x86 = 'x86'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]Invoke-WebRequest https://github.com/Corsinvest/cv4pve-metrics-exporter/releases/latest/download/cv4pve-metrics-exporter.exe-win-$arch.zip -OutFile cv4pve-metrics-exporter.zipExpand-Archive cv4pve-metrics-exporter.zip -DestinationPath . -Force.\cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=…' run --fullcurl -s http://localhost:9221/metrics/ | grep -v '^#'A few lines of the answer, from a two-node cluster:
cv4pve_up{id="node/pve01",type="node"} 1cv4pve_cluster_quorate{name="pve-cluster"} 1cv4pve_node_info{id="node/pve01",name="pve01",ip="10.0.0.11",level="Community"} 1cv4pve_node_version_info{node="pve01",version="8.4.21",release="8.4",repoid="2606ac850d46da29"} 1cv4pve_node_memory_total_bytes{node="pve01"} 270057619456cv4pve_node_memory_assigned_bytes{node="pve01"} 76235669504cv4pve_guest_info{id="qemu/1006",vmid="1006",node="pve01",name="dc01",type="qemu",tags="domain-controller;prod",template="0"} 1cv4pve_guest_cpu_usage_ratio{id="qemu/1006"} 0.0308618328609814cv4pve_guest_memory_usage_bytes{id="qemu/1006"} 5608828928cv4pve_guest_lock{id="qemu/1006",state="backup"} 0cv4pve_storage_size_bytes{id="storage/pve01/datapool"} 5442126217216cv4pve_storage_usage_bytes{id="storage/pve01/datapool"} 1092213195072cv4pve_replication_last_sync_timestamp_seconds{id="1006-0",type="local",source="pve01",target="pve02",guest="1006"} 1790683214cv4pve_guests_not_backed_up 6cv4pve_not_backed_up_info{id="qemu/203"} 1cv4pve_ha_quorate 1cv4pve_node_disk_health{node="pve01",serial="S3Z9NX0M412345",type="ssd",dev_path="/dev/sde"} 1cv4pve_node_disk_wearout{node="pve01",serial="S3Z9NX0M412345",type="ssd",dev_path="/dev/sde"} 98cv4pve_node_subscription_next_due_timestamp_seconds{node="pve01"} 1807747200cv4pve_scrape_duration_seconds 0.2013666Every metric, label and unit is in Metrics.
Proxmox VE shows the state of the cluster in its web interface and can send node, guest and storage
usage to an external metric server. What it does not give you is the rest of what keeps a cluster
healthy: whether the HA manager has quorum and every resource is started, whether replication still
syncs, which VMs no backup job includes, which guest has been locked since last night’s backup, when the
subscription expires, which SSD is wearing out.
cv4pve-metrics-exporter reads all of it through the API and publishes it in the Prometheus format. Prometheus keeps the history (how a storage fills up, how memory is assigned over the months) and turns the metrics into alerts that reach you before a user does.
Outside the nodes, API only
Section titled “Outside the nodes, API only”The exporter runs outside the cluster (on the Prometheus server, a management VM or any machine that
reaches a node on port 8006) and talks only to the Proxmox VE REST API. Nothing is installed on the
nodes and no SSH is needed: a read-only API token with the PVEAuditor role is enough, see
Permissions. Any node gives the view of the whole cluster; give
it more than one and each scrape uses the first one that answers, so the metrics keep coming while a
node is down.
Where it fits
Section titled “Where it fits”The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. cv4pve-metrics-exporter watches the cluster over time; cv4pve-report takes a full inventory of it, and cv4pve-diag finds what is configured wrong.
| cv4pve-metrics-exporter | cv4pve-report | cv4pve-diag | |
|---|---|---|---|
| Question | How is it doing, now and over time? | What do I have? | What is wrong? |
| Runs | Permanently, scraped by Prometheus | On demand or scheduled | On demand or scheduled |
| Result | Time series and alerts | Excel, HTML or JSON inventory | A list of problems with severity |
| Access | Proxmox VE API only, from outside the nodes | Proxmox VE API only, from outside the nodes | Proxmox VE API only, from outside the nodes |
Want the endpoint without running a separate service? cv4pve-admin runs the same engine in its Metrics Exporter module, with a scrape endpoint per cluster.
What it does for you
Section titled “What it does for you”HA state of resources and nodes, replication, guests no backup job includes, guest locks, subscription expiry, SMART health and SSD wearout.
vCPUs and memory assigned to the running guests of each node, next to what the node has.
No node reachable or login failed: HTTP 503, so Prometheus marks the target down. A single failed call is counted, and the other metrics are still exported.
Three profiles, a cache per collector for slow data such as SMART and subscription, and a limit on parallel calls.
systemd with Type=notify on Linux, a native Windows service: no wrapper, no agent on the nodes.
Part of the cv4pve suite →
Made by Corsinvest,
official Proxmox partner
See your cluster in Prometheus
Download the binary, point it at any node, add one scrape job.
Made by Corsinvest,official Proxmox partner
