Skip to content
PiVirt

Metrics API

PiVirt components expose standardized Prometheus /metrics endpoints, along with /healthz and /readyz probes for real-time observability, health checking, and Kubernetes integration.

Metrics Endpoints

Section titled “Metrics Endpoints”
Component Endpoint Port Path
pivirtd HTTP 9002 /metrics
agent HTTP 8444 /metrics
iscsiman HTTP 9003 /metrics
deployer HTTP 9005 /metrics

Health Endpoints

Section titled “Health Endpoints”

pivirtd exposes HTTP health endpoints on its Unix socket (and optionally on TCP if listen_tcp is configured):

Endpoint Description Status Codes
/healthz Liveness probe — always returns 200 200 OK
/readyz Readiness probe — checks VM manager availability 200 OK or 503 Service Unavailable
Terminal window
# Liveness check via Unix socket
curl --unix-socket /var/lib/pivirt/daemon/pivirtd.sock http://localhost/healthz
# → {"status":"ok"}


# Readiness check
curl --unix-socket /var/lib/pivirt/daemon/pivirtd.sock http://localhost/readyz
# → {"status":"ok"} or {"status":"not ready","reason":"vm manager unavailable"}


# Over TCP (if listen_tcp configured)
curl http://localhost:8443/healthz
curl http://localhost:8443/readyz

Metrics Configuration

Section titled “Metrics Configuration”

Enable Metrics

Section titled “Enable Metrics”
# pivirtd config
metrics:
  enabled: true
  path: "/metrics"
  addr: "0.0.0.0:9002"

Authentication

Section titled “Authentication”
# agent config
metrics:
  enabled: true
  auth:
    enabled: true
    basic_auth:
      username: "metrics"
      password_ref: "vault:secret/data/metrics#password"

Daemon Metrics

Section titled “Daemon Metrics”

These metrics are exposed by the pivirtd daemon itself (not per-VM):

# HELP pivirtd_vm_count Current number of VMs
# TYPE pivirtd_vm_count gauge
pivirtd_vm_count 12


# HELP pivirtd_vm_state Number of VMs in each state
# TYPE pivirtd_vm_state gauge
pivirtd_vm_state{state="running"} 8
pivirtd_vm_state{state="stopped"} 3
pivirtd_vm_state{state="paused"} 1


# HELP pivirtd_uptime_seconds Daemon uptime in seconds
# TYPE pivirtd_uptime_seconds counter
pivirtd_uptime_seconds 3600

VM Metrics

Section titled “VM Metrics”

CPU Metrics

Section titled “CPU Metrics”
# HELP pivirtd_vm_cpu_usage_percent VM CPU usage percentage
# TYPE pivirtd_vm_cpu_usage_percent gauge
pivirtd_vm_cpu_usage_percent{vm="web-01",namespace="production"} 23.5
pivirtd_vm_cpu_usage_percent{vm="db-01",namespace="production"} 45.2


# HELP pivirtd_vm_cpu_time_seconds_total VM CPU time in seconds
# TYPE pivirtd_vm_cpu_time_seconds_total counter
pivirtd_vm_cpu_time_seconds_total{vm="web-01",namespace="production"} 12345.67

Memory Metrics

Section titled “Memory Metrics”
# HELP pivirtd_vm_memory_usage_bytes VM memory usage in bytes
# TYPE pivirtd_vm_memory_usage_bytes gauge
pivirtd_vm_memory_usage_bytes{vm="web-01",namespace="production"} 2147483648


# HELP pivirtd_vm_memory_total_bytes VM total memory in bytes
# TYPE pivirtd_vm_memory_total_bytes gauge
pivirtd_vm_memory_total_bytes{vm="web-01",namespace="production"} 4294967296


# HELP pivirtd_vm_memory_usage_percent VM memory usage percentage
# TYPE pivirtd_vm_memory_usage_percent gauge
pivirtd_vm_memory_usage_percent{vm="web-01",namespace="production"} 50.0

Disk Metrics

Section titled “Disk Metrics”
# HELP pivirtd_vm_disk_read_bytes_total VM disk read bytes
# TYPE pivirtd_vm_disk_read_bytes_total counter
pivirtd_vm_disk_read_bytes_total{vm="web-01",namespace="production",disk="root"} 1073741824


# HELP pivirtd_vm_disk_write_bytes_total VM disk write bytes
# TYPE pivirtd_vm_disk_write_bytes_total counter
pivirtd_vm_disk_write_bytes_total{vm="web-01",namespace="production",disk="root"} 536870912


# HELP pivirtd_vm_disk_iops VM disk IOPS
# TYPE pivirtd_vm_disk_iops gauge
pivirtd_vm_disk_iops{vm="web-01",namespace="production",disk="root",op="read"} 150
pivirtd_vm_disk_iops{vm="web-01",namespace="production",disk="root",op="write"} 75

Network Metrics

Section titled “Network Metrics”
# HELP pivirtd_vm_network_rx_bytes_total VM network receive bytes
# TYPE pivirtd_vm_network_rx_bytes_total counter
pivirtd_vm_network_rx_bytes_total{vm="web-01",namespace="production",nic="eth0"} 2147483648


# HELP pivirtd_vm_network_tx_bytes_total VM network transmit bytes
# TYPE pivirtd_vm_network_tx_bytes_total counter
pivirtd_vm_network_tx_bytes_total{vm="web-01",namespace="production",nic="eth0"} 1073741824


# HELP pivirtd_vm_network_packets_total VM network packets
# TYPE pivirtd_vm_network_packets_total counter
pivirtd_vm_network_packets_total{vm="web-01",namespace="production",nic="eth0",dir="rx"} 1234567
pivirtd_vm_network_packets_total{vm="web-01",namespace="production",nic="eth0",dir="tx"} 765432

