[receiver/vcenter] Adds Suspended VM Counts to `vcenter.cluster.vm.co…

…unt` (open-telemetry#32804)

**Description:** <Describe what has changed.>
Currently the metric `vcenter.cluster.vm.count` does not include a count
for suspended VMs. Instead it lumps together this count with the value
it reports for "poweredOn" VMs.

Here I'm modifying the relevent metric attribute to allow for a
"suspended" value, and updating the metric to report this count.

I also added a minor capitalization fix for the metadata description.

**Link to tracking Issue:** <Issue number if applicable>
open-telemetry#32803 

**Testing:** <Describe what testing was performed and which tests were
added.>
Unit/integration tests updated and tested. Local environment tested.

**Documentation:** <Describe the documentation added.>
New documentation generated based on the metadata.

.chloggen/fix_vcenter-cluster-vm-count-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: bug_fix
+
+# 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: "Updates the `vcenter.cluster.vm.count` metric to also report suspended VM counts"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [32803]
+
+# (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/documentation.md

@@ -70,7 +70,7 @@ The memory that is currently used by the cluster.
 
 ### vcenter.cluster.vm.count
 
-the number of virtual machines in the cluster.
+The number of virtual machines in the cluster.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
 | ---- | ----------- | ---------- | ----------------------- | --------- |
@@ -80,7 +80,7 @@ the number of virtual machines in the cluster.
 
 | Name | Description | Values |
 | ---- | ----------- | ------ |
-| power_state | Whether the virtual machines are powered on or off. | Str: ``on``, ``off`` |
+| power_state | The current power state of the virtual machine. | Str: ``on``, ``off``, ``suspended`` |
 
 ### vcenter.datastore.disk.usage
 

receiver/vcenterreceiver/metadata.yaml

@@ -91,11 +91,12 @@ attributes:
       - received
   vm_count_power_state:
     name_override: power_state
-    description: Whether the virtual machines are powered on or off.
+    description: The current power state of the virtual machine.
     type: string
     enum:
       - "on"
       - "off"
+      - "suspended"
   object_name:
     name_override: object
     description: The object on the virtual machine or host that is being reported on.
@@ -150,7 +151,7 @@ metrics:
     attributes: []
   vcenter.cluster.vm.count:
     enabled: true
-    description: the number of virtual machines in the cluster.
+    description: The number of virtual machines in the cluster.
     unit: "{virtual_machines}"
     sum:
       monotonic: false

receiver/vcenterreceiver/scraper.go

@@ -124,9 +124,9 @@ func (v *vcenterMetricScraper) collectClusters(ctx context.Context, datacenter *
 	for _, c := range computes {
 		v.collectHosts(ctx, now, dcName, c, errs)
 		v.collectDatastores(ctx, now, dcName, c, errs)
-		poweredOnVMs, poweredOffVMs := v.collectVMs(ctx, now, dcName, c, errs)
+		poweredOnVMs, poweredOffVMs, suspendedVMs := v.collectVMs(ctx, now, dcName, c, errs)
 		if c.Reference().Type == "ClusterComputeResource" {
-			v.collectCluster(ctx, now, dcName, c, poweredOnVMs, poweredOffVMs, errs)
+			v.collectCluster(ctx, now, dcName, c, poweredOnVMs, poweredOffVMs, suspendedVMs, errs)
 		}
 	}
 }
@@ -136,11 +136,12 @@ func (v *vcenterMetricScraper) collectCluster(
 	now pcommon.Timestamp,
 	dcName string,
 	c *object.ComputeResource,
-	poweredOnVMs, poweredOffVMs int64,
+	poweredOnVMs, poweredOffVMs, suspendedVMs int64,
 	errs *scrapererror.ScrapeErrors,
 ) {
 	v.mb.RecordVcenterClusterVMCountDataPoint(now, poweredOnVMs, metadata.AttributeVMCountPowerStateOn)
 	v.mb.RecordVcenterClusterVMCountDataPoint(now, poweredOffVMs, metadata.AttributeVMCountPowerStateOff)
+	v.mb.RecordVcenterClusterVMCountDataPoint(now, suspendedVMs, metadata.AttributeVMCountPowerStateSuspended)
 
 	var moCluster mo.ClusterComputeResource
 	err := c.Properties(ctx, c.Reference(), []string{"summary"}, &moCluster)
@@ -366,7 +367,7 @@ func (v *vcenterMetricScraper) collectVMs(
 	dcName string,
 	compute *object.ComputeResource,
 	errs *scrapererror.ScrapeErrors,
-) (poweredOnVMs int64, poweredOffVMs int64) {
+) (poweredOnVMs int64, poweredOffVMs int64, suspendedVMs int64) {
 	// Get all VMs with property data
 	vms, err := v.client.VMs(ctx)
 	if err != nil {
@@ -398,10 +399,13 @@ func (v *vcenterMetricScraper) collectVMs(
 			continue
 		}
 
-		if string(vm.Runtime.PowerState) == "poweredOff" {
+		switch vm.Runtime.PowerState {
+		case "poweredOff":
 			poweredOffVMs++
-		} else {
+		case "poweredOn":
 			poweredOnVMs++
+		default:
+			suspendedVMs++
 		}
 
 		// vApp may not exist for a VM
@@ -460,7 +464,7 @@ func (v *vcenterMetricScraper) collectVMs(
 		v.mb.EmitForResource(metadata.WithResource(rb.Emit()))
 	}
 
-	return poweredOnVMs, poweredOffVMs
+	return poweredOnVMs, poweredOffVMs, suspendedVMs
 }
 
 func (v *vcenterMetricScraper) buildVMMetrics(

receiver/vcenterreceiver/testdata/integration/expected.yaml

@@ -744,7 +744,7 @@ resourceMetrics:
                   startTimeUnixNano: "1707407684042820000"
                   timeUnixNano: "1707407733803628000"
             unit: By
-          - description: the number of virtual machines in the cluster.
+          - description: The number of virtual machines in the cluster.
             name: vcenter.cluster.vm.count
             sum:
               aggregationTemporality: 2
@@ -763,6 +763,13 @@ resourceMetrics:
                         stringValue: "off"
                   startTimeUnixNano: "1707407684042820000"
                   timeUnixNano: "1707407733803628000"
+                - asInt: "0"
+                  attributes:
+                    - key: power_state
+                      value:
+                        stringValue: "suspended"
+                  startTimeUnixNano: "1707407684042820000"
+                  timeUnixNano: "1707407733803628000"
             unit: "{virtual_machines}"
         scope:
           name: otelcol/vcenterreceiver

receiver/vcenterreceiver/testdata/metrics/expected-all-enabled.yaml

@@ -65,7 +65,7 @@ resourceMetrics:
                   startTimeUnixNano: "1000000"
                   timeUnixNano: "2000000"
             unit: By
-          - description: the number of virtual machines in the cluster.
+          - description: The number of virtual machines in the cluster.
             name: vcenter.cluster.vm.count
             sum:
               aggregationTemporality: 2
@@ -84,6 +84,13 @@ resourceMetrics:
                         stringValue: "on"
                   startTimeUnixNano: "1000000"
                   timeUnixNano: "2000000"
+                - asInt: "0"
+                  attributes:
+                    - key: power_state
+                      value:
+                        stringValue: "suspended"
+                  startTimeUnixNano: "1000000"
+                  timeUnixNano: "2000000"
             unit: '{virtual_machines}'
         scope:
           name: otelcol/vcenterreceiver

receiver/vcenterreceiver/testdata/metrics/expected.yaml

@@ -62,7 +62,7 @@ resourceMetrics:
                   startTimeUnixNano: "1000000"
                   timeUnixNano: "2000000"
             unit: By
-          - description: the number of virtual machines in the cluster.
+          - description: The number of virtual machines in the cluster.
             name: vcenter.cluster.vm.count
             sum:
               aggregationTemporality: 2
@@ -81,6 +81,13 @@ resourceMetrics:
                         stringValue: "on"
                   startTimeUnixNano: "1000000"
                   timeUnixNano: "2000000"
+                - asInt: "0"
+                  attributes:
+                    - key: power_state
+                      value:
+                        stringValue: "suspended"
+                  startTimeUnixNano: "1000000"
+                  timeUnixNano: "2000000"
             unit: '{virtual_machines}'
         scope:
           name: otelcol/vcenterreceiver