Hypervisor Monitoring
NetXMS can monitor virtualization platforms including VMware vSphere, KVM/libvirt, and Xen through the Virtual Machine Manager subagent (vmgr).
VMware vCenter and ESXi can also be monitored through the vcenter agent extension, which does not use libvirt (see VMware vCenter Agent Extension).
This enables monitoring of hypervisor hosts, virtual machines, and virtualization resource usage.
Overview
Hypervisor monitoring provides:
-
Hypervisor host information (CPU architecture, model, and frequency; memory utilization)
-
Virtual machine inventory and status
-
Per-VM resource allocation and consumption
Virtual Machine Manager Subagent
Connection Configuration
Configuration uses a main [VMGR] section listing host names, with per-host sections providing connection details:
[VMGR]
Host = esx1
Host = kvm1
[VMGR:esx1]
Url = esx://esx1.example.com/
Username = monitor
Password = your_password
[VMGR:kvm1]
Url = qemu+ssh://[email protected]/system
Username = root
Password = your_password
Per-host section parameters:
| Parameter | Description |
|---|---|
|
Libvirt connection URI (platform-specific, see examples below) |
|
Authentication user |
|
Authentication password |
The subagent connects through libvirt, so the hypervisor must be reachable through a libvirt driver:
-
KVM/QEMU (
qemu://,qemu+ssh://,qemu+tcp://) and Xen (xen://,xen+ssh://) URLs connect to the libvirt service on the hypervisor host: the monolithiclibvirtddaemon, or the modularvirtqemud(QEMU) orvirtxend(Xen) daemon. The service must be available there, started or socket-activated, with its local socket (forqemu:///system) or remote transport (for the+sshand+tcpforms) accessible. -
VMware URLs (
esx://,vpx://) connect to the ESXi or vCenter API directly and need no libvirt daemon.
The list of libvirt drivers describes what libvirt can talk to, not what runs on a given host: a KVM-based platform without libvirt cannot be monitored this way (see Unsupported Platforms).
The subagent connects to every configured host once, when the agent starts.
A host that cannot be connected is skipped with the warning Unable to add host connection "<name>" with URL "<url>" in the agent log and is not retried until the agent restarts; if libvirt could not open the connection, its error is logged before this warning.
The subagent also does not reopen a connection that closes later.
If no host can be connected, the subagent does not load and the agent log shows No connections defined, VMGR subagent will not start.
VMware vSphere Monitoring
Connection
The esx:// libvirt driver connects to a standalone ESXi host.
For an ESXi host managed by vCenter, use the vpx:// driver with the full inventory path to the host (vpx://vcenter/datacenter/cluster/esxhost):
[VMGR]
Host = esx1
Host = esx2
[VMGR:esx1]
Url = esx://esx1.example.com/
Username = root
Password = your_password
[VMGR:esx2]
Url = vpx://vcenter.example.com/DC1/Cluster1/esx2.example.com
Username = [email protected]
Password = your_password
| Use a dedicated read-only monitoring account. |
Host Metrics
| Parameter | Description |
|---|---|
|
Host CPU architecture |
|
Number of active CPUs on the host |
|
Maximum number of virtual CPUs libvirt allows per guest |
|
Host CPU model |
|
Host CPU frequency |
|
Total host memory |
|
Free host memory |
|
Libvirt connection type |
|
Libvirt library version |
|
Libvirt connection version |
Virtual Machine Metrics
Per-VM metrics require both the host name and VM/domain name as arguments:
| Parameter | Description |
|---|---|
|
Memory currently used by VM in bytes |
|
VM memory usage as a percentage |
|
Maximum memory available to VM in bytes |
|
Number of virtual CPUs assigned to the VM |
|
VM CPU time in nanoseconds |
Tables
VMGR.VM(host)
Virtual machine list with properties. Key column: NAME.
| Column | Type | Description |
|---|---|---|
|
UINT |
VM numeric ID |
|
STRING |
VM name (key) |
|
STRING |
VM UUID |
|
STRING |
State: |
|
STRING |
OS type/architecture (e.g. |
|
STRING |
Autostart scheduled: |
|
UINT64 |
Current memory in bytes |
|
UINT64 |
Maximum memory in bytes |
|
UINT64 |
Memory usage percentage |
|
UINT |
Number of vCPUs |
|
UINT64 |
CPU time in nanoseconds |
|
STRING |
VM control state: |
|
STRING |
Control state details |
|
UINT |
Time in ms since entering current control state |
|
UINT |
Current VM wall clock time (seconds) |
|
STRING |
Whether VM config is persistent: |
Other Tables
| Table | Description |
|---|---|
|
Host network interface list (column: NAME) |
|
VM disks with source path, type, device type, device name, controller type, address |
|
VM disk controllers with type, index, model |
|
VM network interfaces with MAC address, type, source bridge, NIC model |
|
VM video adapters with type and VRAM |
|
Virtual networks with name, UUID, interfaces, port groups |
|
Storage pools with name, state, capacity, allocation, available bytes |
VMware vCenter Agent Extension
The vcenter agent extension monitors a VMware vCenter server or a standalone ESXi host through the VMware API, without libvirt.
It is a Python script that the agent starts and supervises, and it reports CPU and memory utilization of virtual machines and hosts, datastore usage, and the inventory of virtual machines, datastores, and hosts.
The extension polls the server at startup and then VC_POLL_INTERVAL seconds after each poll, and keeps the results of the last successful poll in memory; the agent answers all metric requests from that cache, so DCI polling does not reach vCenter.
Requirements
-
Python 3 with the
pyvmomipackage on the agent host (pip install pyvmomi) -
The script
nxagent-vcenter.py, which the Linux agent packages install in/usr/share/netxms/extensions/vcenter/(for a source installation,share/netxms/extensions/vcenter/under the installation prefix). The Windows agent installer does not include it: copy it fromsrc/agent/extensions/vcenter/in the source archive of the same version, and giveCommandthe full paths of the Python interpreter and the script, in double quotes if they contain spaces. -
A vCenter or ESXi account with read access, preferably a dedicated monitoring account
Configuration
Add the extension to the agent configuration file (nxagentd.conf):
*extensions/vcenter
Mode = spawn
Command = /usr/bin/python3 /usr/share/netxms/extensions/vcenter/nxagent-vcenter.py
Environment = VC_HOST=vc.example.com
Environment = [email protected]
Environment = VC_PASSWORD=secret
DebugTag = extension.vcenter
For the other keys of an extension section, see Agent Extensions.
The script reads its settings from the environment variables set with Environment:
| Variable | Default | Description |
|---|---|---|
|
— |
vCenter or ESXi host name (required) |
|
— |
User name, for example |
|
— |
Password ( |
|
|
API port |
|
|
Poll interval in seconds |
|
|
Set to |
Messages from the extension go to the agent log under the debug tag set with DebugTag (extension.vcenter if omitted), and appear only at a sufficient debug level for that tag: level 1 shows failed polls (vcenter poll failed: followed by the error), level 5 adds the script’s own output, including startup errors such as a missing pyvmomi package or a missing VC_HOST or VC_USER, and level 6 adds the messages of successful polls.
Metrics, Lists, and Tables
Virtual machines, datastores, and hosts are identified by their managed object ID (MOID), which does not change when the object is renamed; each metric takes the MOID as its argument.
| Metric | Description |
|---|---|
|
Virtual machine name |
|
CPU usage, % of the VM’s maximum CPU capacity |
|
CPU usage (MHz) |
|
Active guest memory, % of configured memory |
|
Active guest memory (bytes) |
|
Power state: |
|
Uptime in seconds |
|
Committed storage (bytes) |
|
Datastore name |
|
Datastore usage (%) |
|
Free space (bytes) |
|
Capacity (bytes) |
|
Host name |
|
CPU usage, % of total host CPU capacity |
|
CPU usage (MHz) |
|
Memory usage, % of host memory |
|
Memory usage (bytes) |
|
Number of virtual machines on the host, including powered-off ones |
|
Host connection state, for example |
The lists VMware.VMList, VMware.DatastoreList, and VMware.HostList return the MOIDs for instance discovery, and the tables VMware.VMs, VMware.Datastores, and VMware.Hosts provide inventories with selected utilization and state columns.
Template
The server includes the template VMware vCenter / ESXi Monitoring (file vmware_vcenter_esxi.json in the server’s share/templates directory, for example /usr/share/netxms/templates).
The server imports it on startup as controlled by the server configuration variable Server.ImportConfigurationOnStartup; if that variable is set to Never, import the file manually with .
After import, the template is in the template group VMware.
The template is not applied automatically: apply it to the node whose agent runs the extension.
It creates DCIs for each virtual machine, datastore, and host through instance discovery on the three lists, with an instance filter that shows the object name in DCI descriptions while keeping the MOID as the instance.
Its thresholds generate the VMW_* events (for example VMW_VM_CPU_HIGH and VMW_DATASTORE_FULL_CRITICAL), and the configuration file adds EPP rules that create an alarm when a threshold is reached and terminate it when the value returns to normal.
KVM/libvirt Monitoring
Connection
Connect to KVM hosts via libvirt:
[VMGR]
Host = kvm1
Host = local
[VMGR:kvm1]
Url = qemu+ssh://[email protected]/system
Username = root
[VMGR:local]
Url = qemu:///system
Connection URL formats:
-
qemu:///system— local connection -
qemu+ssh://user@host/system— SSH-tunneled connection -
qemu+tcp://host/system— TCP connection
Xen Monitoring
Xen can be monitored in two ways: via libvirt (using the vmgr subagent) or directly using the Xen-specific subagent (xen).
Via libvirt (vmgr)
The libvirt xen:// driver connects to the libxl stack on a Xen dom0 host.
It does not work with Citrix XenServer / Citrix Hypervisor.
[VMGR]
Host = xen1
[VMGR:xen1]
Url = xen+ssh://[email protected]/system
Username = root
Password = your_password
This provides the same VMGR.* metrics as for KVM and VMware.
Direct Xen Subagent
The xen subagent connects directly to the local Xen hypervisor via libxl.
It must run on the Xen dom0. No configuration is required beyond loading the subagent.
SubAgent = xen
Host Metrics
| Parameter | Description |
|---|---|
|
Xen hypervisor version string |
|
Number of CPU cores |
|
Number of logical CPUs |
|
Number of physical CPUs |
|
Currently online CPUs |
|
CPU frequency in KHz |
|
Host CPU utilization, current snapshot (%) |
|
Host CPU utilization, 1-minute average (%) |
|
Host CPU utilization, 5-minute average (%) |
|
Host CPU utilization, 15-minute average (%) |
|
Total host memory in bytes |
|
Free host memory in bytes |
|
Free memory percentage |
|
Used host memory in bytes |
|
Used memory percentage |
|
Outstanding claimed memory in bytes |
|
Outstanding claimed memory percentage |
|
Memory being scrubbed, in bytes |
|
Memory being scrubbed, percentage |
Domain (VM) Metrics
All domain metrics accept the domain name or numeric ID as the argument.
| Parameter | Description |
|---|---|
|
Domain current CPU utilization (%) |
|
Domain 1-minute average CPU utilization (%) |
|
Domain 5-minute average CPU utilization (%) |
|
Domain 15-minute average CPU utilization (%) |
|
1 if domain exists, 0 otherwise |
|
1 if domain is running or blocked |
|
1 if domain is paused |
|
Domain state: RUNNING, BLOCKED, PAUSED, SHUTDOWN, DYING, MISSING, UNKNOWN |
|
Total bytes received across all domain vifs |
|
Total bytes transmitted |
|
Total packets received |
|
Total packets transmitted |
Xen Tables
XEN.Domains — domain table with ID, name, state (single string column), memory (current/shared/paged/outstanding/max), vCPU count, CPU time, CPU usage (current and 1-minute average), and network I/O.
XEN.Net.DomainInterfaces — all domain network interfaces with vif name, domain ID/name, network ID, bridge, MAC address, IP, NIC model, and per-interface byte/packet counters.
Unsupported Platforms
Proxmox VE manages its virtual machines with QEMU directly, not through libvirt, so the vmgr subagent cannot monitor them.
On a standard Proxmox VE installation, a qemu:///system connection fails with an error such as Failed to connect socket to '/var/run/libvirt/libvirt-sock': No such file or directory.
The host itself can be monitored with the agent like any Linux server, and agents installed in the guests report normally; only the host-level virtual machine inventory and per-VM metrics of the vmgr subagent are not available.
Guest Agent Integration
For in-depth guest OS monitoring, install the NetXMS agent inside virtual machines. This provides:
-
Full OS-level metrics (same as OS monitoring)
-
Application-level monitoring
-
Log monitoring
-
File system monitoring
The VM subagent metrics complement guest agent monitoring by providing the hypervisor-level view (allocated resources, host-side performance).
For nodes that run as virtual machines, the server detects the hypervisor type and hypervisor information during the configuration poll and shows them in the node properties. Virtual machines are not automatically linked to their hypervisor hosts in the object tree.
Troubleshooting
vCenter Agent Extension Issues
- The extension is not connected (
Agent.Extension.IsConnected(vcenter)returns 0) -
The script exits at startup. Set the debug level of the extension’s tag to 5 and check the agent log for the reason, for example a missing
pyvmomipackage or a missingVC_HOSTorVC_USER. - The extension is connected, but the lists are empty or the values do not change
-
The connection to the agent says nothing about the connection to vCenter. A failed poll is logged at debug level 1 as
vcenter poll failed:with the error, for example a TLS, authentication, or network error. The extension tries again at the next poll interval and keeps serving the data of the last successful poll, without a time limit, so the values can be stale; before the first successful poll the lists and tables are empty.
VMware Connection Issues (libvirt)
-
Verify the vCenter/ESXi URL and credentials
-
Check that the monitoring account has read-only permissions
-
Verify network access from the agent host to the vCenter/ESXi management interface
-
Check agent log for libvirt errors, logged under the
vmgrdebug tag
KVM/libvirt Connection Issues
-
Verify SSH key authentication is configured (for SSH-tunneled connections)
-
Check libvirt is running on the KVM host
-
Verify the monitoring user has permissions to query libvirt
-
Test connection with
virsh -c <url> list -
Restart the agent after fixing the connection: a host that failed to connect at startup is not retried