VMware vCenter Server

Plugin: go.d.plugin Module: vsphere

Overview

Monitors vSphere resources from vCenter servers.

Includes hosts, VMs, datastores, clusters, resource pools, and inventory counts.

Use the vcsa collector for vCenter Server Appliance health.

Use the snmp collector with the vmware-esx profile for ESXi hardware, HBA, and environment sensors.

Those surfaces are intentionally not duplicated here by default.

Warning: The vsphere collector cannot re-login and continue collecting metrics after a vCenter reboot. go.d.plugin needs to be restarted.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

This integration doesn't support auto-detection.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default update_every is 20 seconds, and it doesn't make sense to decrease the value. VMware real-time statistics are generated at the 20-second specificity.

Note: Datastore and cluster performance metrics use 300-second (5-minute) historical intervals because VMware does not support real-time statistics for these entity types. Datastore capacity/status, cluster properties, and resource pool statistics are updated every collection cycle. Host and VM metrics use real-time 20-second intervals.

It is likely that 20 seconds is not enough for big installations and the value should be tuned.

To size a job, run the collector in debug mode and compare the discovery and collection timing lines. Discovery runs in a separate goroutine, while collection timing must stay comfortably below update_every.

Useful log lines include:

• discovering : discovered ... the whole process took ...
• scraping : scraped metrics for ... hosts, process took ...
• scraping : scraped metrics for ... vms, process took ...
• metrics collected, process took ...

Adjust update_every and timeout based on those timings and on the number of enabled optional surfaces.

Setup

You can configure the vsphere collector in two ways:

Method	Best for	How to
UI	Fast setup without editing files	Go to Nodes → Configure this node → Collectors → Jobs, search for vsphere, then click + to add a job.
File	If you prefer configuring via file, or need to automate deployments (e.g., with Ansible)	Edit go.d/vsphere.conf and add a job.

important

UI configuration requires paid Netdata Cloud plan.

Prerequisites

vCenter read-only access

Configure a vCenter account that can read inventory objects, properties, and performance counters for the datacenters, clusters, ESXi hosts, VMs, datastores, and resource pools selected by the include filters.

Optional vSphere metadata permissions

tag_categories requires access to the vSphere Automation/CIS tagging APIs for the selected categories. custom_attributes requires access to custom field definitions and values for the selected inventory objects.

Optional datastore cluster, vSAN, and network data

collect_datastore_clusters requires read access to StoragePod objects. collect_vsan requires vSAN Management API access and the vSAN Performance Service on the target clusters. collect_network_topology requires read access to Network and Distributed Virtual Port Group inventory objects.

Configuration

Options

The following options can be defined globally: update_every, autodetection_retry.

Config options

Group	Option	Description	Default	Required
Collection	update_every	Data collection interval (seconds).	20	no
	autodetection_retry	Autodetection retry interval (seconds).	60	no
Target	url	Target endpoint URL.	https://vcenter.local	yes
	timeout	HTTP request timeout (seconds).	20	no
Discovery	discovery_interval	Hosts, VMs, datastores, clusters, and resource pools discovery interval (seconds).	300	no
Labels	tag_categories	vSphere tag category allowlist.		no
	custom_attributes	vSphere custom attribute allowlist.		no
