wingetCollections
  • Auto
  • Search
  • Awesome Collections
  • Awesome Programs
  • My Favorite Collections
  • My Collections
  • Account / Settings
  • Terms of Service
  • Privacy
  • About

© 2026 winget.ragerworks.com

Loading...
Install cv4pve-metrics-exporter using Winget - wingetCollections
  1. Go back
  2. Packages
  3. cv4pve-metrics-exporter
cv4pve-metrics-exporter logo

cv4pve-metrics-exporter Corsinvest Srl

corsinvest exporter metrics monitoring prometheus proxmox proxmoxve virtualization
Use this command to install cv4pve-metrics-exporter:
winget install --id=Corsinvest.cv4pve.metrics-exporter -e

cv4pve-metrics-exporter is a Prometheus metrics exporter designed to provide comprehensive monitoring data for Proxmox VE virtualization infrastructure.

Key Features:

  • Exports detailed Prometheus metrics for monitoring and alerting.
  • Monitors node health, VM/container resource usage, storage capacity, replication status, and High Availability (HA) resources.
  • Offers customizable endpoints and supports API token authentication for secure access.

Audience & Benefit:
Ideal for Proxmox VE administrators seeking to enhance infrastructure monitoring. This tool enables proactive management of virtualized environments by providing actionable insights into resource utilization, system health, and HA configurations.

The software is available via winget for Windows users.

README

cv4pve-metrics-exporter

   ______                _                      __
  / ____/___  __________(_)___ _   _____  _____/ /_
 / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
/ /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
\____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

Metrics Exporter for Proxmox VE (Made in Italy)

License Release Downloads NuGet WinGet AUR

> Exports Proxmox VE cluster metrics to Prometheus — nodes, VMs, containers, storage, HA, replication, subscription, SMART.

Quick Start

wget https://github.com/Corsinvest/cv4pve-metrics-exporter/releases/download/VERSION/cv4pve-metrics-exporter-linux-x64.zip
unzip cv4pve-metrics-exporter-linux-x64.zip
./cv4pve-metrics-exporter --host=YOUR_HOST --username=root@pam --password=YOUR_PASSWORD run

With API token (recommended):

./cv4pve-metrics-exporter --host=YOUR_HOST --api-token=user@realm!token=uuid run

Scrape endpoint: http://localhost:9221/metrics/

Profiles

ProfileUse caseAPI calls per scrape
FastLarge clusters, lightweight scrapinglowest
StandardDaily monitoring, balancedmedium
Full
Versions
2.0.0
1.7.0
Website
github.com
License
Last updated
4/21/2026
Download latest version
Full observability, small/medium clusters
highest
cv4pve-metrics-exporter --host=YOUR_HOST --api-token=... run           # Standard (default)
cv4pve-metrics-exporter --host=YOUR_HOST --api-token=... run --fast    # Fast
cv4pve-metrics-exporter --host=YOUR_HOST --api-token=... run --full    # Full

Profiles comparison

SettingFastStandardFull
Cluster
HA state✓ (no cache)✓ (no cache)✓ (cache 30s)
BackupInfo✓ (no cache)✓ (cache 10m)✓ (cache 10m)
Node
Status (memory/swap/load/uptime + version)✓✓
Subscription✓ (cache 1h)✓ (cache 1h)
Replication✓ (no cache)✓ (cache 1m)
DiskSmart✓ (cache 10m)
Guest
Balloon (1 RPC per running QEMU)✓
Other
API instrumentation✓✓

> Fast profile skips all per-node calls — good for very large clusters where scrape latency matters more than per-node detail.

