[receiver/kubeletstats] Move receiver.kubeletstats.enableCPUUsageMetrics feature gate to beta (#39488)

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #39487
Related to
#27885

---------

Signed-off-by: odubajDT <[email protected]>

Author: odubajDT

.chloggen/kubeletstats-feature-gate.yaml

@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: receiver/kubeletstats
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Move receiver.kubeletstats.enableCPUUsageMetrics feature gate to beta
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [39487]
+
+# (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: | 
+  Deprecated metrics `container.cpu.utilization`, `k8s.pod.cpu.utilization` and `k8s.node.cpu.utilization` are being replaced
+  by `container.cpu.usage`, `k8s.pod.cpu.usage` and `k8s.node.cpu.usage`.
+  To be able to use the deprecated metrics, switch `receiver.kubeletstats.enableCPUUsageMetrics` feature gate to `false`.
+
+# 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: []

receiver/kubeletstatsreceiver/README.md

@@ -16,6 +16,10 @@
 The Kubelet Stats Receiver pulls node, pod, container, and volume metrics from the API server on a kubelet
 and sends it down the metric pipeline for further processing.
 
+> [!WARNING]
+> The `receiver.kubeletstats.enableCPUUsageMetrics` feature gate was moved to stage `Beta` what results in a breaking change in metrics names.
+> For more information which metrics are affected see [here](#metrics-deprecation).
+
 ## 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)
@@ -308,16 +312,19 @@ rules:
     verbs: ["get"]
 ```
 
-### Warning about metrics' deprecation
+### Metrics deprecation
+
+The following metrics were deprecated and renamed from version `v0.125.0`:
 
-The following metrics will be renamed in a future version:
 - `k8s.node.cpu.utilization` (renamed to `k8s.node.cpu.usage`)
 - `k8s.pod.cpu.utilization` (renamed to `k8s.pod.cpu.usage`)
 - `container.cpu.utilization` (renamed to `container.cpu.usage`)
 
 The above metrics show usage counted in CPUs and it's not a percentage of used resources.
 These metrics were previously incorrectly named using the utilization term.
 
+You can enable the usage of the deprecated metrics by disabling the `receiver.kubeletstats.enableCPUUsageMetrics` feature gate.
+
 #### `receiver.kubeletstats.enableCPUUsageMetrics` feature gate
 
 - alpha: when enabled it makes the `.cpu.usage` metrics enabled by default, disabling the `.cpu.utilization` metrics

receiver/kubeletstatsreceiver/documentation.md

@@ -20,13 +20,13 @@ Total cumulative CPU time (sum of all cores) spent by the container/pod/node sin
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | s | Sum | Double | Cumulative | true |
 
-### container.cpu.utilization
+### container.cpu.usage
 
-Container CPU utilization
+Total CPU usage (sum of all cores per second) averaged over the sample window
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| 1 | Gauge | Double |
+| {cpu} | Gauge | Double |
 
 ### container.filesystem.available
 
@@ -108,13 +108,13 @@ Total cumulative CPU time (sum of all cores) spent by the container/pod/node sin
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | s | Sum | Double | Cumulative | true |
 
-### k8s.node.cpu.utilization
+### k8s.node.cpu.usage
 
-Node CPU utilization
+Total CPU usage (sum of all cores per second) averaged over the sample window
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| 1 | Gauge | Double |
+| {cpu} | Gauge | Double |
 
 ### k8s.node.filesystem.available
 
@@ -226,13 +226,13 @@ Total cumulative CPU time (sum of all cores) spent by the container/pod/node sin
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | s | Sum | Double | Cumulative | true |
 
-### k8s.pod.cpu.utilization
+### k8s.pod.cpu.usage
 
-Pod CPU utilization
+Total CPU usage (sum of all cores per second) averaged over the sample window
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| 1 | Gauge | Double |
+| {cpu} | Gauge | Double |
 
 ### k8s.pod.filesystem.available
 
@@ -386,13 +386,13 @@ metrics:
     enabled: true
 ```
 
-### container.cpu.usage
+### container.cpu.utilization
 
-Total CPU usage (sum of all cores per second) averaged over the sample window
+Container CPU utilization
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| {cpu} | Gauge | Double |
+| 1 | Gauge | Double |
 
 ### container.uptime
 
@@ -450,13 +450,13 @@ Container memory utilization as a ratio of the container's requests
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Double |
 
-### k8s.node.cpu.usage
+### k8s.node.cpu.utilization
 
-Total CPU usage (sum of all cores per second) averaged over the sample window
+Node CPU utilization
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| {cpu} | Gauge | Double |
+| 1 | Gauge | Double |
 
 ### k8s.node.uptime
 
@@ -474,13 +474,13 @@ Pod cpu utilization as a ratio of the node's capacity
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Double |
 
-### k8s.pod.cpu.usage
+### k8s.pod.cpu.utilization
 
-Total CPU usage (sum of all cores per second) averaged over the sample window
+Pod CPU utilization
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
-| {cpu} | Gauge | Double |
+| 1 | Gauge | Double |
 
 ### k8s.pod.cpu_limit_utilization
 

receiver/kubeletstatsreceiver/factory.go

@@ -25,9 +25,9 @@ const (
 	enableCPUUsageMetricsFeatureFlag = "receiver.kubeletstats.enableCPUUsageMetrics"
 )
 
-var enableCPUUsageMetrics = featuregate.GlobalRegistry().MustRegister(
+var EnableCPUUsageMetrics = featuregate.GlobalRegistry().MustRegister(
 	enableCPUUsageMetricsFeatureFlag,
-	featuregate.StageAlpha,
+	featuregate.StageBeta,
 	featuregate.WithRegisterDescription("When enabled the container.cpu.utilization, k8s.pod.cpu.utilization and k8s.node.cpu.utilization metrics will be replaced by the container.cpu.usage, k8s.pod.cpu.usage and k8s.node.cpu.usage"),
 	featuregate.WithRegisterFromVersion("v0.110.0"),
 	featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/27885"),
@@ -78,31 +78,6 @@ func createMetricsReceiver(
 		return nil, err
 	}
 
-	if enableCPUUsageMetrics.IsEnabled() {
-		if cfg.Metrics.ContainerCPUUtilization.Enabled {
-			cfg.Metrics.ContainerCPUUtilization.Enabled = false
-			cfg.Metrics.ContainerCPUUsage.Enabled = true
-		}
-		if cfg.Metrics.K8sPodCPUUtilization.Enabled {
-			cfg.Metrics.K8sPodCPUUtilization.Enabled = false
-			cfg.Metrics.K8sPodCPUUsage.Enabled = true
-		}
-		if cfg.Metrics.K8sNodeCPUUtilization.Enabled {
-			cfg.Metrics.K8sNodeCPUUtilization.Enabled = false
-			cfg.Metrics.K8sNodeCPUUsage.Enabled = true
-		}
-	} else {
-		if cfg.Metrics.ContainerCPUUtilization.Enabled {
-			set.Logger.Warn("The default metric container.cpu.utilization is being replaced by the container.cpu.usage metric. Switch now by enabling the receiver.kubeletstats.enableCPUUsageMetrics feature gate.")
-		}
-		if cfg.Metrics.K8sPodCPUUtilization.Enabled {
-			set.Logger.Warn("The default metric k8s.pod.cpu.utilization is being replaced by the k8s.pod.cpu.usage metric. Switch now by enabling the receiver.kubeletstats.enableCPUUsageMetrics feature gate.")
-		}
-		if cfg.Metrics.K8sNodeCPUUtilization.Enabled {
-			set.Logger.Warn("The default metric k8s.node.cpu.utilization is being replaced by the k8s.node.cpu.usage metric. Switch now by enabling the receiver.kubeletstats.enableCPUUsageMetrics feature gate.")
-		}
-	}
-
 	scrp, err := newKubeletScraper(rest, set, rOptions, cfg.MetricsBuilderConfig, cfg.NodeName)
 	if err != nil {
 		return nil, err

receiver/kubeletstatsreceiver/internal/metadata/generated_config.go

@@ -82,17 +82,15 @@ attributes:
 
 metrics:
   k8s.node.cpu.usage:
-    enabled: false
+    enabled: true
     description: "Total CPU usage (sum of all cores per second) averaged over the sample window"
     unit: "{cpu}"
     gauge:
       value_type: double
     attributes: []
   k8s.node.cpu.utilization:
-    enabled: true
+    enabled: false
     description: "Node CPU utilization"
-    warnings:
-      if_enabled: "This metric will be disabled in a future release. Use metric k8s.node.cpu.usage instead."
     unit: "1"
     gauge:
       value_type: double
@@ -197,17 +195,15 @@ metrics:
       aggregation_temporality: cumulative
     attributes: []
   k8s.pod.cpu.usage:
-    enabled: false
+    enabled: true
     description: "Total CPU usage (sum of all cores per second) averaged over the sample window"
     unit: "{cpu}"
     gauge:
       value_type: double
     attributes: [ ]
   k8s.pod.cpu.utilization:
-    enabled: true
+    enabled: false
     description: "Pod CPU utilization"
-    warnings:
-      if_enabled: "This metric will be disabled in a future release. Use metric k8s.pod.cpu.usage instead."
     unit: "1"
     gauge:
       value_type: double
@@ -354,17 +350,15 @@ metrics:
       aggregation_temporality: cumulative
     attributes: []
   container.cpu.usage:
-    enabled: false
+    enabled: true
     description: "Total CPU usage (sum of all cores per second) averaged over the sample window"
     unit: "{cpu}"
     gauge:
       value_type: double
     attributes: [ ]
   container.cpu.utilization:
-    enabled: true
+    enabled: false
     description: "Container CPU utilization"
-    warnings:
-      if_enabled: "This metric will be disabled in a future release. Use metric container.cpu.usage instead."
     unit: "1"
     gauge:
       value_type: double