[receiver/vcenter] Adds vCenter VM CPU readiness metric

.chloggen/add_vcenter_vm_cpu_readiness_metric.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: vcenterreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Adds vCenter CPU readiness metric for VMs."
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [33607]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/vcenterreceiver/README.md

@@ -55,4 +55,8 @@ The full list of settings exposed for this receiver are documented [here](./conf
 
 Details about the metrics produced by this receiver can be found in [metadata.yaml](./metadata.yaml) with further documentation in [documentation.md](./documentation.md)
 
+Additionally some metrics are only available to certain vSphere API versions.
+### 7.0.0+
+- [vcenter.vm.cpu.readiness](https://dp-downloads.broadcom.com/api-content/apis/API_VMA_001/8.0U2/html/vim.vm.Summary.QuickStats.html)
+
 ### Feature gates

receiver/vcenterreceiver/client.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"net/url"
 
+	"github.com/hashicorp/go-version"
 	"github.com/vmware/govmomi"
 	"github.com/vmware/govmomi/find"
 	"github.com/vmware/govmomi/object"
@@ -22,13 +23,14 @@ import (
 
 // vcenterClient is a client that collects data from a vCenter endpoint.
 type vcenterClient struct {
-	moClient  *govmomi.Client
-	vimDriver *vim25.Client
-	finder    *find.Finder
-	pc        *property.Collector
-	pm        *performance.Manager
-	vm        *view.Manager
-	cfg       *Config
+	moClient   *govmomi.Client
+	vimDriver  *vim25.Client
+	finder     *find.Finder
+	pc         *property.Collector
+	pm         *performance.Manager
+	vm         *view.Manager
+	cfg        *Config
+	apiVersion string
 }
 
 var newVcenterClient = defaultNewVcenterClient
@@ -74,6 +76,7 @@ func (vc *vcenterClient) EnsureConnection(ctx context.Context) error {
 	vc.finder = find.NewFinder(vc.vimDriver)
 	vc.pm = performance.NewManager(vc.vimDriver)
 	vc.vm = view.NewManager(vc.vimDriver)
+	vc.apiVersion = vc.getVsphereAPIVersion()
 	return nil
 }
 
@@ -103,6 +106,24 @@ func (vc *vcenterClient) Datacenters(ctx context.Context) ([]mo.Datacenter, erro
 	return datacenters, nil
 }
 
+func (vc *vcenterClient) getVsphereAPIVersion() string {
+	return vc.vimDriver.ServiceContent.About.ApiVersion
+}
+
+func (vc *vcenterClient) VsphereAPIVersionMeetsMin(minVsphereAPIVersion string) bool {
+	apiVersion, err := version.NewVersion(vc.apiVersion)
+	if err != nil {
+		return false
+	}
+
+	minAPIVersion, err := version.NewVersion(minVsphereAPIVersion)
+	if err != nil {
+		return false
+	}
+
+	return apiVersion.GreaterThanOrEqual(minAPIVersion)
+}
+
 // Datastores returns the Datastores of the vSphere SDK
 func (vc *vcenterClient) Datastores(ctx context.Context, containerMoRef vt.ManagedObjectReference) ([]mo.Datastore, error) {
 	v, err := vc.vm.CreateContainerView(ctx, containerMoRef, []string{"Datastore"}, true)

receiver/vcenterreceiver/client_test.go

@@ -298,3 +298,34 @@ func TestSessionReestablish(t *testing.T) {
 		require.True(t, connected)
 	})
 }
+
+func TestVsphereAPIVersionMeetsMin(t *testing.T) {
+	simulator.Test(func(_ context.Context, c *vim25.Client) {
+		finder := find.NewFinder(c)
+		vm := view.NewManager(c)
+		client := vcenterClient{
+			vimDriver:  c,
+			finder:     finder,
+			vm:         vm,
+			apiVersion: c.ServiceContent.About.ApiVersion,
+		}
+		testCases := []struct {
+			name       string
+			minVersion string
+			expectMeet bool
+		}{
+			{"Lower Version", "6.0.0", true},
+			{"Equal Version", client.apiVersion, true},
+			{"Higher Version", "7.0.8", false},
+			{"Empty Version", "", false},
+			{"Invalid Version", "invalid", false},
+		}
+
+		for _, tc := range testCases {
+			t.Run(tc.name, func(t *testing.T) {
+				result := client.VsphereAPIVersionMeetsMin(tc.minVersion)
+				require.Equal(t, tc.expectMeet, result, "Unexpected result for min version: %s", tc.minVersion)
+			})
+		}
+	})
+}

receiver/vcenterreceiver/documentation.md

@@ -477,6 +477,24 @@ As measured over the most recent 20s interval.
 | ---- | ----------- | ------ |
 | object | The object on the virtual machine or host that is being reported on. | Any Str |
 
+## Optional Metrics
+
+The following metrics are not emitted by default. Each of them can be enabled by applying the following configuration:
+
+```yaml
+metrics:
+  <metric_name>:
+    enabled: true
+```
+
+### vcenter.vm.cpu.readiness
+
+Percentage of time that the virtual machine was ready, but could not get scheduled to run on the physical CPU.
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| % | Gauge | Int |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

receiver/vcenterreceiver/go.mod

@@ -5,6 +5,7 @@ go 1.21.0
 require (
 	github.com/basgys/goxml2json v1.1.0
 	github.com/google/go-cmp v0.6.0
+	github.com/hashicorp/go-version v1.7.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/coreinternal v0.103.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/golden v0.103.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatatest v0.103.0
@@ -50,7 +51,6 @@ require (
 	github.com/go-viper/mapstructure/v2 v2.0.0-alpha.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/hashicorp/go-version v1.7.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.17.2 // indirect
 	github.com/knadh/koanf/maps v0.1.1 // indirect

receiver/vcenterreceiver/internal/metadata/testdata/config.yaml

@@ -49,6 +49,8 @@ all_set:
       enabled: true
     vcenter.resource_pool.memory.usage:
       enabled: true
+    vcenter.vm.cpu.readiness:
+      enabled: true
     vcenter.vm.cpu.usage:
       enabled: true
     vcenter.vm.cpu.utilization:
@@ -156,6 +158,8 @@ none_set:
       enabled: false
     vcenter.resource_pool.memory.usage:
       enabled: false
+    vcenter.vm.cpu.readiness:
+      enabled: false
     vcenter.vm.cpu.usage:
       enabled: false
     vcenter.vm.cpu.utilization:

receiver/vcenterreceiver/metadata.yaml

@@ -441,6 +441,15 @@ metrics:
       value_type: int
       aggregation_temporality: cumulative
     attributes: []
+  vcenter.vm.cpu.readiness:
+    enabled: false
+    description: Percentage of time that the virtual machine was ready, but could not get scheduled to run on the physical CPU.
+    unit: "%"
+    gauge:
+      value_type: int
+    attributes: []
+    warnings:
+      if_enabled_not_set: "this metric will be enabled by default starting in release v0.105.0"
   vcenter.vm.memory.utilization:
     enabled: true
     description: The memory utilization of the VM.

receiver/vcenterreceiver/metrics.go

@@ -140,6 +140,13 @@ func (v *vcenterMetricScraper) recordVMStats(
 		return
 	}
 	v.mb.RecordVcenterVMCPUUtilizationDataPoint(ts, 100*float64(cpuUsage)/float64(cpuLimit))
+
+	// OverallCpuReadiness is only available in vSphere API 7.0
+	// https://dp-downloads.broadcom.com/api-content/apis/API_VMA_001/8.0U2/html/vim.vm.Summary.QuickStats.html
+	if v.client.VsphereAPIVersionMeetsMin("7.0.0") {
+		cpuReadiness := vm.Summary.QuickStats.OverallCpuReadiness
+		v.mb.RecordVcenterVMCPUReadinessDataPoint(ts, int64(cpuReadiness))
+	}
 }
 
 var hostPerfMetricList = []string{