[receiver/dockerstats] adding renamed cpu_utilization metric

.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
@@ -885,7 +885,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