Features

  • Lock visibility — cv4pve_guest_lock{state} exploded series for clean alerting (backup, snapshot, migrate, …)
  • Subscription monitoring — info, exploded status and next due date
  • HA state — exploded series for both guests (cv4pve_ha_state) and nodes (cv4pve_ha_node_state), plus cv4pve_ha_quorate
  • Replication on every node — full cluster coverage
  • SMART disk health — wearout and health per disk (opt-in, cached)
  • Node version per node — cv4pve_node_version_info with version/release/repoid
  • Overcommit detection — cv4pve_node_cpu_assigned_cores and cv4pve_node_memory_assigned_bytes
  • Backup compliance — per-guest cv4pve_not_backed_up_info + cluster-wide cv4pve_guests_not_backed_up
  • API instrumentation — per-endpoint duration histogram and error counter, with normalized paths
  • Self-monitoring — cv4pve_scrape_duration_seconds + cv4pve_scrape_errors_total{section}
  • Per-collector cache TTL — slow-changing data (SMART, subscription) cached to minimize Proxmox API load
  • Native C# — single binary, cross-platform (Linux, Windows, macOS), no runtime dependencies
  • Native service support — systemd (Type=notify) and Windows Services (no wrapper required)
  • Profile-driven — Fast/Standard/Full profiles or full settings.json for fine-grained control

Installation

PlatformCommand
Linuxwget .../cv4pve-metrics-exporter-linux-x64.zip && unzip cv4pve-metrics-exporter-linux-x64.zip && chmod +x cv4pve-metrics-exporter
Windows WinGetwinget install Corsinvest.cv4pve.metrics-exporter
Windows manualDownload cv4pve-metrics-exporter-win-x64.zip from Releases
Arch Linuxyay -S cv4pve-metrics-exporter
Debian/Ubuntusudo dpkg -i cv4pve-metrics-exporter-VERSION-ARCH.deb
RHEL/Fedorasudo rpm -i cv4pve-metrics-exporter-VERSION-ARCH.rpm
macOS Homebrewbrew install corsinvest/tap/cv4pve-metrics-exporter
macOS manualwget .../cv4pve-metrics-exporter-osx-x64.zip && unzip cv4pve-metrics-exporter-osx-x64.zip && chmod +x cv4pve-metrics-exporter

All binaries on the Releases page.

Required Permissions

PermissionPurposeScope
VM.AuditRead VM/CT configuration and statusVirtual machines
Datastore.AuditRead storage metricsStorage systems
Sys.AuditNode status, disks, subscription, replicationCluster nodes

Create an API Token

# Create dedicated user (recommended)
pveum user add metrics@pve

# Grant read-only permissions
pveum aclmod / -user metrics@pve -role PVEAuditor

# Create token (save the secret — shown only once!)
pveum user token add metrics@pve metrics --privsep 0

Running as a Service

The binary is service-aware out of the box — it integrates natively with both systemd (Linux) and Windows SCM. Run it interactively during development, then promote the same binary to a managed service in production without any wrapper.

Linux (systemd)

Supports Type=notify — systemd is informed when the exporter is ready and gets proper graceful shutdown on systemctl stop.

# /etc/systemd/system/cv4pve-metrics-exporter.service
[Unit]
Description=Proxmox VE Metrics Exporter for Prometheus
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/cv4pve-metrics-exporter \
  --host=pve.local \
  --api-token=metrics@pve!metrics=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --settings-file=/etc/cv4pve/metrics-exporter.json \
  run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

# Create a dedicated unprivileged user (optional)
sudo useradd -r -s /bin/false prometheus

# Place the settings file somewhere the service user can read
sudo install -d /etc/cv4pve
sudo install -m 640 -o root -g prometheus settings.json /etc/cv4pve/metrics-exporter.json

sudo systemctl daemon-reload
sudo systemctl enable --now cv4pve-metrics-exporter
sudo systemctl status cv4pve-metrics-exporter
sudo journalctl -u cv4pve-metrics-exporter -f

> Note: always use absolute paths for --settings-file — systemd does not set a working directory by default.

Windows (native service)

The binary integrates with Windows SCM directly.