High Cardinality	collect_datastore_clusters	Collect datastore cluster capacity and Storage DRS status.	no	no
	datastore_cluster_include	Datastore cluster selector.	/*	no
	collect_vsan	Collect vSAN metrics.	no	no
	vsan_cluster_include	vSAN cluster selector.	/*	no
	vsan_host_include	vSAN host selector.	/*	no
	vsan_vm_include	vSAN VM selector.	/*	no
Collection	collect_network_topology	Discover networks for the vSphere Topology function.	no	no
Filters	host_include	Hosts selector (filter).	/*	no
	vm_include	VM selector (filter).	/*	no
	datastore_include	Datastore selector (filter).	/*	no
	cluster_include	Cluster selector (filter). Resource pools follow their owning cluster.	/*	no
HTTP Auth	username	Username for Basic HTTP authentication.		yes
	password	Password for Basic HTTP authentication.		yes
TLS	tls_skip_verify	Skip TLS certificate and hostname verification (insecure).	no	no
	tls_ca	Path to CA bundle used to validate the server certificate.		no
	tls_cert	Path to client TLS certificate (for mTLS).		no
	tls_key	Path to client TLS private key (for mTLS).		no
Virtual Node	vnode	Associates this data collection job with a Virtual Node.		no

tag_categories

Disabled by default because vSphere tags are user-defined metadata and can expose internal names, ownership, business unit, or environment details. Each list item is one glob pattern matching vSphere tag category names, so names with spaces are supported. Use * only when every tag category is intentional.

Matching categories are exposed as labels named vsphere_tag_<sanitized_category>. When a resource has multiple tags in the same category, values are sorted and joined with the pipe character.

tag_categories:
  - "Environment"
  - "Business Unit"

custom_attributes

Disabled by default because vSphere custom attributes are user-defined metadata and can expose internal names, ownership, business unit, operational data, or secrets stored by administrators. Custom attribute values are sent verbatim as labels. Each list item is one glob pattern matching custom attribute names, so names with spaces are supported. Use * only when every custom attribute is intentional and none of the matched values contain secrets.

Matching attributes are exposed as labels named vsphere_custom_attribute_<sanitized_name>.

custom_attributes:
  - "Owner"
  - "Cost Center"

collect_datastore_clusters

Disabled by default because it adds a separate vSphere resource class (StoragePod) to the collector output. When enabled, the collector emits aggregate datastore-cluster capacity, utilization, and Storage DRS status.

datastore_cluster_include

Applies only when collect_datastore_clusters is enabled. Values use Netdata simple patterns and match /Datacenter/DatastoreCluster, the datastore-cluster name, or the vSphere managed object ID. Matching datastore clusters are included in metrics, labels, cached discovery state, and topology function output.

datastore_cluster_include:
  - "/*"

collect_vsan

Disabled by default because it uses the vSAN Management API and vSAN Performance Service, and adds extra vCenter queries. When enabled, it emits vSAN cluster capacity, vSAN cluster health, and vSAN cluster, host, and VM performance metrics for discovered vSAN-enabled clusters. Use the vSAN selectors below to choose the concrete vSAN performance entity refs queried. vSAN events are not collected by this option.

vsan_cluster_include

Applies only when collect_vsan is enabled. Values use Netdata simple patterns and match /Datacenter/Cluster, the cluster name, the vSphere managed object ID, or vsan_uuid:<uuid>.

vsan_cluster_include:
  - "/*"
  - "vsan_uuid:52b..."

vsan_host_include

Applies only when collect_vsan is enabled. Values use Netdata simple patterns and match /Datacenter/Cluster/Host, the host name, the vSphere managed object ID, or vsan_node_uuid:<uuid>.

vsan_host_include:
  - "/*"
  - "vsan_node_uuid:52b..."

vsan_vm_include

Applies only when collect_vsan is enabled. Values use Netdata simple patterns and match /Datacenter/Cluster/Host/VM, the VM name, the vSphere managed object ID, or instance_uuid:<uuid>.

vsan_vm_include:
  - "/*"
  - "instance_uuid:52b..."

collect_network_topology

Disabled by default to avoid extra vCenter discovery calls for existing users. When enabled, the collector discovers vSphere Network and Distributed Virtual Port Group objects and includes their cached accessibility/status and host/VM relationships in the vSphere Topology function. It does not create charts or metrics.

host_include

Metrics of hosts matching the selector will be collected.

• Include pattern syntax: "/Datacenter pattern/Cluster pattern/Host pattern".

• Match pattern syntax: simple patterns.

• Syntax:

  host_include:
    - '/DC1/*'           # all hosts from datacenter DC1
    - '/DC2/*/!Host2 *'  # all hosts from datacenter DC2 except HOST2
    - '/DC3/Cluster3/*'  # all hosts from DC3, cluster Cluster3

vm_include

Metrics of VMs matching the selector will be collected.

• Include pattern syntax: "/Datacenter pattern/Cluster pattern/Host pattern/VM pattern".

• Match pattern syntax: simple patterns.

• Syntax:

  vm_include:
    - '/DC1/*'           # all VMs from datacenter DC1
    - '/DC2/*/*/!VM2 *'  # all VMs from DC2 except VM2
    - '/DC3/Cluster3/*'  # all VMs from DC3, cluster Cluster3

datastore_include

Metrics of datastores matching the selector will be collected.

• Include pattern syntax: "/Datacenter pattern/Datastore pattern".

• Match pattern syntax: simple patterns.

• Syntax:

  datastore_include:
    - '/DC1/*'           # all datastores from datacenter DC1
    - '/DC2/!DS2 *'      # all datastores from DC2 except DS2

