pve-exporter/docs/configuration.md

Configuration Reference

The exporter reads config.yaml from the current working directory by default. Use -config to select a different file:

./pve-exporter -config /etc/pve-exporter/config.yaml

Complete example

host: 0.0.0.0
port: 9090
logLevel: 4

proxmox:
  token:
    tokenId: monitoring@pve!exporter
    secret: change-me

  hosts:
    - https://192.168.0.10:8006
    - https://pve02.example.com:8006/

  interval: 15

  metrics:
    clusterState: true
    nodeStatus: true
    qemu: true
    lxc: true
    disk: true
    zfs: true
    storage: true
    subscription: true
    sdn: true

Server settings

Setting	Type	Description
host	IP address	Address on which the exporter HTTP server listens, for example 0.0.0.0 or 127.0.0.1. DNS names are not accepted here.
port	integer	Exporter HTTP port. Prometheus metrics are served at /metrics.
logLevel	integer	Logrus level: 0=Panic, 1=Fatal, 2=Error, 3=Warn, 4=Info, 5=Debug, 6=Trace.

Proxmox token

Setting	Type	Description
proxmox.token.tokenId	string	Full Proxmox API token ID, normally user@realm!token-name.
proxmox.token.secret	string	API token secret. Treat the configuration file as sensitive.

Create a dedicated monitoring user and token, then assign the read-only PVEAuditor role to both the user and the token. The role supplies the audit permissions used by cluster, node, storage, disk, ZFS, guest, and subscription API calls.

API hosts and failover

proxmox.hosts is a non-empty list of Proxmox API base URLs. Both IP addresses and DNS names are supported:

proxmox:
  hosts:
    - https://192.168.0.10:8006
    - https://pve02.example.com:8006/

A trailing slash is optional and normalized automatically. Every host must use http or https and must belong to the same PVE cluster. The exporter checks endpoint liveness every five seconds and distributes API requests across the currently reachable endpoints.

Do not combine unrelated clusters in one list. Their API responses share the same short-lived client cache and Prometheus registry. Run a separate exporter for each cluster.

Collection interval

proxmox.interval is the positive number of seconds between collection cycles. The first cycle runs during application startup. Prometheus scrapes only the values already present in the registry, so its scrape interval does not control the PVE API request rate.

Collector switches

All switches are booleans. Omitted switches default to false.

Setting	Collector	Main metric prefix
clusterState	Cluster mode, node count, and quorum	pve_cluster_
nodeStatus	Node health and resource usage	pve_node_
qemu	QEMU virtual machines	pve_vm_
lxc	LXC containers	pve_ct_
disk	Physical disk health and metadata	pve_node_disk_
zfs	ZFS pool topology, state, and errors	pve_node_zfs_
storage	Enabled PVE storage status and capacity	pve_storage_
subscription	Node subscription information	pve_node_subscription_
sdn	Software-defined network state	pve_sdn_

The exporter-level pve_metrics_collection_duration_seconds summary is always registered.

Validation notes

• host must be a literal IP address.
• At least one Proxmox API host is required.
• API host URLs require an http or https scheme and an IP or DNS hostname.
• Token ID and secret cannot be empty.
• Keep proxmox.interval greater than zero and logLevel between 0 and 6.