Install the Prometheus exporter for Proxmox VE
cv4pve-metrics-exporter runs outside the cluster (on the Prometheus server, a management VM or any machine that can reach a node on port 8006) and talks only to the Proxmox VE REST API. Nothing is installed on the nodes.
First run
Section titled “First run”Install cv4pve-metrics-exporter
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-exportercurl -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).debcurl -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).rpmyay -S cv4pve-metrics-exporterbrew install corsinvest/tap/cv4pve-metrics-exportercurl -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).pkgarch=$(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-exporterwinget install Corsinvest.cv4pve.metrics-exporter$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 . -ForceAll files are on the latest release page.
Create an API token
Create a dedicated user and an API token in Proxmox VE, with the privileges the tool needs: see Permissions.
Run
cv4pve-metrics-exporter runPoint the tool at any node:
cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' runSeveral nodes, username and password, certificates and options in a file for the service: see Connection.
Scrape the metrics
By default the endpoint listens only on
localhost, port9221. From the same machine:curl http://localhost:9221/metrics/The answer is the Prometheus text format, one line per value:
# HELP cv4pve_up Resource is online/running/available (1) or not (0)# TYPE cv4pve_up gaugecv4pve_up{id="cluster/pve-cluster",type="cluster"} 1cv4pve_up{id="node/pve01",type="node"} 1cv4pve_up{id="qemu/1000",type="qemu"} 1cv4pve_up{id="storage/pve01/local-zfs",type="storage"} 1Use the host name that is in the settings (
localhostby default): a request to127.0.0.1gets an error instead of the metrics. To let a Prometheus server on another machine scrape it, changeHost, see Listening address.
cv4pve-metrics-exporter has two commands:
| Command | What it does |
|---|---|
run |
Starts the HTTP endpoint and stays in the foreground until it is stopped (Ctrl+C, systemctl stop, the Windows service manager). Each request to the endpoint reads the cluster and answers with the metrics, see Prometheus. |
create-settings |
Writes settings.json with the standard settings (or those of --fast / --full), to edit and pass with --settings-file, see Settings. Needs no connection to the cluster. |
Options of run:
| Option | What it does |
|---|---|
--fast |
Fast profile: only the cluster-wide calls, no per-node calls. For large clusters or short scrape intervals. |
--full |
Full profile: adds SMART disk health and QEMU balloon memory, and caches HA and replication. |
Without --fast or --full the standard profile is used. The profiles
table lists exactly what each one turns on.
cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' run # standard profilecv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' run --fast # large clusterscv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' run --full # SMART and balloon too
# Your own selection of collectors, or a different address and portcv4pve-metrics-exporter create-settings --full # then edit settings.jsoncv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' --settings-file=settings.json run--fast and --full go after run. --settings-file goes before the command, with the
connection options: after run it is rejected as an unknown argument. A settings file always wins over
--fast and --full.
At start the exporter prints the address it listens on:
Corsinvest for Proxmox VEPrometheus: http://localhost:9221/metrics/Press Ctrl+C to stop.- Prometheus: the scrape configuration and how each scrape reads the cluster.
- Run as a service: systemd on Linux, a service on Windows.
- Metrics: every metric, its labels and the setting that turns it on.