# Install as a Windows service
sc.exe create cv4pve-metrics-exporter `
  binPath= "C:\Tools\cv4pve-metrics-exporter\cv4pve-metrics-exporter.exe --host=pve.local --api-token=metrics@pve!metrics=xxx --settings-file=C:\ProgramData\cv4pve\metrics-exporter.json run" `
  start= auto `
  DisplayName= "Corsinvest Proxmox VE Metrics Exporter"

# Start / stop
sc.exe start cv4pve-metrics-exporter
sc.exe stop cv4pve-metrics-exporter

# View logs in Event Viewer → Windows Logs → Application

> Note on quoting: sc.exe is picky — the space after binPath= and around each = is required.

Docker

Run the binary in a minimal container — no special flags needed, SIGTERM is handled.

FROM mcr.microsoft.com/dotnet/runtime:10.0-alpine
COPY cv4pve-metrics-exporter /usr/local/bin/
EXPOSE 9221
ENTRYPOINT ["/usr/local/bin/cv4pve-metrics-exporter"]
CMD ["run"]

docker run -d --name pve-metrics \
  -p 9221:9221 \
  -v /etc/cv4pve:/config:ro \
  cv4pve-metrics-exporter \
  --host=pve.local \
  --api-token=metrics@pve!metrics=xxx \
  --settings-file=/config/metrics-exporter.json \
  run

Remember to bind to 0.0.0.0 (via Host in settings.json) when exposing outside the container.

Prometheus scrape config

scrape_configs:
  - job_name: proxmox
    static_configs:
      - targets: ['exporter-host:9221']

Settings Reference

Customize the exporter by creating and editing a settings.json file:

# Step 1 — generate a settings file (pick your starting profile)
cv4pve-metrics-exporter create-settings          # Standard (default)
cv4pve-metrics-exporter create-settings --fast   # Fast
cv4pve-metrics-exporter create-settings --full   # Full

# Step 2 — edit settings.json to your needs

# Step 3 — run with your custom settings
cv4pve-metrics-exporter --host=YOUR_HOST --api-token=... --settings-file=settings.json run

Each collector exposes two knobs:

  • Enabled — turn the collector on/off
  • CacheSeconds — TTL of the cached result (0 = always refresh)

Cache is the recommended way to keep slow-changing data (SMART, subscription, backup info) up-to-date without hammering the Proxmox API on every scrape.

Full settings.json with all defaults (Standard profile)

{
  "Prometheus": {
    "Enabled": true,                    // enable the Prometheus exporter
    "Host": "localhost",                // HTTP listener host (0.0.0.0 to expose publicly)
    "Port": 9221,                       // HTTP listener port
    "Url": "metrics/",                  // HTTP URL path
    "MaxParallelRequests": 5,           // parallel API requests per scrape
    "ApiInstrumentation": true,         // per-endpoint API duration histogram + errors counter
    "Cluster": {
      "Ha":         { "Enabled": true,  "CacheSeconds": 0 },
      "BackupInfo": { "Enabled": true,  "CacheSeconds": 600 }
    },
    "Node": {
      "Status":       { "Enabled": true,  "CacheSeconds": 0 },     // memory/swap/load + version
      "Subscription": { "Enabled": true,  "CacheSeconds": 3600 },  // status + next due
      "Replication":  { "Enabled": true,  "CacheSeconds": 0 },
      "DiskSmart":    { "Enabled": false, "CacheSeconds": 0 }      // opt-in (1 call per node)
    },
    "Guest": {
      "Balloon":      { "Enabled": false, "CacheSeconds": 0 }      // opt-in (1 RPC per running QEMU)
    }
  }
}

Response Files

Arguments can be stored in a response file and referenced with @filename. This is useful to avoid repeating connection parameters on every run.

# config.rsp
--host
192.168.1.1
--api-token
user@pam!metrics=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

cv4pve-metrics-exporter @config.rsp run
cv4pve-metrics-exporter @config.rsp --settings-file=settings.json run
cv4pve-metrics-exporter @config.rsp run --full
  • One token per line (option name and value on separate lines)
  • Lines starting with # are comments
  • Response files can be nested: a line starting with @ references another file

Exported Metrics

All metrics are prefixed with cv4pve_.

Show all exported metrics

Core (always on)

MetricTypeLabelsDescription
cv4pve_upgaugeid, type1 if resource is online/running/available
cv4pve_cluster_infogaugename, versionCluster info (always 1)
cv4pve_cluster_quorategaugename1 if cluster is quorate
cv4pve_cluster_nodesgaugenameNumber of nodes in the cluster
cv4pve_node_infogaugeid, name, ip, levelNode info (always 1)
cv4pve_guest_infogaugeid, vmid, node, name, type, tags, templateVM/CT info (always 1, tags sorted to prevent churn)
cv4pve_guest_lockgaugeid, state1 if guest matches lock state — backup/clone/create/migrate/rollback/snapshot/snapshot-delete/suspended/suspending
cv4pve_storage_infogaugeid, node, storage, contentStorage info (always 1, content is sorted CSV)
cv4pve_storage_sharedgaugeid1 if storage is shared across nodes

Self-monitoring (always on)

MetricTypeLabelsDescription
cv4pve_scrape_duration_secondsgauge—Duration of the last scrape
cv4pve_scrape_last_success_timestamp_secondsgauge—Unix timestamp of the last successful scrape
cv4pve_scrape_errors_totalcountersectionTotal number of errors per scrape section

Guest (per VM/CT, always on)

MetricTypeLabelsDescription
cv4pve_guest_cpu_usage_ratiogaugeidCPU usage (0..1)
cv4pve_guest_cpu_coresgaugeidCPU cores allocated
cv4pve_guest_memory_size_bytesgaugeidConfigured memory
cv4pve_guest_memory_usage_bytesgaugeidUsed memory
cv4pve_guest_memory_host_ratiogaugeidGuest memory usage over host total (0..1)
cv4pve_guest_disk_size_bytesgaugeidDisk total size
cv4pve_guest_disk_usage_bytesgaugeidDisk used
cv4pve_guest_uptime_secondsgaugeidUptime
cv4pve_guest_disk_read_bytes_totalcounteridTotal bytes read
cv4pve_guest_disk_write_bytes_totalcounteridTotal bytes written
cv4pve_guest_network_receive_bytes_totalcounteridTotal bytes received
cv4pve_guest_network_transmit_bytes_totalcounteridTotal bytes transmitted

Storage (per storage, always on)

MetricTypeLabelsDescription
cv4pve_storage_size_bytesgaugeidStorage total size
cv4pve_storage_usage_bytesgaugeidStorage used

Node Status (if Node.Status enabled)

MetricTypeLabelsDescription
cv4pve_node_uptime_secondsgaugenodeUptime
cv4pve_node_load_avg1gaugenodeLoad average 1 min
cv4pve_node_load_avg5gaugenodeLoad average 5 min
cv4pve_node_load_avg15gaugenodeLoad average 15 min
cv4pve_node_memory_used_bytesgaugenodeMemory used
cv4pve_node_memory_total_bytesgaugenodeMemory total
cv4pve_node_memory_assigned_bytesgaugenodeSum of configured memory of running guests on this node
cv4pve_node_swap_used_bytesgaugenodeSwap used
cv4pve_node_swap_total_bytesgaugenodeSwap total
cv4pve_node_root_fs_used_bytesgaugenodeRoot FS used
cv4pve_node_root_fs_total_bytesgaugenodeRoot FS total
cv4pve_node_cpu_assigned_coresgaugenodeSum of CPU cores allocated to running guests
cv4pve_node_version_infogaugenode, version, release, repoidNode Proxmox VE version (always 1)

Subscription (if Node.Subscription enabled)

MetricTypeLabelsDescription
cv4pve_node_subscription_infogaugenode, levelSubscription info (always 1)
cv4pve_node_subscription_statusgaugenode, status1 if matches status — active/expired/new/notfound/invalid/suspended
cv4pve_node_subscription_next_due_timestamp_secondsgaugenodeNext due date as Unix timestamp

Replication (if Node.Replication enabled)

MetricTypeLabelsDescription
cv4pve_replication_duration_secondsgaugeid, type, source, target, guestLast replication duration
cv4pve_replication_last_sync_timestamp_secondsgaugesameLast successful sync
cv4pve_replication_next_sync_timestamp_secondsgaugesameNext scheduled sync
cv4pve_replication_failed_totalcountersameFailed replication count

SMART (if Node.DiskSmart enabled)

MetricTypeLabelsDescription
cv4pve_node_disk_healthgaugenode, serial, type, dev_path1 if SMART PASSED
cv4pve_node_disk_wearoutgaugesameWearout percentage (0..100)

HA (always on)

MetricTypeLabelsDescription
cv4pve_ha_stategaugesid, type, group, state1 if guest matches state
cv4pve_ha_node_stategaugenode, state1 if node matches HA state
cv4pve_ha_quorategauge—1 if the HA manager reports quorum

Guest state values: stopped, request_stop, request_start, request_start_balance, started, fence, recovery, migrate, relocate, freeze, error, disabled. Node state values: online, maintenance, unknown, fence, gone.

Backup (always on)

MetricTypeLabelsDescription
cv4pve_guests_not_backed_upgauge—Number of guests not covered by any backup job
cv4pve_not_backed_up_infogaugeid1 if guest is not covered by any backup job

Balloon (if Guest.Balloon enabled)

MetricTypeLabelsDescription
cv4pve_guest_balloon_actual_bytesgaugeid, vmidQEMU balloon actual memory

API Instrumentation (if ApiInstrumentation = true)

MetricTypeLabelsDescription
cv4pve_api_request_duration_secondshistogrammethod, endpointDuration of Proxmox API requests (path is normalized: {node}, {vmid}, {upid})
cv4pve_api_request_errors_totalcountermethod, endpointFailed Proxmox API requests

Performance Tuning

Increase parallelism

By default the exporter runs up to 5 parallel API requests per scrape (MaxParallelRequests = 5).

"MaxParallelRequests": 10

> Don't go too high. Each parallel request is a real HTTP call to Proxmox. Values between 5 and 15 are a reasonable range. On very large clusters, prefer the Fast profile or aggressive cache TTL over increasing parallelism.

Cache TTL for slow-changing data

Set CacheSeconds per collector to avoid hammering Proxmox on every scrape:

"Node": {
  "DiskSmart":    { "Enabled": true, "CacheSeconds": 1800 },  // 30 min
  "Subscription": { "Enabled": true, "CacheSeconds": 3600 }   // 1 h
}

The metric remains visible to Prometheus between refreshes — only the underlying API call is skipped.

Minimize API calls

The Fast profile skips all per-node toggles (Status, Subscription, Replication) — only the cluster-wide bulk calls plus HA. Ideal for very large clusters or high scrape frequencies.

Debug API endpoints

Enable ApiInstrumentation (default on) and look at cv4pve_api_request_duration_seconds to identify which endpoints are slowest:

# Average latency per endpoint over last 5 min
rate(cv4pve_api_request_duration_seconds_sum[5m])
  / rate(cv4pve_api_request_duration_seconds_count[5m])

# p99 latency
histogram_quantile(0.99, rate(cv4pve_api_request_duration_seconds_bucket[5m]))

Summary

SettingEffectDefault
MaxParallelRequests ↑Faster, but more load on Proxmox5
*.CacheSeconds ↑Fewer API calls for slow data, metrics held between refresh0 / 600 / 3600 (varies)
ApiInstrumentationPer-endpoint latency histograms — handy for tuningon
Fast profileSkip all per-node callsoff

Support

Professional support and consulting available through Corsinvest.

Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest

Copyright © Corsinvest Srl