[receiver/dockerstats] adding renamed cpu_utilization metric (open-te…

…lemetry#22823)

This change starts the process for deprecating the metric container.cpu.percent in favor of container.cpu.utilization to adhere to semantic convention.

At this step introducing the new metric name disabled by default, leaving the old metric enabled

.chloggen/change_cpu_percentage_naming.yaml

@@ -0,0 +1,26 @@
+# 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: dockerstatsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "cpu.container.percent metric will be deprecated in v0.79.0 in favor of container.cpu.utilization"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [21807]
+
+# (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 incorrect metric name:
+  - `container.cpu.utilization`
+  and replacing it with the names adhering to the semantic conventions:
+  - `container.cpu.percent`
+  At this stage, the new metric is added, but is disabled by default.
+  See the "Deprecations" section of the Docker Stats receiver's README for details.

receiver/dockerstatsreceiver/README.md

@@ -70,6 +70,40 @@ receivers:
 The full list of settings exposed for this receiver are documented [here](./config.go)
 with detailed sample configurations [here](./testdata/config.yaml).
 
+## Deprecations
+
+### Transition to cpu utilization metric name aligned with OpenTelemetry specification
+
+The Docker Stats receiver has been emitting the following cpu memory metric:
+
+- [container.cpu.percent] for the percentage of CPU used by the container,
+
+This is in conflict with the OpenTelemetry specification,
+which defines [container.cpu.utilization] as the name for this metric.
+
+To align the emitted metric names with the OpenTelemetry specification,
+the following process will be followed to phase out the old metrics:
+
+- Between `v0.79.0` and `v0.81.0`, the new metric is introduced and the old metric is marked as deprecated.
+  Only the old metric are emitted by default.
+- Between `v0.82.0` and `v0.84.0`, the old metric is disabled and the new one enabled by default.
+- In `v0.85.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:
+  docker_stats:
+    metrics:
+      container.cpu.percent:
+        enabled: false
+      container.cpu.utilization:
+        enabled: true
+
+```
+
 ### Migrating from ScraperV1 to ScraperV2
 
 *Note: These changes are now in effect and ScraperV1 have been removed as of v0.71.*

receiver/dockerstatsreceiver/documentation.md

@@ -32,7 +32,7 @@ Number of bytes transferred to/from the disk by the group and descendant groups.
 
 ### container.cpu.percent
 
-Percent of CPU used by the container.
+Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |
@@ -334,6 +334,14 @@ Note this is the usage for the system, not the container.
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | ns | Sum | Int | Cumulative | true |
 
+### container.cpu.utilization
+
+Percent of CPU used by the container.
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| 1 | Gauge | Double |
+
 ### container.memory.active_anon
 
 The amount of anonymous memory that has been identified as active by the kernel.

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

@@ -35,6 +35,8 @@ all_set:
       enabled: true
     container.cpu.usage.usermode:
       enabled: true
+    container.cpu.utilization:
+      enabled: true
     container.memory.active_anon:
       enabled: true
     container.memory.active_file:
@@ -174,6 +176,8 @@ none_set:
       enabled: false
     container.cpu.usage.usermode:
       enabled: false
+    container.cpu.utilization:
+      enabled: false
     container.memory.active_anon:
       enabled: false
     container.memory.active_file:

receiver/dockerstatsreceiver/metadata.yaml

@@ -121,10 +121,20 @@ metrics:
       value_type: int
       monotonic: true
       aggregation: cumulative
+  container.cpu.utilization:
+    enabled: false
+    description: "Percent of CPU used by the container."
+    unit: "1"
+    warnings:
+      if_enabled_not_set: This metric will be enabled by default in v0.82.0.
+    gauge:
+      value_type: double
   container.cpu.percent:
     enabled: true
-    description: "Percent of CPU used by the container."
+    description: "Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container."
     unit: "1"
+    warnings:
+      if_enabled: This metric will be disabled in v0.82.0 and removed in v0.85.0.
     gauge:
       value_type: double
 

receiver/dockerstatsreceiver/receiver.go

@@ -248,6 +248,7 @@ func (r *receiver) recordCPUMetrics(now pcommon.Timestamp, cpuStats *dtypes.CPUS
 	r.mb.RecordContainerCPUThrottlingDataThrottledPeriodsDataPoint(now, int64(cpuStats.ThrottlingData.ThrottledPeriods))
 	r.mb.RecordContainerCPUThrottlingDataPeriodsDataPoint(now, int64(cpuStats.ThrottlingData.Periods))
 	r.mb.RecordContainerCPUThrottlingDataThrottledTimeDataPoint(now, int64(cpuStats.ThrottlingData.ThrottledTime))
+	r.mb.RecordContainerCPUUtilizationDataPoint(now, calculateCPUPercent(prevStats, cpuStats))
 	r.mb.RecordContainerCPUPercentDataPoint(now, calculateCPUPercent(prevStats, cpuStats))
 
 	for coreNum, v := range cpuStats.CPUUsage.PercpuUsage {

receiver/dockerstatsreceiver/testdata/mock/cgroups_v2/expected_metrics.yaml

@@ -52,7 +52,7 @@ resourceMetrics:
                   timeUnixNano: "1682426015943175000"
               isMonotonic: true
             unit: By
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0.041326615629205886

receiver/dockerstatsreceiver/testdata/mock/no_pids_stats/expected_metrics.yaml

@@ -195,7 +195,7 @@ resourceMetrics:
                   timeUnixNano: "1683723817613281000"
               isMonotonic: true
             unit: '{operations}'
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0.0002888012543185477

receiver/dockerstatsreceiver/testdata/mock/pids_stats_max/expected_metrics.yaml

@@ -104,7 +104,7 @@ resourceMetrics:
                   timeUnixNano: "1683723781130612000"
               isMonotonic: true
             unit: By
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0

receiver/dockerstatsreceiver/testdata/mock/single_container/expected_metrics.yaml

@@ -201,7 +201,7 @@ resourceMetrics:
                   timeUnixNano: "1661128093795620000"
               isMonotonic: true
             unit: '{operations}'
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0.0002888012543185477

receiver/dockerstatsreceiver/testdata/mock/two_containers/expected_metrics.yaml

@@ -195,7 +195,7 @@ resourceMetrics:
                   timeUnixNano: "1661128790158163000"
               isMonotonic: true
             unit: '{operations}'
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0
@@ -884,7 +884,7 @@ resourceMetrics:
                   timeUnixNano: "1661128790158163000"
               isMonotonic: true
             unit: '{operations}'
-          - description: Percent of CPU used by the container.
+          - description: 'Deprecated: use `container.cpu.utilization` metric instead. Percent of CPU used by the container.'
             gauge:
               dataPoints:
                 - asDouble: 0