Skip to content

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.

  1. 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.zip
    unzip cv4pve-metrics-exporter-linux-$arch.zip
    chmod +x cv4pve-metrics-exporter

    All files are on the latest release page.

  2. Create an API token

    Create a dedicated user and an API token in Proxmox VE, with the privileges the tool needs: see Permissions.

  3. Run cv4pve-metrics-exporter run

    Point the tool at any node:

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

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

  4. Scrape the metrics

    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.

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 profile
cv4pve-metrics-exporter --host=pve01 --api-token='metrics@pve!metrics=<uuid>' run --fast # large clusters
cv4pve-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 port
cv4pve-metrics-exporter create-settings --full # then edit settings.json
cv4pve-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 VE
Prometheus: 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.