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:

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.

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 :gear: (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.

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

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:

Metrics:

Per virtual machine

These metrics refer to the Virtual Machine.

Labels:

Metrics:

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:

Metrics:

Per vSAN virtual machine

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

Labels:

Metrics:

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:

Metrics:

Per vSAN host

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

Labels:

Metrics:

Per host

These metrics refer to the ESXi host.

Labels:

Metrics:

Per datastore

These metrics refer to the Datastore.

Labels:

Metrics:

Per datastore cluster

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

Labels:

Metrics:

Per vSAN cluster

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

Labels:

Metrics:

Per cluster

These metrics refer to the vSphere Cluster.

Labels:

Metrics:

Per resource pool

These metrics refer to the vSphere Resource Pool.

Labels:

Metrics:

Alerts

The following alerts are available:

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.