Skip to content

Proxmox VE Module API Explanation

The Proxmox VE module collects real-time CPU, RAM, and storage utilization metrics from virtual hosts.

API Execution Logic

The backend process parses Proxmox VE hosts configured under proxmox.instances in the configuration. For each host, the module constructs the API URL by joining the host URL and apiPath (which targets /api2/json/nodes/[NODE_NAME]/status).

Request Execution

A GET request is sent to the status endpoint. The token is loaded from the environment variable key defined in authEnv (e.g., PVE_1_AUTH) and transmitted via the Authorization header. A 10-second timeout is attached.

Data Parsing and Normalization

Upon a successful response, the JSON payload is parsed under the data wrapper. The module extracts resource metrics and normalizes them:

  1. CPU: The value from d.cpu is multiplied by 100 to yield a percentage.
  2. RAM: The used memory (d.mem or d.memory.used) is divided by total memory (d.maxmem or d.memory.total) and multiplied by 100 to yield a percentage.

  3. Storage: If root filesystem (d.rootfs) details are returned, the used space is divided by total space and multiplied by 100 to compute the storage percentage.

  4. Specs Output: The cpu cores count (d.cpuinfo.cpus), total RAM (converted to GB), and total storage capacity (converted to GB) are returned in the specs payload.

Caching Strategy

To prevent load spikes, the metrics are cached for 10 seconds (TTL) with a stale window of 300 seconds.