Proxmox Virtual Environment extension
- Latest Dynatrace
- Extension
- Published Sep 24, 2026
Monitor Proxmox VE clusters, nodes, QEMU virtual machines, LXC containers, storage, and Ceph with metrics, topology, dashboards, and alerts in Dynatrace.
Get full-stack observability for your Proxmox virtualization estate.
Get started
Overview
Proxmox Virtual Environment (Proxmox VE) is an open-source platform for running QEMU virtual machines and LXC containers on clustered hosts. This extension connects to the Proxmox REST API with a Proxmox API token and collects metrics, topology, dashboards, alerts, and unified analysis pages for your clusters, nodes, virtual machines, containers, storage, and Ceph. It runs remotely on an ActiveGate and doesn't install any agent on the Proxmox hosts.
The extension maps the whole estate as Dynatrace entities—clusters, nodes, virtual machines, containers, and storage—and links nodes and virtual machines to their corresponding hosts, so you can navigate from a cluster down to an individual guest.
Use cases
- Monitor the health, quorum, and capacity of your Proxmox clusters and nodes from one place.
- Track CPU, memory, disk, and network usage across QEMU virtual machines and LXC containers.
- Detect node CPU saturation, lost high-availability quorum, and failed node tasks with prebuilt alerts.
- Analyze Ceph storage health, OSD state, placement-group state, and per-pool utilization.
- Investigate the relationships between clusters, nodes, guests, and storage in Smartscape.
Requirements
- A Proxmox VE API token in
user@realmformat, with a token name and secret, granting read access to the monitored resources. ThePVEAuditorrole on/is sufficient. - Network reachability from the ActiveGate to the Proxmox API (port
8006by default).
Compatibility information
- Dynatrace version 1.343+.
- Environment ActiveGate version 1.313+.
Activation and setup
Prerequisites
- An ActiveGate to host the extension. The extension monitors Proxmox remotely; it doesn't run on the Proxmox hosts.
- A Proxmox API token, as described in Requirements.
To start monitoring:
- In Proxmox, create an API token for a user that holds the
PVEAuditorrole, and copy the token secret. - In Dynatrace, go to Dynatrace Hub, find Proxmox Virtual Environment, and select Add to environment.
- Create a monitoring configuration and select the ActiveGate group that can reach the Proxmox API.
- Enter the Proxmox host, port, username, token name, and token secret. Optionally store the token secret in the Dynatrace credential vault and reference it instead.
- Select the feature sets you want to collect, then save the configuration.
Monitoring configurations
A monitoring configuration defines one Proxmox connection:
- Host and Port: the address of a Proxmox cluster node and its API port (default
8006). - Username, Token name, and Token value—the API token credentials, or a credential-vault reference to the token.
- Verify SSL certificate: off by default, because self-hosted Proxmox typically uses self-signed certificates. Turn it on when the API presents a trusted certificate.
- Collection interval: how often the extension polls the Proxmox API.
- Monitored systemd services: the node services whose state is reported. A default set covers the core Proxmox services; you can customize the list.
Details
This extension package contains:
- Custom entity types for Proxmox clusters, nodes, QEMU virtual machines, LXC containers, and storage, plus the relationships between them, in both classic topology and Smartscape.
- A Proxmox VE overview dashboard.
- Metric events that alert on node CPU saturation, lost high-availability quorum, and failed node tasks.
- Unified analysis pages for clusters, nodes, virtual machines, containers, and storage.
Metrics
Metrics are namespaced under proxmox. across six domains—proxmox.cluster, proxmox.node, proxmox.vm, proxmox.container, proxmox.storage, and proxmox.ceph—and grouped into feature sets so you can collect only what you need. Recommended feature sets are enabled by default; the extended and Ceph feature sets are opt-in.
Licensing and costs
There is no charge to use the extension. You are only charged for the data that the extension ingests.
The Proxmox Virtual Environment extension ingests custom metrics, which consume Davis data units (DDUs) (Dynatrace classic license) or Metrics powered by Grail (DPS), according to your license model.
By default, this extension queries for data every minute. You can change the polling frequency in the monitoring configuration with the Collection interval setting, so keep your configured interval in mind when you estimate cost: a longer interval produces the same datapoints less often and lowers consumption proportionally. To estimate the number of metric datapoints produced by your extension configuration, use the following list, which gives you a number of metrics per feature set and a multiplier value depending on which entity the metric is split by. Add all of these up to get the total datapoints per collection cycle (every minute at the default interval).
Cluster14 × number of Proxmox clustersCeph22 × number of Proxmox clusters + 1 × number of Proxmox clusters × number of Ceph flags + 2 × number of Proxmox clusters × number of Ceph poolsNode20 × number of Proxmox nodesNode-Extended12 × number of Proxmox nodes + 2 × number of Proxmox nodes × number of physical disks + 1 × number of Proxmox nodes × number of physical disks × number of SMART attributesNode-Services3 × number of Proxmox nodes × number of monitored servicesNode-Storage7 × number of Proxmox storage volumesVM16 × number of Proxmox virtual machinesVM-Extended15 × number of Proxmox virtual machines + 2 × number of Proxmox virtual machines × number of guest filesystems + 6 × number of Proxmox virtual machines × number of guest network interfacesContainer13 × number of Proxmox containersContainer-Extended15 × number of Proxmox containers
Dynatrace Platform Subscription
In the Dynatrace Platform Subscription, metric ingestion consumes Metrics powered by Grail according to the number of ingested metric data points.
To calculate the approximate yearly consumption, apply the following calculation: <metric data points per minute> * 60 minutes * 24 hours * 365 days.
For example, at 64 metric data points per minute: 64 * 60 * 24 * 365 = 33,638,400 metric data points per year.
Dynatrace classic license
In the classic licensing model, metric ingestion consumes Davis data units (DDUs) at the rate of 0.001 DDUs per metric data point. Multiply the annual data point formula by 0.001 to estimate annual DDU usage.
For example, at 64 metric data points per minute: 64 * 60 * 24 * 365 * 0.001 = 33,638.4 DDUs per year.
The DDU cost doesn't include any log events or custom events the extension triggers. For more information, see DDU events.
Feature sets
When activating your extension using a monitoring configuration, you can limit monitoring to one of the feature sets. To work properly, the extension has to collect at least one metric after the activation.
In highly segmented networks, feature sets can reflect the segments of your environment. Then, when you create a monitoring configuration, you can select a feature set and a corresponding ActiveGate group that can connect to this particular segment.
All metrics that aren't categorized into any feature set are considered to be the default and are always reported.
A metric inherits the feature set of a subgroup, which in turn inherits the feature set of a group. Also, the feature set defined on the metric level overrides the feature set defined on the subgroup level, which in turn overrides the feature set defined on the group level.
Node-Extended
| Metric name | Metric key | Description |
|---|---|---|
| Node Subscription Active | proxmox.node.subscription.active | 1 if the node has an active Proxmox subscription |
| Node Updates Pending | proxmox.node.updates.pending | Total pending APT package updates |
| Node Proxmox Updates Pending | proxmox.node.updates.pending_proxmox | Pending updates originating from the Proxmox repositories |
| Node Tasks Failed | proxmox.node.tasks.failed | Tasks in the recent history that ended in FAILED status |
| Node Tasks Running | proxmox.node.tasks.running | Tasks currently in progress |
| Physical Disk Size | proxmox.node.disk.size | Raw physical disk capacity |
| Physical Disk SMART Health | proxmox.node.disk.smart_passed | 1 if SMART overall health is PASSED |
| Physical Disk SMART Attribute | proxmox.node.disk.smart_attribute | Raw value of a tracked SMART attribute |
| Node Memory Available | proxmox.node.memory.available | Usable memory including reclaimable page cache |
| Node ZFS ARC Size | proxmox.node.zfs.arc_size | ZFS adaptive replacement cache size (0 on non-ZFS hosts) |
| Node CPU Pressure (some) | proxmox.node.pressure.cpu.some | Linux PSI: share of time some task was stalled on CPU |
| Node I/O Pressure (some) | proxmox.node.pressure.io.some | Linux PSI: share of time some task was stalled on I/O |
| Node I/O Pressure (full) | proxmox.node.pressure.io.full | Linux PSI: share of time all tasks were stalled on I/O |
| Node Memory Pressure (some) | proxmox.node.pressure.memory.some | Linux PSI: share of time some task was stalled on memory |
| Node Memory Pressure (full) | proxmox.node.pressure.memory.full | Linux PSI: share of time all tasks were stalled on memory |
VM
| Metric name | Metric key | Description |
|---|---|---|
| VM Status | proxmox.vm.status | 1 if the VM is running |
| VM CPU Usage | proxmox.vm.cpu.usage | CPU utilization |
| VM vCPU Count | proxmox.vm.cpu.count | Allocated virtual CPUs |
| VM Memory Used | proxmox.vm.memory.used | Memory currently in use |
| VM Memory Total | proxmox.vm.memory.total | Maximum allocated memory |
| VM Memory Free | proxmox.vm.memory.free | Estimated free memory (maxmem - mem). When the balloon driver is active this may overstate available memory, since the balloon reports how much the host has reclaimed rather than what the guest OS considers free. |
| VM Memory Used % | proxmox.vm.memory.used_pct | Percentage of allocated memory in use (mem / maxmem × 100). Only reported when maxmem > 0. |
| VM Disk Read | proxmox.vm.disk.read | Cumulative bytes read since the VM started |
| VM Disk Write | proxmox.vm.disk.write | Cumulative bytes written since the VM started |
| VM Disk Size | proxmox.vm.disk.size | Allocated root disk size |
| VM Network In | proxmox.vm.network.in | Cumulative bytes received since the VM started |
| VM Network Out | proxmox.vm.network.out | Cumulative bytes sent since the VM started |
| VM Uptime | proxmox.vm.uptime | Time since the VM last started |
| VM QMP Status | proxmox.vm.qmp_status | 1 if the QEMU Machine Protocol monitor reports the VM running |
| VM Lock | proxmox.vm.lock | 1 if the VM has an active configuration lock, 0 if unlocked. The lock type (e.g. "backup", "migrate", "snapshot") is stored in the vm_lock dimension. A value of "none" means no lock is held. Locked VMs cannot be started, stopped, or reconfigured until the operation completes. |
| VM HA State | proxmox.vm.ha.state | Always 1 for each reporting interval; the HA service state (e.g. "started", "stopped", "error", "migrate") is captured in the vm_ha_state dimension. Only reported for VMs registered with the Proxmox HA manager. Use vm_ha_state == "error" to alert on HA failures. |
Container-Extended
| Metric name | Metric key | Description |
|---|---|---|
| Container Configured Cores | proxmox.container.config.cores | Configured CPU cores |
| Container Configured Memory | proxmox.container.config.memory | Configured maximum memory |
| Container Configured Swap | proxmox.container.config.swap | Configured maximum swap |
| Container CPU Limit | proxmox.container.config.cpu_limit | Configured CPU limit (0 = unlimited) |
| Container CPU Priority Units | proxmox.container.config.cpu_units | Configured relative CPU scheduling weight |
| Container Start On Boot | proxmox.container.config.start_on_boot | 1 if the container is configured to start on node boot |
| Container Unprivileged | proxmox.container.config.unprivileged | 1 if the container runs unprivileged |
| Container Snapshot Count | proxmox.container.snapshot.count | Snapshots currently held |
| Container Disk Used (actual) | proxmox.container.disk.used | Actual disk space consumed, distinct from allocated size |
| Container Host Memory Used | proxmox.container.memory.host | Host-side memory held by this guest |
| Container CPU Pressure (some) | proxmox.container.pressure.cpu.some | Linux PSI: share of time some task was stalled on CPU |
| Container CPU Pressure (full) | proxmox.container.pressure.cpu.full | Linux PSI: share of time all tasks were stalled on CPU |
| Container I/O Pressure (some) | proxmox.container.pressure.io.some | Linux PSI: share of time some task was stalled on I/O |
| Container Memory Pressure (some) | proxmox.container.pressure.memory.some | Linux PSI: share of time some task was stalled on memory |
| Container Memory Pressure (full) | proxmox.container.pressure.memory.full | Linux PSI: share of time all tasks were stalled on memory |
Node
| Metric name | Metric key | Description |
|---|---|---|
| Node Online | proxmox.node.online | 1 if the node is online in the cluster |
| Node CPU Usage | proxmox.node.cpu.usage | CPU utilization |
| Node CPU I/O Wait | proxmox.node.cpu.wait | CPU time spent waiting on I/O |
| Node CPU Count | proxmox.node.cpu.count | Logical CPUs available to the node |
| Node CPU Sockets | proxmox.node.cpu.sockets | Physical CPU sockets |
| Node Load Average (1m) | proxmox.node.loadavg.1m | 1-minute load average |
| Node Load Average (5m) | proxmox.node.loadavg.5m | 5-minute load average |
| Node Load Average (15m) | proxmox.node.loadavg.15m | 15-minute load average |
| Node Memory Used | proxmox.node.memory.used | Physical memory in use |
| Node Memory Total | proxmox.node.memory.total | Total physical memory |
| Node Memory Free | proxmox.node.memory.free | Free physical memory |
| Node Memory Usage | proxmox.node.memory.used_pct | Physical memory utilisation as a percentage (memory.used / memory.total × 100) |
| Node Swap Used | proxmox.node.swap.used | Swap space in use |
| Node Swap Total | proxmox.node.swap.total | Total swap space |
| Node Swap Free | proxmox.node.swap.free | Free swap space |
| Node Root FS Used | proxmox.node.rootfs.used | Root filesystem space used |
| Node Root FS Total | proxmox.node.rootfs.total | Root filesystem capacity |
| Node Root FS Available | proxmox.node.rootfs.avail | Root filesystem space available |
| Node Uptime | proxmox.node.uptime | Time since the node last booted |
| Node KSM Shared Memory | proxmox.node.ksm.shared | Memory de-duplicated by Kernel Samepage Merging |
Node-Services
| Metric name | Metric key | Description |
|---|---|---|
| Node Service Active | proxmox.node.service.active | 1 if the monitored systemd service is active (active-state == "active"), 0 otherwise. The state dimension holds the derived value ("active" or "inactive"). |
| Node Service State | proxmox.node.service.state | Always 1 for each reporting interval; the raw systemd active-state string (e.g. "active", "inactive", "failed", "activating") is captured in the service_state dimension. Filter on service_state to isolate services in a particular state. |
| Node Service Enabled | proxmox.node.service.enabled | 1 if the service is configured to start on boot (unit-state is "enabled" or "enabled-runtime"), 0 otherwise. The raw unit-state string is stored in the service_unit_state dimension. A value of 0 with state "active" indicates a service that is running but will not survive a reboot. |
Ceph
| Metric name | Metric key | Description |
|---|---|---|
| Ceph Health | proxmox.ceph.health | 2=HEALTH_OK, 1=HEALTH_WARN, 0=HEALTH_ERR, -1=unknown |
| Ceph OSDs Total | proxmox.ceph.osd.total | Total OSDs in the cluster |
| Ceph OSDs Up | proxmox.ceph.osd.up | OSDs currently up |
| Ceph OSDs In | proxmox.ceph.osd.in | OSDs currently in the CRUSH map |
| Ceph OSDs Down | proxmox.ceph.osd.down | OSDs that are not up (total minus up). Derived as num_osds - num_up_osds. |
| Ceph OSDs Out | proxmox.ceph.osd.out | OSDs removed from the CRUSH map (total minus in). Derived as num_osds - num_in_osds. |
| Ceph Placement Groups | proxmox.ceph.pg.total | Total placement groups |
| Ceph Active PGs | proxmox.ceph.pg.active | Placement groups currently in an active state (sum of all PG states containing "active") |
| Ceph Degraded PGs | proxmox.ceph.pg.degraded | Placement groups with reduced redundancy (sum of all PG states containing "degraded"). Non-zero indicates data protection loss. |
| Ceph Recovering PGs | proxmox.ceph.pg.recovering | Placement groups currently recovering data (sum of all PG states containing "recovering") |
| Ceph Undersized PGs | proxmox.ceph.pg.undersized | Placement groups with fewer replicas than required (sum of all PG states containing "undersized") |
| Ceph Bytes Used | proxmox.ceph.bytes.used | Raw bytes used across the Ceph cluster |
| Ceph Bytes Available | proxmox.ceph.bytes.avail | Raw bytes available across the Ceph cluster |
| Ceph Bytes Total | proxmox.ceph.bytes.total | Raw capacity across the Ceph cluster |
| Ceph Capacity Used % | proxmox.ceph.bytes.used_pct | Percentage of raw Ceph cluster capacity used. Derived as bytes_used / bytes_total * 100. |
| Ceph Read Throughput | proxmox.ceph.io.read_bps | Cluster-wide read throughput |
| Ceph Write Throughput | proxmox.ceph.io.write_bps | Cluster-wide write throughput |
| Ceph Recovery Throughput | proxmox.ceph.io.recovering_bps | Data movement rate during recovery/backfill |
| Ceph Read IOPS | proxmox.ceph.io.read_ops | Cluster-wide read operations per second |
| Ceph Write IOPS | proxmox.ceph.io.write_ops | Cluster-wide write operations per second |
| Ceph Monitor Count | proxmox.ceph.mon.count | Number of Ceph monitors |
| Ceph Monitors in Quorum | proxmox.ceph.mon.quorum | Number of Ceph monitors participating in quorum. Quorum loss (drops below majority) causes full cluster outage. |
| Ceph Flag Active | proxmox.ceph.flag | 1 if the named Ceph cluster flag is set |
| Ceph Pool Used Bytes | proxmox.ceph.pool.used_bytes | Bytes used by this pool. Dimension pool_name identifies the pool. |
| Ceph Pool Used % | proxmox.ceph.pool.used_pct | Percentage of pool quota used. Dimension pool_name identifies the pool. |
Container
| Metric name | Metric key | Description |
|---|---|---|
| Container Status | proxmox.container.status | 1 if the container is running |
| Container CPU Usage | proxmox.container.cpu.usage | CPU utilization |
| Container vCPU Count | proxmox.container.cpu.count | Allocated virtual CPUs |
| Container Memory Used | proxmox.container.memory.used | Memory currently in use |
| Container Memory Total | proxmox.container.memory.total | Maximum allocated memory |
| Container Swap Used | proxmox.container.swap.used | Swap space in use |
| Container Swap Total | proxmox.container.swap.total | Maximum allocated swap |
| Container Disk Read | proxmox.container.disk.read | Cumulative bytes read since the container started |
| Container Disk Write | proxmox.container.disk.write | Cumulative bytes written since the container started |
| Container Disk Size | proxmox.container.disk.size | Allocated root disk size |
| Container Network In | proxmox.container.network.in | Cumulative bytes received since the container started |
| Container Network Out | proxmox.container.network.out | Cumulative bytes sent since the container started |
| Container Uptime | proxmox.container.uptime | Time since the container last started |
Cluster
| Metric name | Metric key | Description |
|---|---|---|
| Cluster Nodes Total | proxmox.cluster.nodes.total | Total nodes registered in the cluster |
| Cluster Nodes Online | proxmox.cluster.nodes.online | Nodes currently online |
| Cluster Nodes Offline | proxmox.cluster.nodes.offline | Nodes currently offline (total minus online) |
| Cluster CPU Usage | proxmox.cluster.cpu.usage | Cluster-wide CPU utilisation as a weighted average across all online nodes. Calculated as sum(node_cpu_fraction × node_cpu_count) / sum(node_cpu_count) × 100, so nodes with more CPUs contribute proportionally more to the result. |
| Cluster Memory Used | proxmox.cluster.memory.used | Total memory used across all online cluster nodes in bytes |
| Cluster Memory Total | proxmox.cluster.memory.total | Total memory capacity across all online cluster nodes in bytes |
| Cluster Memory Usage | proxmox.cluster.memory.usage | Cluster-wide memory utilisation as a percentage (memory.used / memory.total × 100) |
| Cluster Quorate | proxmox.cluster.quorate | 1 if the cluster has quorum (majority of nodes online for Corosync decisions), 0 if not |
| SDN Status | proxmox.cluster.sdn.status | 1 if all SDN zones are applied and clean, 0 if any zone is in a pending or error state |
| HA Quorate | proxmox.cluster.ha.quorate | 1 if the HA manager reports quorum |
| HA Resource Running | proxmox.cluster.ha.resource.running | 1 if the HA-managed resource is started |
| HA Resource Error | proxmox.cluster.ha.resource.error | 1 if the HA-managed resource is in an error state |
| HA Resource Stopped | proxmox.cluster.ha.resource.stopped | 1 if the HA-managed resource is stopped |
| Guests Without Backup | proxmox.cluster.backup.unprotected_guests | VMs/containers with no backup job covering them |
VM-Extended
| Metric name | Metric key | Description |
|---|---|---|
| VM Configured Cores | proxmox.vm.config.cores | Configured CPU cores |
| VM Configured Sockets | proxmox.vm.config.sockets | Configured CPU sockets |
| VM Configured Memory | proxmox.vm.config.memory | Configured maximum memory |
| VM Configured Balloon Minimum | proxmox.vm.config.balloon_min | Configured minimum balloon memory |
| VM CPU Limit | proxmox.vm.config.cpu_limit | Configured CPU limit (0 = unlimited) |
| VM CPU Priority Units | proxmox.vm.config.cpu_units | Configured relative CPU scheduling weight |
| VM Start On Boot | proxmox.vm.config.start_on_boot | 1 if the VM is configured to start on node boot |
| VM Snapshot Count | proxmox.vm.snapshot.count | Snapshots currently held |
| VM Disk Used (actual) | proxmox.vm.disk.used | Actual disk space consumed, distinct from allocated size |
| VM Host Memory Used | proxmox.vm.memory.host | Host-side memory held by this guest (balloon perspective) |
| VM CPU Pressure (some) | proxmox.vm.pressure.cpu.some | Linux PSI: share of time some task was stalled on CPU |
| VM CPU Pressure (full) | proxmox.vm.pressure.cpu.full | Linux PSI: share of time all tasks were stalled on CPU |
| VM I/O Pressure (some) | proxmox.vm.pressure.io.some | Linux PSI: share of time some task was stalled on I/O |
| VM Memory Pressure (some) | proxmox.vm.pressure.memory.some | Linux PSI: share of time some task was stalled on memory |
| VM Memory Pressure (full) | proxmox.vm.pressure.memory.full | Linux PSI: share of time all tasks were stalled on memory |
| VM Guest Disk Used | proxmox.vm.agent.disk.used | In-guest filesystem space used, reported by the guest agent |
| VM Guest Disk Total | proxmox.vm.agent.disk.total | In-guest filesystem capacity, reported by the guest agent |
| VM Guest NIC RX Bytes | proxmox.vm.agent.network.rx_bytes | In-guest NIC receive bytes, reported by the guest agent |
| VM Guest NIC TX Bytes | proxmox.vm.agent.network.tx_bytes | In-guest NIC transmit bytes, reported by the guest agent |
| VM Guest NIC RX Errors | proxmox.vm.agent.network.rx_errors | In-guest NIC receive errors, reported by the guest agent |
| VM Guest NIC TX Errors | proxmox.vm.agent.network.tx_errors | In-guest NIC transmit errors, reported by the guest agent |
| VM Guest NIC RX Dropped | proxmox.vm.agent.network.rx_dropped | In-guest NIC receive drops, reported by the guest agent |
| VM Guest NIC TX Dropped | proxmox.vm.agent.network.tx_dropped | In-guest NIC transmit drops, reported by the guest agent |
Node-Storage
| Metric name | Metric key | Description |
|---|---|---|
| Storage Total | proxmox.storage.total | Total storage capacity |
| Storage Used | proxmox.storage.used | Storage space used |
| Storage Available | proxmox.storage.avail | Storage space available |
| Storage Used % | proxmox.storage.used_pct | Percentage of storage capacity consumed (used / total x 100). Only reported when total > 0. |
| Storage Enabled | proxmox.storage.enabled | 1 if the storage is enabled |
| Storage Active | proxmox.storage.active | 1 if the storage is currently active |
| Storage Backup Count | proxmox.storage.backup_count | Backup archives held on this storage |
FAQ
A virtual machine has no IP address. Why?
The extension reads virtual machine IP addresses from the QEMU guest agent. If the guest agent isn't installed and running inside the virtual machine, the IP dimension is empty for that virtual machine; all other metrics are unaffected. Install and start qemu-guest-agent inside the virtual machine to populate it.
No high-availability metrics are reported.
High-availability metrics require an HA-enabled Proxmox cluster. On clusters without HA configured, the corresponding API returns an error, which the extension logs and skips. Other metrics are unaffected.
No Ceph metrics are reported.
The Ceph feature set collects data only when Ceph is deployed on the cluster, and it's opt-in. Enable the Ceph feature set in the monitoring configuration on a cluster that runs Ceph.
Related tags
VirtualizationPythonHypervisorProxmoxInfrastructure Observability