Skip to main content
The VMware vSphere integration requires CXDOT Collector 1.7.0 or greater. VMware vSphere is a virtualization platform for managing ESXi hosts and virtual machines. Use the vSphere integration to collect performance and inventory metrics from vCenter Servers and standalone ESXi hosts, and event logs from vCenter Servers. The vSphere integration supports vSphere 8.0.

​
Supported telemetry types

The vSphere integration supports these telemetry types: The integration converts vCenter events to log records. Standalone ESXi hosts provide metrics only.

​
Prerequisites

The vSphere integration has the following prerequisites:
  • A vSphere account with the Read-only role assigned at the root of each inventory you monitor. The role must propagate to the managed hosts and virtual machines.
  • HTTPS access from the Collector host to each vCenter Server or standalone ESXi host. The default port is 443.
  • The root certificate authority certificate for each endpoint, unless you disable certificate verification. System trust stores don’t typically trust the certificates included with vCenter Server and ESXi.

​
Configure

To configure the vSphere integration, follow these steps:
  1. Make each vSphere password available as an environment variable to the Collector process. If you verify endpoint certificates, make each root certificate available as a file.
  2. Add your vCenter Servers to the Collector configuration. For example:
    Each vCenter Server provides metrics for its managed hosts and virtual machines.
  3. Optional: Attach vSphere tags to metrics for filtering and grouping. The Collector adds tags from each virtual machine, host, cluster, datastore, and datacenter to that object’s metrics. For example:
    Standalone ESXi hosts don’t support tags.
  4. Optional: Add standalone ESXi hosts under esxi.instances. A standalone host runs without a vCenter Server, or no configured vCenter Server manages it. For example:
    Configuring both paths for the same host produces duplicate metrics.

​
Validate

To validate the vSphere integration, follow these steps:
  1. In Live Telemetry Analyzer, filter for __name__=cxdot.integration.target.health and cxdot.integration.name=vsphere. Confirm that the metric reports 1 for each configured endpoint. Use cxdot.integration.target to identify the endpoint.
  2. In Metrics Explorer, run the following query:
    Confirm that the query returns host time series for each endpoint. Endpoints with powered-on virtual machines also return vm time series.
  3. In Logs Explorer, filter for the vsphere.event.type attribute after a vCenter event occurs. Confirm that the log record includes the vCenter Server’s server.address.

​
Troubleshooting

  • A host or its virtual machines report duplicate metrics: Remove the host from esxi.instances when a configured vCenter Server already manages it.
  • A virtual machine has no performance time series: vSphere provides real-time performance counters only for powered-on virtual machines. The integration skips powered-off and suspended virtual machines and templates.

​
Configuration reference

Configure one VMware vSphere integration instance with the following settings. In Helm values, place these settings under config.integrations.vsphere. In a Collector configuration file, place them under cxdot.integrations.vsphere.