cluster_include

Metrics of clusters and their resource pools matching the selector will be collected.

• Include pattern syntax: "/Datacenter pattern/Cluster pattern".

• Match pattern syntax: simple patterns.

• Syntax:

  cluster_include:
    - '/DC1/*'           # all clusters from datacenter DC1
    - '/DC2/!Cluster2 *' # all clusters from DC2 except Cluster2

via UI

Configure the vsphere collector from the Netdata web interface:

1. Go to Nodes.
2. Select the node where you want the vsphere data-collection job to run and click the ⚙ (Configure this node). That node will run the data collection.
3. The Collectors → Jobs view opens by default.
4. In the Search box, type vsphere (or scroll the list) to locate the vsphere collector.
5. Click the + next to the vsphere collector to add a new job.
6. Fill in the job fields, then click Test to verify the configuration and Submit to save.
   • Test runs the job with the provided settings and shows whether data can be collected.
   • If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/vsphere.conf.

The file format is YAML. Generally, the structure is:

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/vsphere.conf

Examples

Basic

A basic example configuration.

jobs:
  - name     : vcenter1
    url      : https://203.0.113.1
    username : [email protected]
    password : somepassword

Multi-instance

Note: When you define multiple jobs, their names must be unique.

Collecting metrics from local and remote instances.

Config

jobs:
  - name     : vcenter1
    url      : https://203.0.113.1
    username : [email protected]
    password : somepassword

  - name     : vcenter2
    url      : https://203.0.113.10
    username : [email protected]
    password : somepassword

Alerts

The following alerts are available:

Alert name	On metric	Description
vsphere_vm_cpu_utilization	vsphere.vm_cpu_utilization	Virtual Machine CPU utilization
vsphere_vm_mem_utilization	vsphere.vm_mem_utilization	Virtual Machine memory utilization
vsphere_vm_snapshot_chain_depth	vsphere.vm_snapshot_max_chain_depth	Virtual Machine snapshot maximum chain depth
vsphere_vm_snapshot_age	vsphere.vm_snapshot_max_age	Virtual Machine oldest snapshot age
vsphere_host_cpu_utilization	vsphere.host_cpu_utilization	ESXi Host CPU utilization
vsphere_host_mem_utilization	vsphere.host_mem_utilization	ESXi Host memory utilization

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per inventory

These metrics refer to the discovered vSphere inventory for this collector job.

Labels:

Label	Description
id	Static inventory instance ID

Metrics:

Metric	Description	Dimensions	Unit
vsphere.inventory_objects	vSphere inventory object count after include filters are applied	datacenters, folders, clusters, hosts, vms, datastores, resource_pools	objects

Per virtual machine

These metrics refer to the Virtual Machine.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vm	Virtual Machine name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.vm_cpu_utilization	Virtual Machine CPU utilization	used	percentage
vsphere.vm_mem_utilization	Virtual Machine memory utilization	used	percentage
vsphere.vm_mem_usage	Virtual Machine memory usage	granted, consumed, active, shared	KiB
vsphere.vm_mem_swap_usage	Virtual Machine VMKernel memory swap usage	swapped	KiB
vsphere.vm_mem_swap_io	Virtual Machine VMKernel memory swap IO	in, out	KiB/s
vsphere.vm_disk_io	Virtual Machine disk IO	read, write	KiB/s
vsphere.vm_disk_max_latency	Virtual Machine disk max latency	latency	milliseconds
vsphere.vm_net_traffic	Virtual Machine network traffic	received, sent	KiB/s
vsphere.vm_net_packets	Virtual Machine network packets	received, sent	packets
vsphere.vm_net_drops	Virtual Machine network dropped packets	received, sent	drops
vsphere.vm_overall_status	Virtual Machine overall alarm status	green, red, yellow, gray	status
vsphere.vm_power_state	Virtual Machine power state	powered_on, powered_off, suspended	status
vsphere.vm_connection_state	Virtual Machine connection state	connected, disconnected, orphaned, inaccessible, invalid	status
vsphere.vm_tools_running_status	Virtual Machine VMware Tools running status	running, not_running, executing_scripts, unknown	status
vsphere.vm_tools_version_status	Virtual Machine VMware Tools version status	current, need_upgrade, not_installed, unmanaged, too_old, supported_old, supported_new, too_new, blacklisted, unknown	status
vsphere.vm_consolidation_needed	Virtual Machine disk consolidation status	needed, not_needed	status
vsphere.vm_system_uptime	Virtual Machine system uptime	uptime	seconds
vsphere.vm_config_cpu	Virtual Machine configured CPU	vcpus	vCPUs
vsphere.vm_config_memory	Virtual Machine configured memory	memory	MiB
vsphere.vm_config_devices	Virtual Machine configured devices	disks, nics	devices
vsphere.vm_storage_usage	Virtual Machine storage usage	committed, uncommitted, unshared	bytes
vsphere.vm_snapshot_count	Virtual Machine snapshot count	count	snapshots
vsphere.vm_snapshot_max_age	Virtual Machine oldest snapshot age; zero means no snapshots	age	seconds
vsphere.vm_snapshot_max_chain_depth	Virtual Machine maximum snapshot chain depth; zero means no snapshots	depth	snapshots

