[receiver/kubeletstatsreceiver] prepend container. metrics with k8s.

This PR introduces `k8s.container*` metrics, which will replace their `container.*` metrics counterparts. For now, the `k8s.container*` metrics are disabled by default.

The following process will be followed to phase out the old metrics:
- In `v0.82.0`, the new metric is introduced and the old metric is marked as deprecated.
  Only the old metric are emitted by default.
- In `v0.84.0`, the old metric is disabled and the new one enabled by default.
- In `v0.86.0` and up, the old metric is removed.

Please refer to the following issue: open-telemetry#24238 for the reason for this change.

.chloggen/kubeletstatsreceiver-struct-changes.yaml

@@ -0,0 +1,20 @@
+# Use this changelog template to create an entry for release notes.
+# If your change doesn't affect end users, such as a test fix or a tooling change,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+
+# 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: kubeletstatsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Change the type from RecordDoubleDataPointFunc to []RecordDoubleDataPointFunc for CPUMetrics.{Time,Utilization}, and from RecordIntDataPointFunc to []RecordIntDataPointFunc for MemoryMetrics.{Available,Usage,Rss,WorkingSet,PageFaults,MajorPageFaults} and FilesystemMetrics.{Available,Capacity,Usage}.  
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [24238]
+
+# (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:

.chloggen/prepend-container-metrics-k8s.yaml

@@ -0,0 +1,46 @@
+# Use this changelog template to create an entry for release notes.
+# If your change doesn't affect end users, such as a test fix or a tooling change,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: kubestatsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: container.* metrics will be deprecated in v0.82.0 in favor of their k8s.container.* counterparts
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [24238]
+
+# (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: |
+  This starts the process of phasing out container.* metrics:
+  - `container.cpu.utilization`
+  - `container.cpu.time`
+  - `container.memory.available`
+  - `container.memory.usage`
+  - `container.memory.rss`
+  - `container.memory.working_set`
+  - `container.memory.page_faults`
+  - `container.memory.major_page_faults`
+  - `container.filesystem.available`
+  - `container.filesystem.capacity`
+  - `container.filesystem.usage`
+  and replacing it with their k8s.container* counterparts:
+  - `k8s.container.cpu.utilization`
+  - `k8s.container.cpu.time`
+  - `k8s.container.memory.available`
+  - `k8s.container.memory.usage`
+  - `k8s.container.memory.rss`
+  - `k8s.container.memory.working_set`
+  - `k8s.container.memory.page_faults`
+  - `k8s.container.memory.major_page_faults`
+  - `k8s.container.filesystem.available`
+  - `k8s.container.filesystem.capacity`
+  - `k8s.container.filesystem.usage`
+  At this stage, the new metric is added, but is disabled by default.
+  See the "Deprecations" section of the Kubelet Stats receiver's README for details.

receiver/kubeletstatsreceiver/README.md

@@ -225,3 +225,70 @@ with detailed sample configurations [here](./testdata/config.yaml).
 ## 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)
+
+## Deprecations
+
+### container.* metrics deprecated in favor of k8s.container.* metrics
+
+All `container.*` metrics have been deprecated in favor of their `k8s.container.*` counterparts
+
+The following process will be followed to phase out the old metrics:
+
+- In `v0.82.0`, the new metric is introduced and the old metric is marked as deprecated.
+  Only the old metric are emitted by default.
+- In `v0.84.0`, the old metric is disabled and the new one enabled by default.
+- In `v0.86.0` and up, the old metric is removed.
+
+To change the enabled state for the specific metrics, use the standard configuration options that are available for all metrics.
+
+Here's an example configuration to disable the old metrics and enable the new metrics:
+
+```yaml
+receivers:
+  kubeletstats:
+    metrics:
+      container.cpu.utilization:
+        enabled: false
+      k8s.container.cpu.utilization:
+        enabled: true
+      container.cpu.time:
+        enabled: false
+      k8s.container.cpu.time:
+        enabled: true
+      container.memory.available:
+        enabled: false
+      k8s.container.memory.available:
+        enabled: true
+      container.memory.usage:
+        enabled: false
+      k8s.container.memory.usage:
+        enabled: true
+      container.memory.rss:
+        enabled: false
+      k8s.container.memory.rss:
+        enabled: true
+      container.memory.working_set:
+        enabled: false
+      k8s.container.memory.working_set:
+        enabled: true
+      container.memory.page_faults:
+        enabled: false
+      k8s.container.memory.page_faults:
+        enabled: true
+      container.memory.major_page_faults:
+        enabled: false
+      k8s.container.memory.major_page_faults:
+        enabled: true
+      container.filesystem.available:
+        enabled: false
+      k8s.container.filesystem.available:
+        enabled: true
+      container.filesystem.capacity:
+        enabled: false
+      k8s.container.filesystem.capacity:
+        enabled: true
+      container.filesystem.usage:
+        enabled: false
+      k8s.container.filesystem.usage:
+        enabled: true
+```

receiver/kubeletstatsreceiver/documentation.md

