# vCenter Receiver

<!-- status autogenerated section -->
| Status        |           |
| ------------- |-----------|
| Stability     | [alpha]: metrics   |
| Distributions | [contrib], [observiq], [sumo] |
| Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Areceiver%2Fvcenter%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Areceiver%2Fvcenter) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Areceiver%2Fvcenter%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Areceiver%2Fvcenter) |
| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@djaglowski](https://www.github.com/djaglowski), [@schmikei](https://www.github.com/schmikei) |

[alpha]: https://github.com/open-telemetry/opentelemetry-collector#alpha
[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
[observiq]: https://github.com/observIQ/observiq-otel-collector
[sumo]: https://github.com/SumoLogic/sumologic-otel-collector
<!-- end autogenerated section -->

This receiver fetches metrics from a vCenter or ESXi host running VMware vSphere APIs.

## Prerequisites

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

- 7.5
- 7.0
- 6.7

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.TLSClientSetting](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md). By default insecure settings are rejected and certificate verification is on. |
| 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.                                                                                                                                                                                           |

### Example Configuration

```yaml
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 [here](./config.go) with detailed sample configurations [here](./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](./metadata.yaml) with further documentation in [documentation.md](./documentation.md)

### Feature gates

#### Performance metrics dimensions

These metrics were incorrectly dimensioned previously but the desired fix is a breaking change. To avoid breaking existing users, this feature gate is used to control whether the dimensions are fixed or not. This feature gate is planned to removed in two months.

- `vcenter.vm.network.throughput`
- `vcenter.vm.network.usage`
- `vcenter.vm.network.packet.count`
- `vcenter.vm.disk.latency.avg`
- `vcenter.vm.disk.latency.max`
- `vcenter.host.network.usage`
- `vcenter.host.network.throughput`
- `vcenter.host.network.packet.count`
- `vcenter.host.network.packet.errors`
- `vcenter.host.disk.latency.avg`
- `vcenter.host.disk.latency.max`
- `vcenter.host.disk.throughput`

These metrics were improperly dimensioned and needed another metric attribute `object` in order to properly dimension the data.

1. v0.84.0, August 2023:

- The version of the receiver will keep default behavior.
- `receiver.vcenter.emitPerfMetricsWithObjects` is *disabled* by default.

2. v0.86.0, September 2023:

- The receiver will emit the `object` metric attribute by default
- `receiver.vcenter.emitPerfMetricsWithObjects` is *enabled* by default.

3. v0.88.0, October 2023:

- The feature gates are removed.
- Performance metrics will always include the `object` metric attribute.