> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Vcenter

> OpenTelemetry receiver for Vcenter

# Vcenter Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@schmikei](https://github.com/schmikei), [@ishleenk17](https://github.com/ishleenk17)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/vcenterreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## Overview

## Prerequisites

This receiver has been built to support ESXi and vCenter versions:

* 8
* 7.0

A “Read Only” user assigned to a vSphere with permissions to the vCenter server, cluster and all subsequent resources being monitored must be specified in order for the receiver to retrieve information about them.

## Configuration

| Parameter | Default | Type | Notes |
| - | - | - | - |
| endpoint | | String | Endpoint to the vCenter Server or ESXi host that has the sdk path enabled. Required. The expected format is `<protocol>://<hostname>` <br /><br /> i.e: `https://vcsa.hostname.localnet` |
| username | | String | Required |
| password | | String | Required |
| tls | | TLSClientSetting | Not Required. Will use defaults for [configtls.ClientConfig](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md). By default insecure settings are rejected and certificate verification is on. |
| proxy\_url | | String | Not Required. URL of the proxy to use when connecting to the vCenter SDK endpoint <br /><br /> i.e: `socks5://proxy.hostname.localnet:1080`. The `http`, `https`, `socks5` and `socks5h` schemes are supported. When unset, the standard `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` environment variables apply. Unlike those, this setting is scoped to a single receiver instance, so several `vcenter/<name>` receivers in one collector can each use a different proxy. <br /><br /> When it is set, those environment variables are ignored for this receiver and all SDK traffic is sent to the proxy. |
| collection\_interval | 2m | Duration | This receiver collects metrics on an interval. If the vCenter is fairly large, this value may need to be increased. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` |
| initial\_delay | 1s | Duration | Defines how long this receiver waits before starting. |
| max\_query\_metrics | 256 | int | Maximum number of metric IDs per `QueryPerf` API call. Should match or be lower than your vCenter's `vpxd.stats.maxQueryMetrics` setting (default 256). Set to `0` to disable batching. See [VMware KB 301449](https://knowledge.broadcom.com/external/article?articleNumber=301449). |

### Example Configuration

```yaml theme={null}
receivers:
  vcenter:
    endpoint: http://localhost:15672
    username: otelu
    password: ${env:VCENTER_PASSWORD}
    collection_interval: 5m
    initial_delay: 1s
    metrics: []
