Getting started

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.

Installation

Platform	How
Linux	wget https://github.com/Corsinvest/cv4pve-metrics-exporter/releases/latest/download/cv4pve-metrics-exporter-linux-x64.zip && unzip cv4pve-metrics-exporter-linux-x64.zip && chmod +x cv4pve-metrics-exporter ARM: cv4pve-metrics-exporter-linux-arm64.zip, cv4pve-metrics-exporter-linux-arm.zip
Debian / Ubuntu	sudo dpkg -i cv4pve-metrics-exporter-VERSION-ARCH.deb (amd64, arm64, armhf)
RHEL / Fedora	sudo rpm -i cv4pve-metrics-exporter-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl)
Arch Linux	yay -S cv4pve-metrics-exporter
Windows (WinGet)	winget install Corsinvest.cv4pve.metrics-exporter
Windows (manual)	cv4pve-metrics-exporter.exe-win-x64.zip, also x86 and arm64
macOS (Homebrew)	brew install corsinvest/tap/cv4pve-metrics-exporter
macOS (installer)	cv4pve-metrics-exporter-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel)
macOS (manual)	cv4pve-metrics-exporter-osx-arm64.zip or cv4pve-metrics-exporter-osx-x64.zip

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

First run

Create a dedicated user and API token first, see Permissions. Then point the tool at any node:

cv4pve-metrics-exporter --host=pve1.local --api-token='metrics@pve!metrics=<uuid>' run

Several nodes, username and password, certificates and options in a file for the service: see Connection.

Run

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=pve1 --api-token='metrics@pve!metrics=<uuid>' run          # standard profile
cv4pve-metrics-exporter --host=pve1 --api-token='metrics@pve!metrics=<uuid>' run --fast   # large clusters
cv4pve-metrics-exporter --host=pve1 --api-token='metrics@pve!metrics=<uuid>' run --full   # SMART and balloon too

# Your own selection of collectors, or a different address and port
cv4pve-metrics-exporter create-settings --full        # then edit settings.json
cv4pve-metrics-exporter --host=pve1 --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 VE
Prometheus: http://localhost:9221/metrics/
Press Ctrl+C to stop.

First scrape

By default the endpoint listens only on localhost, port 9221. 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 gauge
cv4pve_up{id="cluster/pve-cluster",type="cluster"} 1
cv4pve_up{id="node/pve01",type="node"} 1
cv4pve_up{id="qemu/1000",type="qemu"} 1
cv4pve_up{id="storage/pve01/local-zfs",type="storage"} 1

Use the host name that is in the settings (localhost by default): a request to 127.0.0.1 gets an error instead of the metrics. To let a Prometheus server on another machine scrape it, change Host, see Listening address.

Next

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