Update cpu resource metrics to handle resize

.chloggen/k8s_container_cpu_metrics.yaml

@@ -0,0 +1,24 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users 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: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: k8s
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Update CPU metrics for container CPU limit and request to handle resize.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [3558]
+
+# (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: |
+  Introduced new metrics for container CPU limit and request that account for
+  KEP 1287 allowing for in-place updates of container resources.

docs/non-normative/k8s-migration.md

@@ -323,28 +323,32 @@ receiver were introduced as semantic conventions in:
 available)
 - [#2074](https://github.com/open-telemetry/semantic-conventions/issues/2074)
 - [#2197](https://github.com/open-telemetry/semantic-conventions/issues/2197)
+- [#3558](https://github.com/open-telemetry/semantic-conventions/issues/3558) (CPU resize: desired/current split)
+- [#3559](https://github.com/open-telemetry/semantic-conventions/pull/3559)
 
 The changes in their metrics are the following:
 
 <!-- prettier-ignore-start -->
 
-| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New                                                               |
+| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New (SemConv) |
 | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `k8s.container.cpu_limit`              (type: `gauge`)                             | `k8s.container.cpu.limit`       (type: `updowncounter`)           |
-| `k8s.container.cpu_request`             (type: `gauge`)                            | `k8s.container.cpu.request`     (type: `updowncounter`)           |
-| `k8s.container.memory_limit`            (type: `gauge`)                            | `k8s.container.memory.limit`     (type: `updowncounter`)          |
-| `k8s.container.memory_request`           (type: `gauge`)                           | `k8s.container.memory.request`    (type: `updowncounter`)         |
-| `k8s.container.storage_limit`             (type: `gauge`)                          | `k8s.container.storage.limit`     (type: `updowncounter`)         |
-| `k8s.container.storage_request`           (type: `gauge`)                          | `k8s.container.storage.request`    (type: `updowncounter`)        |
-| `k8s.container.ephemeralstorage_limit`      (type: `gauge`)                        | `k8s.container.ephemeral_storage.limit`  (type: `updowncounter`)  |
-| `k8s.container.ephemeralstorage_request`     (type: `gauge`)                       | `k8s.container.ephemeral_storage.request` (type: `updowncounter`) |
-| `k8s.container.restarts`                  (type: `gauge`)                          | `k8s.container.restart.count` (type: `updowncounter`)             |
-| `k8s.container.ready`                  (type: `gauge`)                             | `k8s.container.ready` (type: `updowncounter`)                     |
-| `k8s.container.cpu_limit_utilization` (type: `gauge`)                              | `k8s.container.cpu.limit_utilization` (type: `gauge`)             |
-| `k8s.container.cpu_request_utilization` (type: `gauge`)                            | `k8s.container.cpu.request_utilization` (type: `gauge`)           |
+| `k8s.container.cpu_limit` (type: `gauge`) | `k8s.container.cpu.limit.desired`, `k8s.container.cpu.limit.current` (type: `updowncounter`) |
+| `k8s.container.cpu_request` (type: `gauge`) | `k8s.container.cpu.request.desired`, `k8s.container.cpu.request.current` (type: `updowncounter`) |
+| `k8s.container.memory_limit` (type: `gauge`) | `k8s.container.memory.limit` (type: `updowncounter`) |
+| `k8s.container.memory_request` (type: `gauge`) | `k8s.container.memory.request` (type: `updowncounter`) |
+| `k8s.container.storage_limit` (type: `gauge`) | `k8s.container.storage.limit` (type: `updowncounter`) |
+| `k8s.container.storage_request` (type: `gauge`) | `k8s.container.storage.request` (type: `updowncounter`) |
+| `k8s.container.ephemeralstorage_limit` (type: `gauge`) | `k8s.container.ephemeral_storage.limit` (type: `updowncounter`) |
+| `k8s.container.ephemeralstorage_request` (type: `gauge`) | `k8s.container.ephemeral_storage.request` (type: `updowncounter`) |
+| `k8s.container.restarts` (type: `gauge`) | `k8s.container.restart.count` (type: `updowncounter`) |
+| `k8s.container.ready` (type: `gauge`) | `k8s.container.ready` (type: `updowncounter`) |
+| `k8s.container.cpu_limit_utilization` (type: `gauge`) | `k8s.container.cpu.limit.utilization` (type: `gauge`) |
+| `k8s.container.cpu_request_utilization` (type: `gauge`) | `k8s.container.cpu.request.utilization` (type: `gauge`) |
 
 <!-- prettier-ignore-end -->
 
+**Note:** For CPU limit and request, SemConv splits each into `desired` (from spec) and `actual` (from container status) to support [K8s container resource resize](https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/).
+
 ### K8s ResourceQuota metrics
 
 The K8s ResourceQuota metrics implemented by the Collector and specifically the

docs/system/k8s-metrics.md

@@ -99,10 +99,12 @@ and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`.
 - [Namespace metrics](#namespace-metrics)
   - [Metric: `k8s.namespace.phase`](#metric-k8snamespacephase)
 - [K8s Container metrics](#k8s-container-metrics)
-  - [Metric: `k8s.container.cpu.limit_utilization`](#metric-k8scontainercpulimit_utilization)
-  - [Metric: `k8s.container.cpu.request_utilization`](#metric-k8scontainercpurequest_utilization)
-  - [Metric: `k8s.container.cpu.limit`](#metric-k8scontainercpulimit)
-  - [Metric: `k8s.container.cpu.request`](#metric-k8scontainercpurequest)
+  - [Metric: `k8s.container.cpu.limit.desired`](#metric-k8scontainercpulimitdesired)
+  - [Metric: `k8s.container.cpu.limit.current`](#metric-k8scontainercpulimitcurrent)
+  - [Metric: `k8s.container.cpu.limit.utilization`](#metric-k8scontainercpulimitutilization)
+  - [Metric: `k8s.container.cpu.request.desired`](#metric-k8scontainercpurequestdesired)
+  - [Metric: `k8s.container.cpu.request.current`](#metric-k8scontainercpurequestcurrent)
+  - [Metric: `k8s.container.cpu.request.utilization`](#metric-k8scontainercpurequestutilization)
   - [Metric: `k8s.container.memory.limit`](#metric-k8scontainermemorylimit)
   - [Metric: `k8s.container.memory.request`](#metric-k8scontainermemoryrequest)
   - [Metric: `k8s.container.storage.limit`](#metric-k8scontainerstoragelimit)
@@ -1955,83 +1957,137 @@ This metric is [recommended][MetricRecommended].
 
 **Description:** K8s Container level metrics captured under the namespace `k8s.container`.
 
-### Metric: `k8s.container.cpu.limit_utilization`
+### Metric: `k8s.container.cpu.limit.desired`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.k8s.container.cpu.limit.desired -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
+| -------- | --------------- | ----------- | -------------- | --------- | ------ |
+| `k8s.container.cpu.limit.desired` | UpDownCounter | `{cpu}` | Maximum CPU resource limit as defined by the container spec. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+
+**[1]:** This metric aligns with the limit in the
+[`resources`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#resourcerequirements-v1-core) field of
+[K8s Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#container-v1-core)
+(spec.containers[*].resources). Also see `Desired Resources` in
+<https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/> for more details.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `k8s.container.cpu.limit.current`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.k8s.container.cpu.limit_utilization -->
+<!-- semconv metric.k8s.container.cpu.limit.current -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
 
 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `k8s.container.cpu.limit_utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU limit. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+| `k8s.container.cpu.limit.current` | UpDownCounter | `{cpu}` | Maximum CPU resource limit currently configured for a running container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
 
-**[1]:** The value range is [0.0,1.0]. A value of 1.0 means the container is using 100% of its CPU limit. If the CPU limit is not set, this metric SHOULD NOT be emitted for that container.
+**[1]:** This metric aligns with the limit in the
+[`resources`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#resourcerequirements-v1-core) field of
+[K8s ContainerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#containerstatus-v1-core)
+(status.containerStatuses[*].resources). Also see `Actual Resources` in
+<https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/> for more details.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `k8s.container.cpu.request_utilization`
+### Metric: `k8s.container.cpu.limit.utilization`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.k8s.container.cpu.request_utilization -->
+<!-- semconv metric.k8s.container.cpu.limit.utilization -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
 
 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `k8s.container.cpu.request_utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU request. | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+| `k8s.container.cpu.limit.utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU current limit as defined by <https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#containerstatus-v1-core>. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+
+**[1]:** The value range is [0.0,1.0]. A value of 1.0 means the container is using 100% of its actual CPU limit.
+If the CPU limit is not set, this metric SHOULD NOT be emitted for that container.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `k8s.container.cpu.limit`
+### Metric: `k8s.container.cpu.request.desired`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.k8s.container.cpu.request.desired -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
+| -------- | --------------- | ----------- | -------------- | --------- | ------ |
+| `k8s.container.cpu.request.desired` | UpDownCounter | `{cpu}` | CPU resource requested as defined by the container spec. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+
+**[1]:** This metric aligns with the request in the
+[`resources`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#resourcerequirements-v1-core) field of
+[K8s Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#container-v1-core)
+(spec.containers[*].resources). Also see `Desired Resources` in
+<https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/> for more details.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `k8s.container.cpu.request.current`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- markdownlint-disable -->
-<!-- semconv metric.k8s.container.cpu.limit -->
+<!-- semconv metric.k8s.container.cpu.request.current -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
 
 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `k8s.container.cpu.limit` | UpDownCounter | `{cpu}` | Maximum CPU resource limit set for the container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+| `k8s.container.cpu.request.current` | UpDownCounter | `{cpu}` | CPU resource requested currently configured for a running container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
 
-**[1]:** See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#resourcerequirements-v1-core for details.
+**[1]:** This metric aligns with the request in the
+[`resources`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#resourcerequirements-v1-core) field of
+[K8s ContainerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#containerstatus-v1-core)
+(status.containerStatuses[*].resources). Also see `Actual Resources` in
+<https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/> for more details.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore-->
 
-### Metric: `k8s.container.cpu.request`
+### Metric: `k8s.container.cpu.request.utilization`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- markdownlint-disable -->
-<!-- semconv metric.k8s.container.cpu.request -->
+<!-- semconv metric.k8s.container.cpu.request.utilization -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
 
 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `k8s.container.cpu.request` | UpDownCounter | `{cpu}` | CPU resource requested for the container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
+| `k8s.container.cpu.request.utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU current request as defined by <https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#containerstatus-v1-core>. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.container`](/docs/registry/entities/k8s.md#k8s-container) |
 
-**[1]:** See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#resourcerequirements-v1-core for details.
+**[1]:** The value range is [0.0,1.0]. A value of 1.0 means the container is using 100% of its actual CPU request.
+If the CPU request is not set, this metric SHOULD NOT be emitted for that container.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore-->
 
 ### Metric: `k8s.container.memory.limit`
 

model/k8s/deprecated/metrics-deprecated.yaml

@@ -510,3 +510,64 @@ groups:
       - k8s.node
     instrument: updowncounter
     unit: "By"
+
+  - id: metric.k8s.container.cpu.limit
+    type: metric
+    metric_name: k8s.container.cpu.limit
+    annotations:
+      code_generation:
+        metric_value_type: double
+    stability: development
+    deprecated:
+      reason: renamed
+      renamed_to: k8s.container.cpu.limit.desired
+    brief: "Deprecated, use `k8s.container.cpu.limit.desired` and `k8s.container.cpu.limit.current` instead."
+    entity_associations:
+      - k8s.container
+    instrument: updowncounter
+    unit: "{cpu}"
+  - id: metric.k8s.container.cpu.limit_utilization
+    type: metric
+    metric_name: k8s.container.cpu.limit_utilization
+    annotations:
+      code_generation:
+        metric_value_type: double
+    stability: development
+    deprecated:
+      reason: renamed
+      renamed_to: k8s.container.cpu.limit.utilization
+    brief: "Deprecated, use `k8s.container.cpu.limit.utilization` instead."
+    entity_associations:
+      - k8s.container
+    instrument: gauge
+    unit: "1"
+  - id: metric.k8s.container.cpu.request
+    type: metric
+    metric_name: k8s.container.cpu.request
+    annotations:
+      code_generation:
+        metric_value_type: double
+    stability: development
+    deprecated:
+      reason: renamed
+      renamed_to: k8s.container.cpu.request.desired
+    brief: "Deprecated, use `k8s.container.cpu.request.desired` and `k8s.container.cpu.request.current` instead."
+    entity_associations:
+      - k8s.container
+    instrument: updowncounter
+    unit: "{cpu}"
+  - id: metric.k8s.container.cpu.request_utilization
+    type: metric
+    metric_name: k8s.container.cpu.request_utilization
+    annotations:
+      code_generation:
+        metric_value_type: double
+    stability: development
+    deprecated:
+      reason: renamed
+      renamed_to: k8s.container.cpu.request.utilization
+    brief: "Deprecated, use `k8s.container.cpu.request.utilization` instead."
+    entity_associations:
+      - k8s.container
+    instrument: gauge
+    unit: "1"