Per virtual machine power

These aggregate metrics refer to VM power and energy and are collected for discovered powered-on VMs when vSphere exposes the corresponding power counters.

Labels:

Label	Description
id	vSphere managed object reference ID of the VM
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vm	Virtual Machine name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.vm_power_usage	Virtual Machine power usage	power	watts
vsphere.vm_energy_usage	Virtual Machine energy usage	energy	joules

Per vSAN virtual machine

These optional metrics refer to VM vSAN performance and are collected only when collect_vsan is enabled.

Labels:

Label	Description
id	vSphere managed object reference ID of the VM
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vm	Virtual Machine name
vm_instance_uuid	VM instance UUID used by vSAN performance entity references
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.vsan_vm_operations	vSAN Virtual Machine operations	read, write	operations/s
vsphere.vsan_vm_throughput	vSAN Virtual Machine throughput	read, write	bytes/s
vsphere.vsan_vm_latency	vSAN Virtual Machine latency	read, write	microseconds

Per host power

These aggregate metrics refer to ESXi host power, energy, and power capacity and are collected for discovered powered-on hosts when vSphere exposes the corresponding power counters.

Labels:

Label	Description
id	vSphere managed object reference ID of the host
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.host_power_usage	ESXi Host power usage	power, cap	watts
vsphere.host_power_capacity_usage	ESXi Host power capacity usage	used, usable, idle, system, vm	watts
vsphere.host_power_capacity_utilization	ESXi Host power capacity utilization	used	percentage
vsphere.host_energy_usage	ESXi Host energy usage	energy	joules

Per vSAN host

These optional metrics refer to ESXi host vSAN performance and are collected only when collect_vsan is enabled.

Labels:

Label	Description
id	vSphere managed object reference ID of the host
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vsan_node_uuid	vSAN host node UUID used by vSAN performance entity references
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.vsan_host_operations	vSAN Host operations	read, write	operations/s
vsphere.vsan_host_throughput	vSAN Host throughput	read, write	bytes/s
vsphere.vsan_host_latency	vSAN Host latency	read, write	microseconds
vsphere.vsan_host_congestions	vSAN Host congestion events	congestions	congestions/s
vsphere.vsan_host_cache_hit_rate	vSAN Host client cache hit rate	hit_rate	percentage

Per host

These metrics refer to the ESXi host.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
cluster	Cluster name
host	Host name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.host_cpu_utilization	ESXi Host CPU utilization	used	percentage
vsphere.host_mem_utilization	ESXi Host memory utilization	used	percentage
vsphere.host_mem_usage	ESXi Host memory usage	granted, consumed, active, shared, sharedcommon	KiB
vsphere.host_mem_swap_io	ESXi Host VMKernel memory swap IO	in, out	KiB/s
vsphere.host_disk_io	ESXi Host disk IO	read, write	KiB/s
vsphere.host_disk_max_latency	ESXi Host disk max latency	latency	milliseconds
vsphere.host_net_traffic	ESXi Host network traffic	received, sent	KiB/s
vsphere.host_net_packets	ESXi Host network packets	received, sent	packets
vsphere.host_net_drops	ESXi Host network drops	received, sent	drops
vsphere.host_net_errors	ESXi Host network errors	received, sent	errors
vsphere.host_overall_status	ESXi Host overall alarm status	green, red, yellow, gray	status
vsphere.host_power_state	ESXi Host power state	powered_on, powered_off, standby, unknown	status
vsphere.host_connection_state	ESXi Host connection state	connected, not_responding, disconnected	status
vsphere.host_maintenance_status	ESXi Host maintenance status	normal, in_maintenance	status
vsphere.host_system_uptime	ESXi Host system uptime	uptime	seconds

