| 1 | # yamllint disable rule:line-length |
| 2 | --- |
| 3 | plugin_name: guides |
| 4 | modules: |
| 5 | - meta: |
| 6 | plugin_name: guides |
| 7 | module_name: proxmox |
| 8 | monitored_instance: |
| 9 | name: Proxmox VE Monitoring |
| 10 | link: https://www.proxmox.com/ |
| 11 | icon_filename: proxmox.png |
| 12 | categories: |
| 13 | - data-collection.containers-and-vms |
| 14 | keywords: |
| 15 | - proxmox |
| 16 | - proxmox ve |
| 17 | - pve |
| 18 | - kvm |
| 19 | - qemu |
| 20 | - lxc |
| 21 | - virtualization |
| 22 | - hypervisor |
| 23 | - virtual machines |
| 24 | - containers |
| 25 | - ceph |
| 26 | - zfs |
| 27 | - corosync |
| 28 | - cluster |
| 29 | related_resources: |
| 30 | integrations: |
| 31 | list: |
| 32 | - plugin_name: cgroups.plugin |
| 33 | module_name: /sys/fs/cgroup |
| 34 | monitored_instance_name: Proxmox VMs and Containers |
| 35 | - plugin_name: cgroups.plugin |
| 36 | module_name: /sys/fs/cgroup |
| 37 | monitored_instance_name: Systemd Services |
| 38 | - plugin_name: apps.plugin |
| 39 | module_name: apps |
| 40 | monitored_instance_name: Applications |
| 41 | - plugin_name: go.d.plugin |
| 42 | module_name: zfspool |
| 43 | - plugin_name: go.d.plugin |
| 44 | module_name: ceph |
| 45 | - plugin_name: go.d.plugin |
| 46 | module_name: smartctl |
| 47 | - plugin_name: go.d.plugin |
| 48 | module_name: sensors |
| 49 | - plugin_name: proc.plugin |
| 50 | module_name: /proc/net/dev |
| 51 | - plugin_name: proc.plugin |
| 52 | module_name: /proc/diskstats |
| 53 | - plugin_name: proc.plugin |
| 54 | module_name: /proc/stat |
| 55 | - plugin_name: proc.plugin |
| 56 | module_name: /proc/meminfo |
| 57 | - plugin_name: proc.plugin |
| 58 | module_name: /proc/spl/kstat/zfs/arcstats |
| 59 | info_provided_to_referring_integrations: |
| 60 | description: "" |
| 61 | overview: |
| 62 | data_collection: |
| 63 | metrics_description: | |
| 64 | This guide describes how Netdata monitors Proxmox VE hypervisors. Netdata provides comprehensive, zero-configuration monitoring of Proxmox hosts, including per-VM and per-container resource utilization, host system metrics, storage health, and cluster components. |
| 65 | |
| 66 | When installed on a Proxmox host, Netdata automatically discovers and monitors all KVM/QEMU virtual machines and LXC containers through Linux cgroups, resolving friendly names for each VM and container. |
| 67 | method_description: | |
| 68 | Netdata uses multiple collectors working together to provide full Proxmox visibility: |
| 69 | |
| 70 | - **cgroups.plugin** monitors per-VM and per-container CPU, memory, disk I/O, and network via Linux cgroups. It automatically resolves VM names from `/etc/pve/qemu-server/<VMID>.conf` and container hostnames from `/etc/pve/lxc/<CTID>.conf`. |
| 71 | - **proc.plugin** monitors host-level system metrics (CPU, memory, network interfaces, disk I/O). |
| 72 | - **apps.plugin** monitors Proxmox-specific process groups (`proxmox-ve`, `libvirt`, `qemu-guest-agent`). |
| 73 | - **go.d/zfspool** monitors ZFS pool health, space utilization, and fragmentation (ZFS is common on Proxmox). |
| 74 | - **go.d/ceph** monitors Ceph cluster health and performance (for Proxmox clusters using Ceph storage). |
| 75 | - **go.d/smartctl** monitors physical disk SMART health data. |
| 76 | - **go.d/sensors** monitors hardware temperature, fan speed, and voltage. |
| 77 | - **ebpf.plugin** provides kernel-level visibility into VM/container syscalls, file I/O, and network activity. |
| 78 | supported_platforms: |
| 79 | include: |
| 80 | - Linux |
| 81 | exclude: [] |
| 82 | multi_instance: false |
| 83 | additional_permissions: |
| 84 | description: "" |
| 85 | default_behavior: |
| 86 | auto_detection: |
| 87 | description: | |
| 88 | When Netdata is installed on a Proxmox VE host, it automatically detects and monitors: |
| 89 | |
| 90 | - All running KVM/QEMU virtual machines |
| 91 | - All running LXC containers |
| 92 | - Host system resources (CPU, memory, network, disks) |
| 93 | - Systemd services (pveproxy, pvedaemon, pvestatd, corosync, etc.) |
| 94 | - ZFS pools (if ZFS is used) |
| 95 | limits: |
| 96 | description: "" |
| 97 | performance_impact: |
| 98 | description: "" |
| 99 | setup: |
| 100 | prerequisites: |
| 101 | list: |
| 102 | - title: Install Netdata on the Proxmox host |
| 103 | description: | |
| 104 | Netdata must be installed directly on the Proxmox VE host (not inside a VM or container) to access cgroups for all VMs and containers. |
| 105 | |
| 106 | ```bash |
| 107 | wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh |
| 108 | ``` |
| 109 | configuration: |
| 110 | file: |
| 111 | name: "" |
| 112 | description: "No configuration is required. All Proxmox monitoring works automatically." |
| 113 | options: |
| 114 | description: "" |
| 115 | folding: |
| 116 | title: "" |
| 117 | enabled: true |
| 118 | list: [] |
| 119 | examples: |
| 120 | folding: |
| 121 | enabled: true |
| 122 | title: "" |
| 123 | list: [] |
| 124 | troubleshooting: |
| 125 | problems: |
| 126 | list: |
| 127 | - name: VM or container names not resolved |
| 128 | description: | |
| 129 | If VMs or containers show raw cgroup paths instead of friendly names, verify that: |
| 130 | |
| 131 | 1. Netdata is installed on the Proxmox host (not inside a VM) |
| 132 | 2. The `/etc/pve/` directory is accessible to the netdata user |
| 133 | 3. The `cgroup-name.sh` script can read VM/container configuration files |
| 134 | - name: Missing ZFS metrics |
| 135 | description: | |
| 136 | If ZFS pool metrics are not showing, ensure the `zfspool` collector is enabled and the `zpool` command is available to the netdata user. |
| 137 | - name: Missing Ceph metrics |
| 138 | description: | |
| 139 | Ceph metrics require the Ceph collector to be configured with the Ceph REST API endpoint. See the Ceph integration page for details. |
| 140 | alerts: [] |
| 141 | metrics: |
| 142 | folding: |
| 143 | title: "" |
| 144 | enabled: false |
| 145 | description: | |
| 146 | This guide does not collect metrics directly. Metrics are collected by the related integrations listed above. See each integration's page for detailed metric documentation. |
| 147 | availability: [] |
| 148 | scopes: [] |