Storage Metrics

Section titled “Storage Metrics”

Pool Metrics

Section titled “Pool Metrics”
# HELP iscsiman_pool_capacity_bytes Storage pool capacity in bytes
# TYPE iscsiman_pool_capacity_bytes gauge
iscsiman_pool_capacity_bytes{pool="default"} 1099511627776


# HELP iscsiman_pool_used_bytes Storage pool used space in bytes
# TYPE iscsiman_pool_used_bytes gauge
iscsiman_pool_used_bytes{pool="default"} 549755813888


# HELP iscsiman_pool_available_bytes Storage pool available space in bytes
# TYPE iscsiman_pool_available_bytes gauge
iscsiman_pool_available_bytes{pool="default"} 549755813888


# HELP iscsiman_pool_usage_percent Storage pool usage percentage
# TYPE iscsiman_pool_usage_percent gauge
iscsiman_pool_usage_percent{pool="default"} 50.0

Volume Metrics

Section titled “Volume Metrics”
# HELP iscsiman_volume_size_bytes Volume size in bytes
# TYPE iscsiman_volume_size_bytes gauge
iscsiman_volume_size_bytes{volume="data-01",pool="default"} 107374182400


# HELP iscsiman_volume_used_bytes Volume used space in bytes
# TYPE iscsiman_volume_used_bytes gauge
iscsiman_volume_used_bytes{volume="data-01",pool="default"} 53687091200


# HELP iscsiman_volume_iops Volume IOPS
# TYPE iscsiman_volume_iops gauge
iscsiman_volume_iops{volume="data-01",pool="default",op="read"} 200
iscsiman_volume_iops{volume="data-01",pool="default",op="write"} 100

Cluster Metrics

Section titled “Cluster Metrics”

Node Metrics

Section titled “Node Metrics”
# HELP pivirt_cluster_node_count Number of nodes in cluster
# TYPE pivirt_cluster_node_count gauge
pivirt_cluster_node_count{cluster="prod-cluster",status="ready"} 3
pivirt_cluster_node_count{cluster="prod-cluster",status="not_ready"} 0


# HELP pivirt_cluster_node_cpu_usage_percent Cluster node CPU usage
# TYPE pivirt_cluster_node_cpu_usage_percent gauge
pivirt_cluster_node_cpu_usage_percent{cluster="prod-cluster",node="node-01"} 45.2
pivirt_cluster_node_cpu_usage_percent{cluster="prod-cluster",node="node-02"} 38.7


# HELP pivirt_cluster_node_memory_usage_percent Cluster node memory usage
# TYPE pivirt_cluster_node_memory_usage_percent gauge
pivirt_cluster_node_memory_usage_percent{cluster="prod-cluster",node="node-01"} 67.8
pivirt_cluster_node_memory_usage_percent{cluster="prod-cluster",node="node-02"} 54.3

VM Metrics

Section titled “VM Metrics”
# HELP pivirt_cluster_vm_count Number of VMs in cluster
# TYPE pivirt_cluster_vm_count gauge
pivirt_cluster_vm_count{cluster="prod-cluster",status="running"} 42
pivirt_cluster_vm_count{cluster="prod-cluster",status="stopped"} 5
pivirt_cluster_vm_count{cluster="prod-cluster",status="error"} 1

API Metrics

Section titled “API Metrics”

Request Metrics

Section titled “Request Metrics”
# HELP pivirt_api_requests_total Total API requests
# TYPE pivirt_api_requests_total counter
pivirt_api_requests_total{method="CreateVM",status="200"} 1234
pivirt_api_requests_total{method="ListVMs",status="200"} 5678
pivirt_api_requests_total{method="DeleteVM",status="404"} 12


# HELP pivirt_api_request_duration_seconds API request duration
# TYPE pivirt_api_request_duration_seconds histogram
pivirt_api_request_duration_seconds_bucket{method="CreateVM",le="0.1"} 1000
pivirt_api_request_duration_seconds_bucket{method="CreateVM",le="0.5"} 1200
pivirt_api_request_duration_seconds_bucket{method="CreateVM",le="1.0"} 1230
pivirt_api_request_duration_seconds_bucket{method="CreateVM",le="+Inf"} 1234
pivirt_api_request_duration_seconds_sum{method="CreateVM"} 123.45
pivirt_api_request_duration_seconds_count{method="CreateVM"} 1234

Prometheus Configuration

Section titled “Prometheus Configuration”

Example Scrape Config

Section titled “Example Scrape Config”
prometheus.yml
scrape_configs:
  - job_name: 'pivirtd'
    static_configs:
      - targets: ['node-01:9002', 'node-02:9002', 'node-03:9002']
    metrics_path: '/metrics'
    scrape_interval: 15s


  - job_name: 'pivirt-agent'
    static_configs:
      - targets: ['node-01:8444', 'node-02:8444', 'node-03:8444']
    metrics_path: '/metrics'
    scrape_interval: 15s


  - job_name: 'iscsiman'
    static_configs:
      - targets: ['node-01:9003', 'node-02:9003', 'node-03:9003']
    metrics_path: '/metrics'
    scrape_interval: 15s

Grafana Dashboards

Section titled “Grafana Dashboards”

Pre-built dashboards available:

  • PiVirt Cluster Overview - Cluster health, node status, VM count
  • VM Performance - CPU, memory, disk, network per VM
  • Storage Utilization - Pool usage, volume metrics, IOPS
  • API Performance - Request rates, latency, error rates
Section titled “Related”
Open: Community & Dev•Professional: Production Clustering•Enterprise: Mission-Critical & HA
© 2026 Progressive Innovation LAB. All rights reserved.Distributed virtualization platform licensed across Open, Professional, and Enterprise tiers.