Per datastore

These metrics refer to the Datastore.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
datastore	Datastore name
type	Datastore type (VMFS, NFS, NFS41, vsan, VVOL, PMEM)
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.datastore_disk_io	Datastore disk IO	read, write	KiB/s
vsphere.datastore_disk_iops	Datastore disk IOPS	reads, writes	operations/s
vsphere.datastore_disk_latency	Datastore disk latency	read, write	milliseconds
vsphere.datastore_space_utilization	Datastore space utilization	used	percentage
vsphere.datastore_space_usage	Datastore space usage; capacity, free, used, and uncommitted are zero when the datastore is inaccessible	capacity, free, used, uncommitted	bytes
vsphere.datastore_overall_status	Datastore overall alarm status	green, red, yellow, gray	status
vsphere.datastore_accessibility_status	Datastore accessibility status	accessible, inaccessible	status
vsphere.datastore_maintenance_status	Datastore maintenance mode status	normal, entering_maintenance, in_maintenance, unknown	status
vsphere.datastore_multiple_host_access	Datastore multi-host access status	enabled, disabled, unknown	status

Per datastore cluster

These optional metrics refer to datastore clusters (StoragePod objects) and are collected only when collect_datastore_clusters is enabled.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
datastore_cluster	Datastore cluster name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.datastore_cluster_space_utilization	Datastore Cluster space utilization	used	percentage
vsphere.datastore_cluster_space_usage	Datastore Cluster space usage	capacity, free, used	bytes
vsphere.datastore_cluster_storage_drs_status	Datastore Cluster Storage DRS status	enabled, disabled	status
vsphere.datastore_cluster_overall_status	Datastore Cluster overall status	green, red, yellow, gray	status

Per vSAN cluster

These optional metrics refer to vSAN cluster capacity, health, and performance and are collected only when collect_vsan is enabled.

Labels:

Label	Description
id	vSphere managed object reference ID of the cluster
datacenter	Datacenter name
cluster	Cluster name
vsan_uuid	vSAN cluster UUID used by vSAN performance entity references
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.vsan_cluster_space_usage	vSAN Cluster space usage	used, free, total	bytes
vsphere.vsan_cluster_space_utilization	vSAN Cluster space utilization	used	percentage
vsphere.vsan_cluster_health_status	vSAN Cluster health status	green, yellow, red, unknown	status
vsphere.vsan_cluster_operations	vSAN Cluster operations	read, write	operations/s
vsphere.vsan_cluster_throughput	vSAN Cluster throughput	read, write	bytes/s
vsphere.vsan_cluster_latency	vSAN Cluster latency	read, write	microseconds
vsphere.vsan_cluster_congestions	vSAN Cluster congestion events	congestions	congestions/s

Per cluster

