[receiver/kubeletstats] Add feature gate for cpu utilization metrics'…

… deprecation (open-telemetry#35139)

**Description:** 

This PR adds a feature gate as discussed at
open-telemetry#27885 (comment).
If the feature gate is enabled the `container.cpu.utilization`,
`k8s.pod.cpu.utilization` and `k8s.node.cpu.utilization` metrics will be
not be disabled being replaced by the `container.cpu.usage`,
`k8s.pod.cpu.usage` and `k8s.node.cpu.usage`.

### Feature gate schedule

- alpha: when enabled it makes the .cpu.usage metrics enabled by default
- beta: .cpu.usage metrics are enabled by default and any configuration
enabling the deprecated .cpu.utilization metrics will be failing.
Explicitly disabling the feature gate provides the old (deprecated)
behavior.
- stable: .cpu.usage metrics are enabled by default and the deprecated
metrics are completely removed.
- Removed three releases after `stable`.

**Documentation:**

### How to test this

1. Using the following configuration
```yaml
mode: daemonset
presets:
  kubeletMetrics:
    enabled: true

image:
  repository: otelcontribcol-dev
  tag: "latest"
  pullPolicy: IfNotPresent

command:
  name: otelcontribcol
  extraArgs: [--feature-gates=receiver.kubeletstats.enableCPUUsageMetrics]

config:
  exporters:
    debug:
      verbosity: normal
  receivers:
    kubeletstats:
      collection_interval: 10s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true

  service:
    pipelines:
      metrics:
        receivers: [kubeletstats]
        processors: [batch]
        exporters: [debug]
```
2. Ensure that only the `.cpu.usage` metrics are reported.
3. Disable the feature gate and check that only the `.cpu.utilization`
metrics are reported.

---------

Signed-off-by: ChrsMark <chrismarkou92@gmail.com>

.chloggen/kubeletstats_featuregate_metrics.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: kubeletstats
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Introduce feature gate for deprecation of container.cpu.utilization, k8s.pod.cpu.utilization and k8s.node.cpu.utilization metrics
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [35139]
+
+# (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/kubeletstatsreceiver/README.md

@@ -285,3 +285,23 @@ rules:
     resources: ["nodes/proxy"]
     verbs: ["get"]
 ```
+
+### Warning about metrics' deprecation
+
+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.
+
+#### `receiver.kubeletstats.enableCPUUsageMetrics` feature gate
+
+- alpha: when enabled it makes the `.cpu.usage` metrics enabled by default, disabling the `.cpu.utilization` metrics
+- beta: `.cpu.usage` metrics are enabled by default and any configuration enabling the deprecated `.cpu.utilization` metrics will be failing. Explicitly disabling the feature gate provides the old (deprecated) behavior.
+- stable: `.cpu.usage` metrics are enabled by default and the deprecated metrics are completely removed.
+- removed three releases after stable.
+
+More information about the deprecation plan and
+the background reasoning can be found at https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/27885.

receiver/kubeletstatsreceiver/factory.go

@@ -9,6 +9,7 @@ import (
 
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/consumer"
+	"go.opentelemetry.io/collector/featuregate"
 	"go.opentelemetry.io/collector/receiver"
 	"go.opentelemetry.io/collector/receiver/scraperhelper"
 	"go.uber.org/zap"
@@ -20,7 +21,16 @@ import (
 )
 
 const (
-	metricGroupsConfig = "metric_groups"
+	metricGroupsConfig               = "metric_groups"
+	enableCPUUsageMetricsFeatureFlag = "receiver.kubeletstats.enableCPUUsageMetrics"
+)
+
+var enableCPUUsageMetrics = featuregate.GlobalRegistry().MustRegister(
+	enableCPUUsageMetricsFeatureFlag,
+	featuregate.StageAlpha,
+	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"),
 )
 
 var defaultMetricGroups = []kubelet.MetricGroup{
@@ -68,6 +78,31 @@ func createMetricsReceiver(
 		return nil, err
 	}
 
+	if enableCPUUsageMetrics.IsEnabled() {
+		if cfg.MetricsBuilderConfig.Metrics.ContainerCPUUtilization.Enabled {
+			cfg.MetricsBuilderConfig.Metrics.ContainerCPUUtilization.Enabled = false
+			cfg.MetricsBuilderConfig.Metrics.ContainerCPUUsage.Enabled = true
+		}
+		if cfg.MetricsBuilderConfig.Metrics.K8sPodCPUUtilization.Enabled {
+			cfg.MetricsBuilderConfig.Metrics.K8sPodCPUUtilization.Enabled = false
+			cfg.MetricsBuilderConfig.Metrics.K8sPodCPUUsage.Enabled = true
+		}
+		if cfg.MetricsBuilderConfig.Metrics.K8sNodeCPUUtilization.Enabled {
+			cfg.MetricsBuilderConfig.Metrics.K8sNodeCPUUtilization.Enabled = false
+			cfg.MetricsBuilderConfig.Metrics.K8sNodeCPUUsage.Enabled = true
+		}
+	} else {
+		if cfg.MetricsBuilderConfig.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.MetricsBuilderConfig.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.MetricsBuilderConfig.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 := newKubletScraper(rest, set, rOptions, cfg.MetricsBuilderConfig, cfg.NodeName)
 	if err != nil {
 		return nil, err

receiver/kubeletstatsreceiver/go.mod

@@ -17,6 +17,7 @@ require (
 	go.opentelemetry.io/collector/confmap v1.16.0
 	go.opentelemetry.io/collector/consumer v0.110.0
 	go.opentelemetry.io/collector/consumer/consumertest v0.110.0
+	go.opentelemetry.io/collector/featuregate v1.16.0
 	go.opentelemetry.io/collector/filter v0.110.0
 	go.opentelemetry.io/collector/pdata v1.16.0
 	go.opentelemetry.io/collector/pipeline v0.110.0
@@ -56,6 +57,7 @@ require (
 	github.com/golang/snappy v0.0.4 // indirect
 	github.com/google/gnostic-models v0.6.8 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/hashicorp/go-version v1.7.0 // indirect
 	github.com/imdario/mergo v0.3.11 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect

receiver/kubeletstatsreceiver/metadata.yaml

@@ -92,7 +92,7 @@ metrics:
     enabled: true
     description: "Node CPU utilization"
     warnings:
-      if_enabled: "WARNING: This metric will be disabled in a future release. Use metric k8s.node.cpu.usage instead."
+      if_enabled: "This metric will be disabled in a future release. Use metric k8s.node.cpu.usage instead."
     unit: "1"
     gauge:
       value_type: double
@@ -364,7 +364,7 @@ metrics:
     enabled: true
     description: "Container CPU utilization"
     warnings:
-      if_enabled: "WARNING: This metric will be disabled in a future release. Use metric container.cpu.usage instead."
+      if_enabled: "This metric will be disabled in a future release. Use metric container.cpu.usage instead."
     unit: "1"
     gauge:
       value_type: double