@@ -14,87 +14,87 @@ metrics:
 
 ### container.cpu.time
 
-Container CPU time
+Deprecated: use `k8s.container.cpu.time` metric instead. Container CPU time
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | s | Sum | Double | Cumulative | true |
 
 ### container.cpu.utilization
 
-Container CPU utilization
+Deprecated: use `k8s.container.cpu.utilization` metric instead. Container CPU utilization
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Double |
 
 ### container.filesystem.available
 
-Container filesystem available
+Deprecated: use `k8s.container.filesystem.available` metric instead. Container filesystem available
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.filesystem.capacity
 
-Container filesystem capacity
+Deprecated: use `k8s.container.filesystem.capacity` metric instead. Container filesystem capacity
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.filesystem.usage
 
-Container filesystem usage
+Deprecated: use `k8s.container.filesystem.usage` metric instead. Container filesystem usage
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.memory.available
 
-Container memory available
+Deprecated: use `k8s.container.memory.available` metric instead. Container memory available
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.memory.major_page_faults
 
-Container memory major_page_faults
+Deprecated: use `container.memory.major_page_faults` metric instead. Container memory major_page_faults
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Int |
 
 ### container.memory.page_faults
 
-Container memory page_faults
+Deprecated: use `k8s.container.memory.page_faults` metric instead. Container memory page_faults
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Int |
 
 ### container.memory.rss
 
-Container memory rss
+Deprecated: use `k8s.container.memory.rss` metric instead. Container memory rss
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.memory.usage
 
-Container memory usage
+Deprecated: use `k8s.container.memory.usage` metric instead. Container memory usage
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
 | By | Gauge | Int |
 
 ### container.memory.working_set
 
-Container memory working_set
+Deprecated: use `k8s.container.memory.working_set` metric instead. Container memory working_set
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
@@ -376,6 +376,104 @@ The inodes used by the filesystem. This may not equal inodes - free because file
 | ---- | ----------- | ---------- |
 | 1 | Gauge | Int |
 
+## 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
+```
+
+### k8s.container.cpu.time
+
+Container CPU time
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| s | Sum | Double | Cumulative | true |
+
+### k8s.container.cpu.utilization
+
+Container CPU utilization
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| 1 | Gauge | Double |
+
+### k8s.container.filesystem.available
+
+Container filesystem available
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.filesystem.capacity
+
+Container filesystem capacity
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.filesystem.usage
+
+Container filesystem usage
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.memory.available
+
+Container memory available
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.memory.major_page_faults
+
+Container memory major_page_faults
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| 1 | Gauge | Int |
+
+### k8s.container.memory.page_faults
+
+Container memory page_faults
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| 1 | Gauge | Int |
+
+### k8s.container.memory.rss
+
+Container memory rss
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.memory.usage
+
+Container memory usage
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
+### k8s.container.memory.working_set
+
+Container memory working_set
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| By | Gauge | Int |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

receiver/kubeletstatsreceiver/internal/kubelet/cpu.go

@@ -14,8 +14,12 @@ func addCPUMetrics(mb *metadata.MetricsBuilder, cpuMetrics metadata.CPUMetrics,
 	if s == nil {
 		return
 	}
-	addCPUUsageMetric(mb, cpuMetrics.Utilization, s, currentTime)
-	addCPUTimeMetric(mb, cpuMetrics.Time, s, currentTime)
+	for _, recordDataPoint := range cpuMetrics.Utilization {
+		addCPUUsageMetric(mb, recordDataPoint, s, currentTime)
+	}
+	for _, recordDataPoint := range cpuMetrics.Time {
+		addCPUTimeMetric(mb, recordDataPoint, s, currentTime)
+	}
 }
 
 func addCPUUsageMetric(mb *metadata.MetricsBuilder, recordDataPoint metadata.RecordDoubleDataPointFunc, s *stats.CPUStats, currentTime pcommon.Timestamp) {

receiver/kubeletstatsreceiver/internal/kubelet/fs.go

@@ -14,8 +14,13 @@ func addFilesystemMetrics(mb *metadata.MetricsBuilder, filesystemMetrics metadat
 	if s == nil {
 		return
 	}
-
-	recordIntDataPoint(mb, filesystemMetrics.Available, s.AvailableBytes, currentTime)
-	recordIntDataPoint(mb, filesystemMetrics.Capacity, s.CapacityBytes, currentTime)
-	recordIntDataPoint(mb, filesystemMetrics.Usage, s.UsedBytes, currentTime)
+	for _, recordDataPoint := range filesystemMetrics.Available {
+		recordIntDataPoint(mb, recordDataPoint, s.AvailableBytes, currentTime)
+	}
+	for _, recordDataPoint := range filesystemMetrics.Capacity {
+		recordIntDataPoint(mb, recordDataPoint, s.CapacityBytes, currentTime)
+	}
+	for _, recordDataPoint := range filesystemMetrics.Usage {
+		recordIntDataPoint(mb, recordDataPoint, s.UsedBytes, currentTime)
+	}
 }