These metrics refer to the vSphere Cluster.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
cluster	Cluster name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.cluster_hosts	Cluster host count	total, effective	hosts
vsphere.cluster_cpu_capacity	Cluster CPU capacity	total, effective	MHz
vsphere.cluster_mem_capacity	Cluster memory capacity	total, effective	bytes
vsphere.cluster_cpu_topology	Cluster CPU topology	cores, threads	count
vsphere.cluster_drs_config	Cluster DRS enabled	enabled	status
vsphere.cluster_drs_mode	Cluster DRS automation mode	manual, partially_automated, fully_automated, unknown	status
vsphere.cluster_drs_vmotion_rate	Cluster DRS vMotion recommendation threshold	rate	level
vsphere.cluster_ha_config	Cluster HA configuration	enabled, admission_control	status
vsphere.cluster_ha_host_monitoring	Cluster HA host monitoring	enabled, disabled, unknown	status
vsphere.cluster_ha_vm_monitoring	Cluster HA VM monitoring	disabled, vm_monitoring_only, vm_and_app_monitoring, unknown	status
vsphere.cluster_ha_vm_component_protection	Cluster HA VM component protection	enabled, disabled, unknown	status
vsphere.cluster_overall_status	Cluster overall alarm status	green, red, yellow, gray	status
vsphere.cluster_vmotions	Cluster cumulative vMotion count	vmotions	migrations
vsphere.cluster_drs_score	Cluster DRS score	score	percentage
vsphere.cluster_drs_balance	Cluster DRS load balance	current, target	score
vsphere.cluster_vm_count	Cluster VM count	total, powered_off	VMs
vsphere.cluster_usage_cpu	Cluster DRS CPU usage summary	demand, entitled, reserved	MHz
vsphere.cluster_usage_mem	Cluster DRS memory usage summary	demand, entitled, reserved	MB
vsphere.cluster_cpu_utilization	Cluster CPU utilization	used	percentage
vsphere.cluster_cpu_usage	Cluster CPU usage	used, total	MHz
vsphere.cluster_mem_utilization	Cluster memory utilization	used	percentage
vsphere.cluster_mem_usage	Cluster memory usage	consumed, active, granted, shared, overhead, swap_used	KiB
vsphere.cluster_services_fairness	Cluster DRS resource distribution fairness	cpu, memory	score
vsphere.cluster_services_effective_cpu	Cluster effective CPU capacity	effective_cpu	MHz
vsphere.cluster_services_effective_mem	Cluster effective memory capacity	effective_mem	MB
vsphere.cluster_services_failover	Cluster HA failover capacity	failures_tolerable	failures
vsphere.cluster_vm_migrations	Cluster VM migration operations	vmotion, svmotion, xvmotion	operations
vsphere.cluster_vm_lifecycle	Cluster VM lifecycle operations	poweron, poweroff, create, destroy, clone, deploy	operations
vsphere.cluster_vm_management	Cluster VM management operations	reconfigure, reset, suspend, register, unregister	operations
vsphere.cluster_vm_guest_ops	Cluster VM guest operations	reboot, shutdown, standby	operations
vsphere.cluster_vm_cold_migrations	Cluster VM cold migration operations	change_ds, change_host, change_host_ds	operations

Per resource pool

These metrics refer to the vSphere Resource Pool.

Labels:

Label	Description
id	vSphere managed object reference ID
datacenter	Datacenter name
cluster	Cluster name
resource_pool	Resource Pool name
vsphere_tag_<category>	vSphere tag label; present only for categories matched by tag_categories; category names are sanitized for label keys and multiple tags in one category are sorted and joined with the pipe character
vsphere_custom_attribute_<name>	vSphere custom attribute label; present only for attributes matched by custom_attributes; attribute names are sanitized for label keys

Metrics:

Metric	Description	Dimensions	Unit
vsphere.resource_pool_cpu_usage	Resource Pool CPU usage vs demand	usage, demand	MHz
vsphere.resource_pool_cpu_entitlement	Resource Pool CPU entitlement	distributed	MHz
vsphere.resource_pool_cpu_allocation	Resource Pool CPU allocation	reservation_used, unreserved_for_vm, max_usage	MHz
vsphere.resource_pool_mem_usage	Resource Pool memory usage	host, guest	MB
vsphere.resource_pool_mem_entitlement	Resource Pool memory entitlement	distributed	MB
vsphere.resource_pool_mem_allocation	Resource Pool memory allocation	reservation_used, unreserved_for_vm, max_usage	bytes
vsphere.resource_pool_mem_breakdown	Resource Pool memory state breakdown	private, shared, swapped, ballooned, overhead, consumed_overhead, compressed	MB
vsphere.resource_pool_cpu_config	Resource Pool CPU configured reservation and limit	reservation, limit	MHz
vsphere.resource_pool_mem_config	Resource Pool memory configured reservation and limit	reservation, limit	MB
vsphere.resource_pool_overall_status	Resource Pool overall alarm status	green, red, yellow, gray	status

Live Data

This collector exposes read-only readiness and topology functions for interactive troubleshooting in the Live tab. Both functions require selecting a configured vSphere collector job.

vSphere Readiness

Reports the collector's current readiness from cached local state:

• the selected vSphere collector job
• whether the target URL and credentials are configured
• whether the vSphere client, discovery cache, and performance-counter lists are initialized
• discovered inventory counts
• enabled or disabled optional metric, label, and vSAN groups
• cached vSAN result counts when collect_vsan is enabled

The function does not expose the configured vCenter URL or credentials, and it does not issue extra vCenter API calls.