```

The full list of settings exposed for this receiver are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/vcenterreceiver/config.go) with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/vcenterreceiver/testdata/config.yaml). TLS config is documented further under the [opentelemetry collector's configtls package](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md).

## Metrics

Details about the metrics produced by this receiver can be found in [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/vcenterreceiver/metadata.yaml) with further documentation in [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/vcenterreceiver/documentation.md)

### Feature gates

**BETA**: `receiver.vcenter.resourcePoolMemoryUsageAttribute`

This feature gate is enabled by default. It adds the `memory_usage_type` attribute to the
`vcenter.resource_pool.memory.usage` metric. Disabling the gate retains the previous behavior:
only guest memory usage is emitted, without the attribute.

## Metrics

| Metric Name | Description | Unit | Type | Attributes |
| - | - | - | - | - |
| ✅ `vcenter.cluster.cpu.effective` | The effective CPU available to the cluster. This value excludes CPU from hosts in maintenance mode or are unresponsive. | MHz | UpDownCounter | |
| ✅ `vcenter.cluster.cpu.limit` | The amount of CPU available to the cluster. | MHz | UpDownCounter | |
| ✅ `vcenter.cluster.host.count` | The number of hosts in the cluster. | \{hosts} | UpDownCounter | host\_effective |
| ✅ `vcenter.cluster.memory.effective` | The effective available memory of the cluster. | By | UpDownCounter | |
| ✅ `vcenter.cluster.memory.limit` | The available memory of the cluster. | By | UpDownCounter | |
| ✅ `vcenter.cluster.vm.count` | The number of virtual machines in the cluster. | \{virtual\_machines} | UpDownCounter | vm\_count\_power\_state |
| ✅ `vcenter.cluster.vm_template.count` | The number of virtual machine templates in the cluster. | \{virtual\_machine\_templates} | UpDownCounter | |
| ✅ `vcenter.cluster.vsan.congestions` | The congestions of IOs generated by all vSAN clients in the cluster. | \{congestions/s} | Gauge | |
| ✅ `vcenter.cluster.vsan.latency.avg` | The overall cluster latency while accessing vSAN storage. | us | Gauge | vsan\_latency\_type |
| ✅ `vcenter.cluster.vsan.operations` | The vSAN IOPs of a cluster. | \{operations/s} | Gauge | vsan\_operation\_type |
| ✅ `vcenter.cluster.vsan.throughput` | The vSAN throughput of a cluster. | By/s | Gauge | vsan\_throughput\_direction |
| ✅ `vcenter.datacenter.cluster.count` | The number of clusters in the datacenter. | \{clusters} | UpDownCounter | entity\_status |
| ✅ `vcenter.datacenter.cpu.limit` | The total amount of CPU available to the datacenter. | MHz | UpDownCounter | |
| ✅ `vcenter.datacenter.datastore.count` | The number of datastores in the datacenter. | \{datastores} | UpDownCounter | |
| ✅ `vcenter.datacenter.disk.space` | The amount of available and used disk space in the datacenter. | By | UpDownCounter | disk\_state |
| ✅ `vcenter.datacenter.host.count` | The number of hosts in the datacenter. | \{hosts} | UpDownCounter | entity\_status, host\_power\_state |
| ✅ `vcenter.datacenter.memory.limit` | The total amount of memory available to the datacenter. | By | UpDownCounter | |
| ✅ `vcenter.datacenter.vm.count` | The number of VM's in the datacenter. | \{virtual\_machines} | UpDownCounter | entity\_status, vm\_count\_power\_state |
| ✅ `vcenter.datastore.disk.usage` | The amount of space in the datastore. | By | UpDownCounter | disk\_state |
| ✅ `vcenter.datastore.disk.utilization` | The utilization of the datastore. | % | Gauge | |
| ✅ `vcenter.host.cpu.capacity` | Total CPU capacity of the host system. | MHz | UpDownCounter | |
| ✅ `vcenter.host.cpu.reserved` | The CPU of the host reserved for use by virtual machines. | MHz | UpDownCounter | cpu\_reservation\_type |
| ✅ `vcenter.host.cpu.usage` | The amount of CPU used by the host. | MHz | UpDownCounter | |
| ✅ `vcenter.host.cpu.utilization` | The CPU utilization of the host system. | % | Gauge | |
| ✅ `vcenter.host.disk.latency.avg` | The latency of operations to the host system's disk. | ms | Gauge | disk\_direction, object\_name |
| ✅ `vcenter.host.disk.latency.max` | Highest latency value across all disks used by the host. | ms | Gauge | object\_name |
| ✅ `vcenter.host.disk.throughput` | Average number of kilobytes read from or written to the disk each second. | \{KiBy/s} | UpDownCounter | disk\_direction, object\_name |
| ❌ `vcenter.host.memory.active` | The amount of memory the host's powered-on VMs are actively using. | MiBy | UpDownCounter | |
| ❌ `vcenter.host.memory.ballooned` | The amount of guest physical memory reclaimed from the host's VMs via the balloon driver. | MiBy | UpDownCounter | |
| ❌ `vcenter.host.memory.capacity` | Total memory  capacity of the host system. | MiBy | UpDownCounter | |
| ❌ `vcenter.host.memory.granted` | The amount of machine memory that is granted to the powered-on VMs on the host. | MiBy | UpDownCounter | |
| ✅ `vcenter.host.memory.usage` | The amount of memory the host system is using. | MiBy | UpDownCounter | |
| ✅ `vcenter.host.memory.utilization` | The percentage of the host system's memory capacity that is being utilized. | % | Gauge | |
| ✅ `vcenter.host.network.packet.drop.rate` | The rate of packets dropped across each physical NIC (network interface controller) instance on the host. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.host.network.packet.error.rate` | The rate of packet errors transmitted or received on the host network. | \{errors/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.host.network.packet.rate` | The rate of packets transmitted or received across each physical NIC (network interface controller) instance on the host. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.host.network.throughput` | The amount of data that was transmitted or received over the network by the host. | \{KiBy/s} | UpDownCounter | throughput\_direction, object\_name |
| ✅ `vcenter.host.network.usage` | The sum of the data transmitted and received for all the NIC instances of the host. | \{KiBy/s} | UpDownCounter | object\_name |
| ✅ `vcenter.host.vsan.cache.hit_rate` | The host's read IOs which could be satisfied by the local client cache. | % | Gauge | |
| ✅ `vcenter.host.vsan.congestions` | The congestions of IOs generated by all vSAN clients in the host. | \{congestions/s} | Gauge | |
| ✅ `vcenter.host.vsan.latency.avg` | The host latency while accessing vSAN storage. | us | Gauge | vsan\_latency\_type |
| ✅ `vcenter.host.vsan.operations` | The vSAN IOPs of a host. | \{operations/s} | Gauge | vsan\_operation\_type |
| ✅ `vcenter.host.vsan.throughput` | The vSAN throughput of a host. | By/s | Gauge | vsan\_throughput\_direction |
| ✅ `vcenter.resource_pool.cpu.shares` | The amount of shares of CPU in the resource pool. | \{shares} | UpDownCounter | |
| ✅ `vcenter.resource_pool.cpu.usage` | The usage of the CPU used by the resource pool. | MHz | UpDownCounter | |
| ✅ `vcenter.resource_pool.memory.ballooned` | The amount of memory in a resource pool that is ballooned due to virtualization. | MiBy | UpDownCounter | |
| ✅ `vcenter.resource_pool.memory.granted` | The amount of memory that is granted to VMs in the resource pool from shared and non-shared host memory. | MiBy | UpDownCounter | memory\_granted\_type |
| ✅ `vcenter.resource_pool.memory.shares` | The amount of shares of memory in the resource pool. | \{shares} | UpDownCounter | |
| ✅ `vcenter.resource_pool.memory.swapped` | The amount of memory that is granted to VMs in the resource pool from the host's swap space. | MiBy | UpDownCounter | |
| ✅ `vcenter.resource_pool.memory.usage` | The usage of the memory by the resource pool. | MiBy | UpDownCounter | memory\_usage\_type |
| ✅ `vcenter.vm.cpu.readiness` | Percentage of time that the virtual machine was ready, but could not get scheduled to run on the physical CPU. | % | Gauge | |
| ❌ `vcenter.vm.cpu.time` | CPU time spent in idle, ready or wait state. | % | Gauge | cpu\_state, object\_name |
| ✅ `vcenter.vm.cpu.usage` | The amount of CPU used by the VM. | MHz | UpDownCounter | |
| ✅ `vcenter.vm.cpu.utilization` | The CPU utilization of the VM. | % | Gauge | |
| ✅ `vcenter.vm.disk.latency.avg` | The latency of operations to the virtual machine's disk. | ms | Gauge | disk\_direction, disk\_type, object\_name |
| ✅ `vcenter.vm.disk.latency.max` | The highest reported total latency (device and kernel times) over an interval of 20 seconds. | ms | Gauge | object\_name |
| ✅ `vcenter.vm.disk.throughput` | Average number of kilobytes read from or written to the virtual disk each second. | \{KiBy/s} | Gauge | disk\_direction, object\_name |
| ✅ `vcenter.vm.disk.usage` | The amount of storage space used by the virtual machine. | By | UpDownCounter | disk\_state |
| ✅ `vcenter.vm.disk.utilization` | The utilization of storage on the virtual machine. | % | Gauge | |
| ✅ `vcenter.vm.memory.ballooned` | The amount of memory that is ballooned due to virtualization. | MiBy | UpDownCounter | |
| ❌ `vcenter.vm.memory.granted` | The amount of memory that is granted to a VM. | MiBy | UpDownCounter | |
| ✅ `vcenter.vm.memory.swapped` | The portion of memory that is granted to this VM from the host's swap space. | MiBy | UpDownCounter | |
| ✅ `vcenter.vm.memory.swapped_ssd` | The amount of memory swapped to fast disk device such as SSD. | KiBy | UpDownCounter | |
| ✅ `vcenter.vm.memory.usage` | The amount of memory that is used by the virtual machine. | MiBy | UpDownCounter | |
| ✅ `vcenter.vm.memory.utilization` | The memory utilization of the VM. | % | Gauge | |
| ❌ `vcenter.vm.network.broadcast.packet.rate` | The rate of broadcast packets transmitted or received by each vNIC (virtual network interface controller) on the virtual machine. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ❌ `vcenter.vm.network.multicast.packet.rate` | The rate of multicast packets transmitted or received by each vNIC (virtual network interface controller) on the virtual machine. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.vm.network.packet.drop.rate` | The rate of transmitted or received packets dropped by each vNIC (virtual network interface controller) on the virtual machine. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.vm.network.packet.rate` | The rate of packets transmitted or received by each vNIC (virtual network interface controller) on the virtual machine. | \{packets/s} | Gauge | throughput\_direction, object\_name |
| ✅ `vcenter.vm.network.throughput` | The amount of data that was transmitted or received over the network of the virtual machine. | By/s | UpDownCounter | throughput\_direction, object\_name |
| ✅ `vcenter.vm.network.usage` | The network utilization combined transmit and receive rates during an interval. | \{KiBy/s} | UpDownCounter | object\_name |
| ✅ `vcenter.vm.vsan.latency.avg` | The virtual machine latency while accessing vSAN storage. | us | Gauge | vsan\_latency\_type |
| ✅ `vcenter.vm.vsan.operations` | The vSAN IOPs of a virtual machine. | \{operations/s} | Gauge | vsan\_operation\_type |
| ✅ `vcenter.vm.vsan.throughput` | The vSAN throughput of a virtual machine. | By/s | Gauge | vsan\_throughput\_direction |

## Attributes

| Attribute Name | Description | Type | Values |
| - | - | - | - |
| `cpu_reservation_type` | The type of CPU reservation for the host. | string | `total`, `used` |
| `cpu_state` | CPU time spent in idle, ready or idle state. | string | `idle`, `ready`, `wait` |
| `direction` | The direction of disk latency. | string | `read`, `write` |
| `disk_state` | The state of storage and whether it is already allocated or free. | string | `available`, `used` |
| `disk_type` | The type of storage device that is being recorded. | string | `virtual`, `physical` |
| `status` | The current status of the managed entity. | string | `red`, `yellow`, `green`, `gray` |
| `effective` | Whether the host is effective in the vCenter cluster. | bool | |
| `power_state` | The current power state of the host. | string | `on`, `off`, `standby`, `unknown` |
| `type` | The type of memory granted. | string | `private`, `shared` |
| `type` | The type of memory usage. | string | `guest`, `host`, `overhead` |
| `object` | The object on the virtual machine or host that is being reported on. | string | |
| `direction` | The direction of network throughput. | string | `transmitted`, `received` |
| `power_state` | The current power state of the virtual machine. | string | `on`, `off`, `suspended`, `unknown` |
| `type` | The type of vSAN latency. | string | `read`, `write` |
| `type` | The type of vSAN operation. | string | `read`, `write`, `unmap` |
| `direction` | The type of vSAN throughput. | string | `read`, `write` |

## Resource Attributes

| Attribute Name | Description | Type | Enabled |
| - | - | - | - |
| `vcenter.cluster.name` | The name of the vCenter cluster. | string | ✅ |
| `vcenter.datacenter.name` | The name of the vCenter datacenter. | string | ✅ |
| `vcenter.datastore.name` | The name of the vCenter datastore. | string | ✅ |
| `vcenter.host.name` | The hostname of the vCenter ESXi host. | string | ✅ |
| `vcenter.resource_pool.inventory_path` | The inventory path of the resource pool. | string | ✅ |
| `vcenter.resource_pool.name` | The name of the resource pool. | string | ✅ |
| `vcenter.virtual_app.inventory_path` | The inventory path of the vApp. | string | ✅ |
| `vcenter.virtual_app.name` | The name of the vApp. | string | ✅ |
| `vcenter.vm.id` | The instance UUID of the virtual machine. | string | ✅ |
| `vcenter.vm.name` | The name of the virtual machine. | string | ✅ |
| `vcenter.vm_template.id` | The instance UUID of the virtual machine template. | string | ✅ |
| `vcenter.vm_template.name` | The name of the virtual machine template. | string | ✅ |

## Configuration

### Example Configuration

```yaml theme={null}
vcenter:
  endpoint: http://vcsa.host.localnet
  username: otelu
  password: ${env:VCENTER_PASSWORD}
  proxy_url: socks5://proxy.host.localnet:1080
  collection_interval: 5m
  max_query_metrics: 128
  metrics:
    vcenter.host.cpu.utilization:
      enabled: false
```

***

*Last generated: 2026-10-05*