​
Optional settings

  • enabled Type: boolean. Optional. Default: true. Whether to enable this vSphere integration instance. If true, the Collector collects from its configured vCenter Servers and ESXi hosts. If false, the Collector doesn’t run the integration instance.
  • collection_interval Type: duration. Optional. Default: 2m. How often the Collector reads performance counters. vSphere serves real-time counters as 20-second samples, and each collection returns the newest sample since the previous collection. A collection that runs past this interval delays the next collection. Use an interval closer to 20 seconds for a small inventory to retain more samples.
  • timeout Type: duration. Optional. Default: 10m. How long a collection or event poll can run before the Collector abandons it. This setting guards against an unresponsive endpoint. Set a value long enough for a large inventory or slow server to finish without overlapping the next collection.
  • collect_property_metrics Type: boolean. Optional. Default: false. Whether to collect inventory property metrics. If true, the Collector collects virtual machine uptime, configured CPU and memory, VMware Tools status, guest disks, network adapters and routes, host connection, power, and maintenance state, and cluster HA and DRS settings. Device properties produce one time series per device and increase collection work for a large vCenter inventory. Cluster settings produce four time series per cluster; metric_filters don’t affect them, and cluster resource filters drop them with the cluster. If false, the Collector doesn’t collect these inventory property metrics.
  • inventory_refresh_interval Type: duration. Optional. Default: 5m. How often the Collector refreshes hosts, virtual machines, placement, and properties in the inventory. Performance counters use the cached inventory between refreshes. A new virtual machine appears after the next refresh.
  • max_query_metrics Type: integer. Optional. Default: 500. Minimum: 1. Maximum number of metric IDs in one performance query. The Collector splits larger collections across multiple queries. Increase this value to make fewer, larger requests, or decrease it to make more, smaller requests. A metric collected per instance through per_instance_metrics counts as one ID here, but the server returns one series per device for it, so lower this value when you enable per-instance collection on objects with many devices.
  • concurrency Type: integer. Optional. Default: 4. Minimum: 1. Maximum: 8. How many performance queries are in flight at once against one endpoint, from 1 to 8. Increase this value to collect a large inventory faster, or decrease it to reduce load on a busy server.
  • metric_filters Type: object. Optional. Per resource type, which metrics to collect for its objects, as regular expressions over metric names (vcenter.cpu.usage.avg, vcenter.vm.cpu.usage). A metric is collected when any pattern matches anywhere in its name; anchor with ^ and $ for an exact name. A resource type with no patterns collects every metric. A pattern that doesn’t match a metric selects nothing. A pattern that does not compile, or a type other than vm and host, prevents the Collector from starting.
  • metric_filters.vm Type: array of string. Optional. Default: []. Patterns for virtual machine series.
  • metric_filters.host Type: array of string. Optional. Default: []. Patterns for ESXi host series.
  • per_instance_metrics Type: object. Optional. Per resource type, which metrics to also collect for each instance of the counter — every NIC, LUN, datastore, vCPU or virtual disk of the object — as regular expressions over metric names, matched the way metric_filters are. By default every counter is one series per object, the aggregate over its instances; a matching metric gains one series per instance beside it, told apart by the object attribute, which is empty on the aggregate. This is the Datadog checks’ collect_per_instance_filters, except that the aggregate stays. Per-instance series multiply a metric’s series count by the number of devices on each object, and the server only returns instances for the counters it keeps per device; the rest stay on the aggregate alone. A metric metric_filters drops for a type is not collected at all, per instance or otherwise. Off for every metric by default; host: [".*"] asks for every host counter per device.
  • per_instance_metrics.vm Type: array of string. Optional. Default: []. Patterns for virtual machine series.
  • per_instance_metrics.host Type: array of string. Optional. Default: []. Patterns for ESXi host series.
  • vcenter Type: object. Optional. Settings for collecting from vCenter Servers.
  • vcenter.enabled Type: boolean. Optional. Default: true. Whether to collect from the configured vCenter Servers. If true, the Collector collects metrics and logs from those servers. If false, the Collector doesn’t collect from them.
  • vcenter.instances Type: array of object. Optional. Default: []. The vCenter Servers to monitor, each with its own endpoint and credentials. The Collector doesn’t discover vCenter Servers. List each server in this setting. An empty or omitted list collects no vCenter data.
  • vcenter.instances[].endpoint Type: string. Required. The server, as host or host:port (vcsa.example.com, esx1.example.com:443). The connection is always HTTPS; the port defaults to 443.
  • vcenter.instances[].password Type: string. Required. Password for username. The Collector masks this value in debug output, logs, and error output.
  • vcenter.instances[].resource_filters Type: array of object. Optional. Default: []. Which of this endpoint’s hosts, VMs, clusters, datastores, and datacenters to collect. Each entry names a resource type, the property to match, whether it includes or excludes, and regular expressions over that property. With no entry for a resource type, every object of that type is collected. Otherwise an object matching any exclude entry is dropped, and when include entries exist for its type it must match one of them; an object both included and excluded is excluded. Patterns are anchored at the start of the property, so web- matches web-01 and not old-web-01. Each object is filtered on its own: excluding a cluster or datacenter drops its own time series and leaves the hosts and VMs under it collected, still labeled with its name. Resource filters don’t affect event logs. Select events by vcenter.events.types and resource_types.
  • vcenter.instances[].resource_filters[].patterns Type: array of string. Required. Minimum items: 1. Regular expressions (Go/RE2 syntax) over the property; one match is enough. Each is anchored at the start of the value. A pattern that doesn’t compile prevents the Collector from starting.
  • vcenter.instances[].resource_filters[].property Type: string. Optional. Default: name. What the patterns are matched against: the object’s name in vCenter, the only supported property. Allowed values: name.
  • vcenter.instances[].resource_filters[].resource Type: string. Required. The resource type the filter applies to. Allowed values: vm, host, cluster, datastore, datacenter.
  • vcenter.instances[].resource_filters[].type Type: string. Optional. Default: include. Whether a match collects the object (include) or drops it (exclude). Allowed values: include, exclude.
  • vcenter.instances[].tags Type: array of string. Optional. Default: []. Extra resource attributes in key:value format to add to every time series and event from this endpoint, on top of the collector-wide resource_attributes: product:billing adds the attribute product with the value billing. A value may itself contain colons; an entry without a colon is ignored; a repeated key keeps its last value; a tag never replaces an attribute the integration sets itself.
  • vcenter.instances[].tls Type: object. Optional. TLS settings for the connection to this endpoint. vCenter and ESXi typically use certificates signed by the VMware Certificate Authority. Set ca_file to that authority’s root certificate, or set insecure_skip_verify to true to disable certificate verification. By default, the Collector verifies the server certificate against the system certificate authorities.
  • vcenter.instances[].tls.ca_file Type: string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the vSphere server certificate. If omitted, the Collector uses the system certificate authority pool.
  • vcenter.instances[].tls.ca_pem Type: string. Optional. PEM-encoded certificate authority certificate content used to verify the vSphere server certificate.
  • vcenter.instances[].tls.cert_file Type: string. Optional. Path to the PEM-encoded client certificate file to present when the vSphere endpoint requires mutual TLS authentication.
  • vcenter.instances[].tls.cert_pem Type: string. Optional. PEM-encoded client certificate content to present when the vSphere endpoint requires mutual TLS authentication.
  • vcenter.instances[].tls.cipher_suites Type: array of string. Optional. TLS cipher suites that the Collector can use, in preference order. If omitted, the Collector uses the secure defaults from the Go TLS library. For supported names, see https://go.dev/src/crypto/tls/cipher_suites.go.
  • vcenter.instances[].tls.curve_preferences Type: array of string. Optional. Elliptic curves that the Collector can use for an elliptic curve Diffie-Hellman ephemeral handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.
  • vcenter.instances[].tls.include_system_ca_certs_pool Type: boolean. Optional. Whether to add certificates from the system certificate authority pool to the configured certificate authorities. If true, the Collector trusts both sources. If false, the Collector trusts only the configured certificate authorities.
  • vcenter.instances[].tls.insecure Type: boolean. Optional. Whether to disable transport security. If true, the Collector uses an unencrypted connection. If false, the Collector uses TLS.
  • vcenter.instances[].tls.insecure_skip_verify Type: boolean. Optional. Whether to skip verification of the vSphere server certificate. If true, the connection is encrypted but isn’t authenticated and is vulnerable to man-in-the-middle attacks. If false, the Collector verifies the certificate.
  • vcenter.instances[].tls.key_file Type: string. Optional. Path to the PEM-encoded client private key file used with cert_file for mutual TLS authentication.
  • vcenter.instances[].tls.key_pem Type: string. Optional. PEM-encoded client private key content used with cert_pem for mutual TLS authentication.
  • vcenter.instances[].tls.max_version Type: string. Optional. Maximum TLS protocol version the Collector can use. If omitted, the Collector uses the maximum version supported by the Go TLS library.
  • vcenter.instances[].tls.min_version Type: string. Optional. Minimum TLS protocol version the Collector can use. If omitted, the minimum version is TLS 1.2.
  • vcenter.instances[].tls.reload_interval Type: duration. Optional. How often the Collector reloads certificate and key files. If omitted, the Collector doesn’t reload the files.
  • vcenter.instances[].tls.server_name_override Type: string. Optional. Server name to verify in the vSphere certificate instead of the endpoint hostname. Use this setting when the certificate name differs from the endpoint hostname.
  • vcenter.instances[].tls.tpm Type: object. Optional. Trusted platform module settings for the TLS private key.
  • vcenter.instances[].tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key.
  • vcenter.instances[].tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector loads the key from the configured device or socket. If false, the Collector uses the configured key file or in-memory key.
  • vcenter.instances[].tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module.
  • vcenter.instances[].tls.tpm.path Type: string. Optional. Path to the trusted platform module device or Unix domain socket, such as /dev/tpm0 or /dev/tpmrm0.
  • vcenter.instances[].username Type: string. Required. vSphere user for connecting to this endpoint. A read-only role on the vCenter Server or ESXi host is sufficient.
  • vcenter.collection_level Type: integer. Optional. Default: 1. Minimum: 1. Maximum: 4. vSphere statistics collection level whose counters are read, 1 to 4. Level 1 is the set every vCenter exposes without configuration; each higher level adds counters and multiplies the query volume across the inventory.
  • vcenter.collect_tags Type: boolean. Optional. Default: false. Whether to attach vSphere tags to metrics. If true, the Collector reads the tags assigned to each virtual machine, host, cluster, datastore, and datacenter and adds them to that object’s metrics. Each tag category becomes an attribute key. A category that allows one tag per object sets a string value. A category that allows several sets a sorted list of tag names, such as ["daily","offsite"]. Some backends store a list as one string, so filter on a tag in such a category with a regular expression match rather than an equality match. A tag doesn’t replace the object’s name or placement attributes, but it takes precedence over an instance’s tags entry with the same key. Datadog keeps both values when keys collide, but the Collector keeps only the vSphere tag, so rename the instance’s tags entry if a monitor filters on its value. The Collector drops a tag whose attribute key, including tags_prefix, starts with vcenter., vsphere., cxdot., or server.. A tag change can take up to five minutes to appear, or inventory_refresh_interval if that’s longer, plus one collection_interval. The account for each instance needs read access to tags, which the vCenter Read-only role grants. If the Collector can’t read tags, metrics retain the tags from the last successful refresh. If false, the Collector doesn’t read tags.
  • vcenter.tags_prefix Type: string. Optional. Default: “. Text the Collector adds before each tag category name to form the attribute key. For example, vsphere_ turns the category owner into the attribute key vsphere_owner. A prefix keeps a category from colliding with an attribute set elsewhere in the pipeline. The prefix can’t start with a reserved prefix listed under collect_tags, such as vsphere.. Applies only when collect_tags is true.
  • vcenter.events Type: object. Optional. Settings for converting vCenter events to log records. The Collector reads events from each vcenter.instances endpoint every collection_interval. Standalone ESXi hosts don’t provide event history.
  • vcenter.events.enabled Type: boolean. Optional. Default: true. Whether to collect vCenter events as logs. If true, the Collector collects the selected events. If false, the Collector doesn’t collect vCenter events.
  • vcenter.events.types Type: array of string. Optional. Default: ["AlarmStatusChangedEvent","TaskEvent","VmBeingHotMigratedEvent","VmMessageEvent","VmMigratedEvent","VmPoweredOnEvent","VmPoweredOffEvent","VmReconfiguredEvent","VmSuspendedEvent"]. Event classes to collect, as vSphere names them without the vim.event. prefix (VmPoweredOnEvent). The default is the receiver’s built-in set: alarm status changes, tasks, and VM power, migration, message, reconfiguration and suspend events. An empty list collects the same set.
  • vcenter.events.resource_types Type: array of string. Optional. Default: ["vm","host"]. Inventory object types whose events are collected, for the event classes that name the object they are about: alarms, tasks, scheduled tasks, permission and custom field changes. Omitted, VMs and hosts, the objects the metrics cover, so a datastore alarm or a cluster task is not collected unless its type is listed. An empty list collects none of those classes. Classes that name no object, such as user sessions, are unaffected either way.
  • vcenter.events.excluded_messages Type: object. Optional. Default: {}. Per event class, regular expressions that drop an event whose formatted message matches. Added to the built-in exclusions of routine task events and gray alarm transitions. A pattern that doesn’t compile prevents the Collector from starting.
  • esxi Type: object. Optional. Settings for collecting directly from standalone ESXi hosts.
  • esxi.enabled Type: boolean. Optional. Default: true. Whether to collect from the configured standalone ESXi hosts. If true, the Collector collects metrics from those hosts. If false, the Collector doesn’t collect from them.
  • esxi.instances Type: array of object. Optional. Default: []. ESXi hosts to monitor directly, each with its own endpoint and credentials. A standalone host typically has a local account. Use this setting for hosts not managed by a listed vCenter Server. Listing a host both ways collects duplicate metrics. An empty or omitted list collects no standalone ESXi data.
  • esxi.instances[].endpoint Type: string. Required. The server, as host or host:port (vcsa.example.com, esx1.example.com:443). The connection is always HTTPS; the port defaults to 443.
  • esxi.instances[].password Type: string. Required. Password for username. The Collector masks this value in debug output, logs, and error output.
  • esxi.instances[].resource_filters Type: array of object. Optional. Default: []. Which of this endpoint’s hosts, VMs, clusters, datastores, and datacenters to collect. Each entry names a resource type, the property to match, whether it includes or excludes, and regular expressions over that property. With no entry for a resource type, every object of that type is collected. Otherwise an object matching any exclude entry is dropped, and when include entries exist for its type it must match one of them; an object both included and excluded is excluded. Patterns are anchored at the start of the property, so web- matches web-01 and not old-web-01. Each object is filtered on its own: excluding a cluster or datacenter drops its own time series and leaves the hosts and VMs under it collected, still labeled with its name. Resource filters don’t affect event logs. Select events by vcenter.events.types and resource_types.
  • esxi.instances[].resource_filters[].patterns Type: array of string. Required. Minimum items: 1. Regular expressions (Go/RE2 syntax) over the property; one match is enough. Each is anchored at the start of the value. A pattern that doesn’t compile prevents the Collector from starting.
  • esxi.instances[].resource_filters[].property Type: string. Optional. Default: name. What the patterns are matched against: the object’s name in vCenter, the only supported property. Allowed values: name.
  • esxi.instances[].resource_filters[].resource Type: string. Required. The resource type the filter applies to. Allowed values: vm, host, cluster, datastore, datacenter.
  • esxi.instances[].resource_filters[].type Type: string. Optional. Default: include. Whether a match collects the object (include) or drops it (exclude). Allowed values: include, exclude.
  • esxi.instances[].tags Type: array of string. Optional. Default: []. Extra resource attributes in key:value format to add to every time series and event from this endpoint, on top of the collector-wide resource_attributes: product:billing adds the attribute product with the value billing. A value may itself contain colons; an entry without a colon is ignored; a repeated key keeps its last value; a tag never replaces an attribute the integration sets itself.
  • esxi.instances[].tls Type: object. Optional. TLS settings for the connection to this endpoint. vCenter and ESXi typically use certificates signed by the VMware Certificate Authority. Set ca_file to that authority’s root certificate, or set insecure_skip_verify to true to disable certificate verification. By default, the Collector verifies the server certificate against the system certificate authorities.
  • esxi.instances[].tls.ca_file Type: string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the vSphere server certificate. If omitted, the Collector uses the system certificate authority pool.
  • esxi.instances[].tls.ca_pem Type: string. Optional. PEM-encoded certificate authority certificate content used to verify the vSphere server certificate.
  • esxi.instances[].tls.cert_file Type: string. Optional. Path to the PEM-encoded client certificate file to present when the vSphere endpoint requires mutual TLS authentication.
  • esxi.instances[].tls.cert_pem Type: string. Optional. PEM-encoded client certificate content to present when the vSphere endpoint requires mutual TLS authentication.
  • esxi.instances[].tls.cipher_suites Type: array of string. Optional. TLS cipher suites that the Collector can use, in preference order. If omitted, the Collector uses the secure defaults from the Go TLS library. For supported names, see https://go.dev/src/crypto/tls/cipher_suites.go.
  • esxi.instances[].tls.curve_preferences Type: array of string. Optional. Elliptic curves that the Collector can use for an elliptic curve Diffie-Hellman ephemeral handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.
  • esxi.instances[].tls.include_system_ca_certs_pool Type: boolean. Optional. Whether to add certificates from the system certificate authority pool to the configured certificate authorities. If true, the Collector trusts both sources. If false, the Collector trusts only the configured certificate authorities.
  • esxi.instances[].tls.insecure Type: boolean. Optional. Whether to disable transport security. If true, the Collector uses an unencrypted connection. If false, the Collector uses TLS.
  • esxi.instances[].tls.insecure_skip_verify Type: boolean. Optional. Whether to skip verification of the vSphere server certificate. If true, the connection is encrypted but isn’t authenticated and is vulnerable to man-in-the-middle attacks. If false, the Collector verifies the certificate.
  • esxi.instances[].tls.key_file Type: string. Optional. Path to the PEM-encoded client private key file used with cert_file for mutual TLS authentication.
  • esxi.instances[].tls.key_pem Type: string. Optional. PEM-encoded client private key content used with cert_pem for mutual TLS authentication.
  • esxi.instances[].tls.max_version Type: string. Optional. Maximum TLS protocol version the Collector can use. If omitted, the Collector uses the maximum version supported by the Go TLS library.
  • esxi.instances[].tls.min_version Type: string. Optional. Minimum TLS protocol version the Collector can use. If omitted, the minimum version is TLS 1.2.
  • esxi.instances[].tls.reload_interval Type: duration. Optional. How often the Collector reloads certificate and key files. If omitted, the Collector doesn’t reload the files.
  • esxi.instances[].tls.server_name_override Type: string. Optional. Server name to verify in the vSphere certificate instead of the endpoint hostname. Use this setting when the certificate name differs from the endpoint hostname.
  • esxi.instances[].tls.tpm Type: object. Optional. Trusted platform module settings for the TLS private key.
  • esxi.instances[].tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key.
  • esxi.instances[].tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector loads the key from the configured device or socket. If false, the Collector uses the configured key file or in-memory key.
  • esxi.instances[].tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module.
  • esxi.instances[].tls.tpm.path Type: string. Optional. Path to the trusted platform module device or Unix domain socket, such as /dev/tpm0 or /dev/tpmrm0.
  • esxi.instances[].username Type: string. Required. vSphere user for connecting to this endpoint. A read-only role on the vCenter Server or ESXi host is sufficient.