Aspect	Description
Name	Vsphere:readiness
Require Cloud	yes
Performance	Uses cached collector state only: • No additional vCenter or ESXi API requests are triggered • Response size is bounded by the number of configured optional groups and cached inventory summary rows
Security	Does not expose the configured vCenter URL, username, password, or per-object inventory names: • Shows only configuration presence, resource counts, enabled feature flags, include pattern counts, and cached vSAN result counts • Access should still be restricted to authorized operators because it reveals enabled collection surfaces
Availability	Available when: • The vSphere collector job is running • Returns not_ready rows while the collector is not initialized or discovery has not completed • Uses the last cached discovery and vSAN scrape state

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Job	select	Select which configured vSphere collector job to inspect.	yes

Returns

Collector readiness checks from cached local state. Each row represents one target, discovery, label, scope, metric, or vSAN readiness check.

Column	Type	Unit	Visibility	Description
check	string			Stable readiness check identifier.
scope	string			Area covered by the check, such as target, discovery, labels, scope, or metrics.
status	string			Readiness status. Possible values are ok, warning, disabled, and not_ready.
details	string			Human-readable explanation of the current cached state for the check.

vSphere Topology

Reports cached vSphere inventory topology for datacenters, clusters, ESXi hosts, VMs, datastores, networks, datastore clusters, and resource pools.

The public topology function is topology:vsphere. The function builds actors and links from the selected job's cached discovery state. It does not issue extra vCenter API calls. vSphere Network and Distributed Virtual Port Group actors are included only when collect_network_topology is enabled.

Aspect	Description
Name	Vsphere:topology:vsphere
Require Cloud	yes
Performance	Uses cached collector state only: • No additional vCenter or ESXi API requests are triggered by the function • Response size grows with discovered inventory object count • collect_network_topology adds Network discovery during normal collector discovery cycles when enabled
Security	Exposes discovered inventory object names and status attributes already visible through vSphere chart labels and metrics: • Does not expose the configured vCenter URL, username, or password
Availability	Available when: • The vSphere collector job is running • Initial discovery has completed successfully • Returns HTTP 503 while topology data is not cached yet

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Job	select	Select which configured vSphere collector job provides the cached topology.	yes

Returns

Cached vSphere inventory topology payload using the netdata.topology.v1 schema. Actors represent discovered inventory objects, links represent inventory ownership, VM-to-host runtime placement, and host/VM network attachment relationships, and overlays expose refreshable datastore utilization metrics.

Column	Type	Unit	Visibility	Description
schema_version	string			Topology payload schema version.
producer	object			Producer metadata identifying the vSphere topology source, selected collector job, plugin, and local node when available.
collected_at	datetime			Time when the cached topology response was built.
view	object			Topology view metadata.
dictionaries	object			Compact-table dictionaries used by actors, links, evidence, and detail tables.
types	object			Actor, link, evidence, table, and presentation type registry.
presentation	object			Graph-level presentation metadata.
actors	object			Compact actor table for vSphere inventory objects, including datacenters, clusters, ESXi hosts, VMs, datastores, optional networks, datastore clusters, and resource pools.
links	object			Compact link table for relationships between vSphere inventory actors.
evidence	object			Relationship evidence tables backing the rendered links.
tables	object			Actor detail and label tables used by topology modals.
overlays	object			Telemetry overlay refs for refreshable metrics, including datastore used-space utilization selected by collector job and vSphere managed object ID.
stats	object			Counts of discovered inventory objects, actors, links, and overlay refs included in the response.

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the vsphere collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

• Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

  cd /usr/libexec/netdata/plugins.d/

• Switch to the netdata user.

  sudo -u netdata -s

• Run the go.d.plugin to debug the collector:

  ./go.d.plugin -d -m vsphere

  To debug a specific job:

  ./go.d.plugin -d -m vsphere -j jobName

Getting Logs

If you're encountering problems with the vsphere collector, follow these steps to retrieve logs and identify potential issues:

• Run the command specific to your system (systemd, non-systemd, or Docker container).
• Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep vsphere

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

grep vsphere /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

docker logs netdata 2>&1 | grep vsphere

Missing performance samples

If the logs show vsphere:host-no-perf-samples or vsphere:vm-no-perf-samples, verify that the configured account can read vCenter performance counters for the selected hosts and VMs, and that the entities are powered on when performance metrics are expected.

Periodic discovery errors

If the logs show vsphere:periodic-discovery-error, check vCenter reachability, account permissions for the enabled optional surfaces, and whether the configured timeout is large enough for the inventory size.

vCenter reboot recovery

The collector cannot always recover an existing session after a vCenter reboot. Restart go.d.plugin if collection does not resume after vCenter becomes available again.