Hypervisor Monitoring

NetXMS can monitor virtualization platforms including VMware vSphere, KVM/libvirt, and Xen through the Virtual Machine Manager subagent (vmgr.nsm). 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

Loading the Subagent

SubAgent = vmgr.nsm

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

Url

Libvirt connection URI (platform-specific, see examples below)

Username

Authentication user

Password

Authentication password

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

VMGR.Host.CPU.Arch(host)

Host CPU architecture

VMGR.Host.CPU.MaxCount(host)

Maximum number of virtual CPUs libvirt allows per guest

VMGR.Host.CPU.Model(host)

Host CPU model

VMGR.Host.CPU.Frequency(host)

Host CPU frequency

VMGR.Host.MemorySize(host)

Total host memory

VMGR.Host.FreeMemory(host)

Free host memory

VMGR.Host.ConnectionType(host)

Libvirt connection type

VMGR.Host.LibraryVersion(host)

Libvirt library version

VMGR.Host.ConnectionVersion(host)

Libvirt connection version

Virtual Machine Metrics

Per-VM metrics require both the host name and VM/domain name as arguments:

Parameter Description

VMGR.VM.Memory.Used(host,vmName)

Memory currently used by VM in bytes

VMGR.VM.Memory.UsedPrec(host,vmName)

VM memory usage as a percentage

VMGR.VM.Memory.Max(host,vmName)

Maximum memory available to VM in bytes

VMGR.VM.CPU.Time(host,vmName)

VM CPU time in nanoseconds

Tables

VMGR.VM(host)

Virtual machine list with properties. Key column: NAME.

Column Type Description

ID

UINT

VM numeric ID

NAME

STRING

VM name (key)

UUID

STRING

VM UUID

STATE

STRING

State: no state, Running, blocked on resource, paused by user, shut down, shut off, crashed, suspended by guest power management, or Unknown if the state cannot be determined

OS

STRING

OS type/architecture (e.g. hvm/x86_64)

AUTOSTART

STRING

Autostart scheduled: Yes, No, or Unknown

MEMORY

UINT64

Current memory in bytes

MAX_MEMORY

UINT64

Maximum memory in bytes

MEMORY_PREC

UINT64

Memory usage percentage

VIRTUAL_CPU_COUNT

UINT

Number of vCPUs

VIRTUAL_CPU_TIME

UINT64

CPU time in nanoseconds

CONTROL_STATE

STRING

VM control state: Ready to accept commands, Background job is running, Occupied by a running command, Unusable

STATE_DETAILS

STRING

Control state details

CONTROL_STATE_DURATION

UINT

Time in ms since entering current control state

TIME

UINT

Current VM wall clock time (seconds)

IS_PERSISTENT

STRING

Whether VM config is persistent: Yes, No, or Unknown

Other Tables

Table Description

VMGR.InterfaceList(host)

Host network interface list (column: NAME)

VMGR.VMDisks(host,vmName)

VM disks with source path, type, device type, device name, controller type, address

VMGR.VMController(host,vmName)

VM disk controllers with type, index, model

VMGR.VMInterface(host,vmName)

VM network interfaces with MAC address, type, source bridge, NIC model

VMGR.VMVideo(host,vmName)

VM video adapters with type and VRAM

VMGR.Networks(host)

Virtual networks with name, UUID, interfaces, port groups

VMGR.Storages(host)

Storage pools with name, state, capacity, allocation, available bytes

Lists

List Description

VMGR.VMHost

Configured hypervisor host names

VMGR.VMList(host)

Virtual machine names on a specific host

The VMGR.VM(host) table supports instance discovery for automatic per-VM DCI creation.

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

Available Metrics

KVM/libvirt monitoring provides the same VMGR.Host. and VMGR.VM. metrics as listed above.

Xen Monitoring

Xen can be monitored in two ways: via libvirt (using vmgr.nsm) or directly using the Xen-specific subagent (xen.nsm).

Via libvirt (vmgr.nsm)

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 (xen.nsm)

The xen.nsm 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.nsm

Host Metrics

Parameter Description

XEN.Host.Version

Xen hypervisor version string

XEN.Host.CPU.Cores

Number of CPU cores

XEN.Host.CPU.LogicalCount

Number of logical CPUs

XEN.Host.CPU.PhysicalCount

Number of physical CPUs

XEN.Host.CPU.Online

Currently online CPUs

XEN.Host.CPU.Frequency

CPU frequency in KHz

XEN.Host.CPU.CurrentUsage

Host CPU utilization, current snapshot (%)

XEN.Host.CPU.Usage

Host CPU utilization, 1-minute average (%)

XEN.Host.CPU.Usage5

Host CPU utilization, 5-minute average (%)

XEN.Host.CPU.Usage15

Host CPU utilization, 15-minute average (%)

XEN.Host.Memory.Total

Total host memory in bytes

XEN.Host.Memory.Free

Free host memory in bytes

XEN.Host.Memory.FreePerc

Free memory percentage

XEN.Host.Memory.Used

Used host memory in bytes

XEN.Host.Memory.UsedPerc

Used memory percentage

XEN.Host.Memory.Outstanding

Outstanding claimed memory in bytes

XEN.Host.Memory.OutstandingPerc

Outstanding claimed memory percentage

XEN.Host.Memory.Scrub

Memory being scrubbed, in bytes

XEN.Host.Memory.ScrubPerc

Memory being scrubbed, percentage

Domain (VM) Metrics

All domain metrics accept the domain name or numeric ID as the argument.

Parameter Description

XEN.Domain.CPU.CurrentUsage(dom)

Domain current CPU utilization (%)

XEN.Domain.CPU.Usage(dom)

Domain 1-minute average CPU utilization (%)

XEN.Domain.CPU.Usage5(dom)

Domain 5-minute average CPU utilization (%)

XEN.Domain.CPU.Usage15(dom)

Domain 15-minute average CPU utilization (%)

XEN.Domain.IsExist(dom)

1 if domain exists, 0 otherwise

XEN.Domain.IsOperational(dom)

1 if domain is running or blocked

XEN.Domain.IsPaused(dom)

1 if domain is paused

XEN.Domain.State(dom)

Domain state: RUNNING, BLOCKED, PAUSED, SHUTDOWN, DYING, MISSING, UNKNOWN

XEN.Domain.Net.RxBytes(dom)

Total bytes received across all domain vifs

XEN.Domain.Net.TxBytes(dom)

Total bytes transmitted

XEN.Domain.Net.RxPackets(dom)

Total packets received

XEN.Domain.Net.TxPackets(dom)

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.

Xen Lists

List Description

XEN.Domains

All domain names (including dom0)

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

VMware Connection Issues

  1. Verify the vCenter/ESXi URL and credentials

  2. Check that the monitoring account has read-only permissions

  3. Verify network access from the agent host to the vCenter/ESXi management interface

  4. Check agent log for libvirt errors, logged under the vmgr debug tag

KVM/libvirt Connection Issues

  1. Verify SSH key authentication is configured (for SSH-tunneled connections)

  2. Check libvirt is running on the KVM host

  3. Verify the monitoring user has permissions to query libvirt

  4. Test connection with virsh -c <url> list