<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/vsphere/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/vsphere/metadata.yaml"
sidebar_label: "VMware vCenter Server"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Containers and VMs"
keywords: ['vmware', 'esxi', 'vcenter']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# VMware vCenter Server


<img src="https://netdata.cloud/img/vmware.svg" width="150"/>


Plugin: go.d.plugin
Module: vsphere

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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**](#via-ui)     | Fast setup without editing files                                                         | Go to **Nodes → Configure this node → Collectors → Jobs**, search for **vsphere**, then click **+** to add a job. |
| [**File**](#via-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.


<details open><summary>Config options</summary>



| 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](#option-labels-tag-categories) | vSphere tag category allowlist. |  | no |
|  | [custom_attributes](#option-labels-custom-attributes) | vSphere custom attribute allowlist. |  | no |
| **High Cardinality** | [collect_datastore_clusters](#option-high-cardinality-collect-datastore-clusters) | Collect datastore cluster capacity and Storage DRS status. | no | no |
|  | [datastore_cluster_include](#option-high-cardinality-datastore-cluster-include) | Datastore cluster selector. | /* | no |
|  | [collect_vsan](#option-high-cardinality-collect-vsan) | Collect vSAN metrics. | no | no |
|  | [vsan_cluster_include](#option-high-cardinality-vsan-cluster-include) | vSAN cluster selector. | /* | no |
|  | [vsan_host_include](#option-high-cardinality-vsan-host-include) | vSAN host selector. | /* | no |
|  | [vsan_vm_include](#option-high-cardinality-vsan-vm-include) | vSAN VM selector. | /* | no |
| **Collection** | [collect_network_topology](#option-collection-collect-network-topology) | Discover networks for the vSphere Topology function. | no | no |
| **Filters** | [host_include](#option-filters-host-include) | Hosts selector (filter). | /* | no |
|  | [vm_include](#option-filters-vm-include) | VM selector (filter). | /* | no |
|  | [datastore_include](#option-filters-datastore-include) | Datastore selector (filter). | /* | no |
|  | [cluster_include](#option-filters-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](https://learn.netdata.cloud/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts#virtual-nodes). |  | no |

<a id="option-labels-tag-categories"></a>
##### 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.

```yaml
tag_categories:
  - "Environment"
  - "Business Unit"
```


<a id="option-labels-custom-attributes"></a>
##### 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>`.

```yaml
custom_attributes:
  - "Owner"
  - "Cost Center"
```


<a id="option-high-cardinality-collect-datastore-clusters"></a>
##### 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.


<a id="option-high-cardinality-datastore-cluster-include"></a>
##### 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.

```yaml
datastore_cluster_include:
  - "/*"
```


<a id="option-high-cardinality-collect-vsan"></a>
##### 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.


<a id="option-high-cardinality-vsan-cluster-include"></a>
##### 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>`.

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


<a id="option-high-cardinality-vsan-host-include"></a>
##### 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>`.

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


<a id="option-high-cardinality-vsan-vm-include"></a>
##### 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>`.

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


<a id="option-collection-collect-network-topology"></a>
##### 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.


<a id="option-filters-host-include"></a>
##### 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](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md#simple-patterns).
- Syntax:

  ```yaml
  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
  ```


<a id="option-filters-vm-include"></a>
##### 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](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md#simple-patterns).
- Syntax:

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


<a id="option-filters-datastore-include"></a>
##### datastore_include

Metrics of datastores matching the selector will be collected.

- Include pattern syntax: "/Datacenter pattern/Datastore pattern".
- Match pattern syntax: [simple patterns](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md#simple-patterns).
- Syntax:

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


<a id="option-filters-cluster-include"></a>
##### 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](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md#simple-patterns).
- Syntax:

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



</details>


#### 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:

```yaml
update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2
```
You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

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

##### Examples

###### Basic

A basic example configuration.

```yaml
jobs:
  - name     : vcenter1
    url      : https://203.0.113.1
    username : admin@vsphere.local
    password : somepassword

```
###### Multi-instance

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

Collecting metrics from local and remote instances.


<details open><summary>Config</summary>

```yaml
jobs:
  - name     : vcenter1
    url      : https://203.0.113.1
    username : admin@vsphere.local
    password : somepassword

  - name     : vcenter2
    url      : https://203.0.113.10
    username : admin@vsphere.local
    password : somepassword

```
</details>



## Alerts


The following alerts are available:

| Alert name  | On metric | Description |
|:------------|:----------|:------------|
| [ vsphere_vm_cpu_utilization ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | vsphere.vm_cpu_utilization | Virtual Machine CPU utilization |
| [ vsphere_vm_mem_utilization ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | vsphere.vm_mem_utilization | Virtual Machine memory utilization |
| [ vsphere_vm_snapshot_chain_depth ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | vsphere.vm_snapshot_max_chain_depth | Virtual Machine snapshot maximum chain depth |
| [ vsphere_vm_snapshot_age ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | vsphere.vm_snapshot_max_age | Virtual Machine oldest snapshot age |
| [ vsphere_host_cpu_utilization ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | vsphere.host_cpu_utilization | ESXi Host CPU utilization |
| [ vsphere_host_mem_utilization ](https://github.com/netdata/netdata/blob/master/src/health/health.d/vsphere.conf) | 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:<br/>• No additional vCenter or ESXi API requests are triggered<br/>• 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:<br/>• Shows only configuration presence, resource counts, enabled feature flags, include pattern counts, and cached vSAN result counts<br/>• Access should still be restricted to authorized operators because it reveals enabled collection surfaces |
| Availability | Available when:<br/>• The vSphere collector job is running<br/>• Returns not_ready rows while the collector is not initialized or discovery has not completed<br/>• 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:<br/>• No additional vCenter or ESXi API requests are triggered by the function<br/>• Response size grows with discovered inventory object count<br/>• `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:<br/>• Does not expose the configured vCenter URL, username, or password |
| Availability | Available when:<br/>• The vSphere collector job is running<br/>• Initial discovery has completed successfully<br/>• 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]`.

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

- Switch to the `netdata` user.

  ```bash
  sudo -u netdata -s
  ```

- Run the `go.d.plugin` to debug the collector:

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

  To debug a specific job:

  ```bash
  ./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:

```bash
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:

```bash
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:

```bash
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.
