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

@@ -59,6 +59,7 @@ and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then:
   - [K8s ResourceQuota resource](#k8s-resourcequota-resource)
   - [K8s ReplicationController resource](#k8s-replicationcontroller-resource)
   - [K8s Container metrics](#k8s-container-metrics)
+    - [Resize CPU and Memory Resources assigned to Containers](#resize-cpu-and-memory-resources-assigned-to-containers)
   - [K8s ResourceQuota metrics](#k8s-resourcequota-metrics)
   - [OpenShift ClusterResourceQuota metrics](#openshift-clusterresourcequota-metrics)
   - [K8s Node condition metrics](#k8s-node-condition-metrics)
@@ -315,6 +316,9 @@ The changes are the following:
 
 ### K8s Container metrics
 
+**Note:** The details below still remain mostly correct. However, due to the introduction of resize for container
+cpu and memory resources, new changes are introduced. Check sub-section [Resize CPU and Memory Resources assigned to Containers](#resize-cpu-and-memory-resources-assigned-to-containers) for more details.
+
 The K8s Container metrics implemented by the Collector and specifically the
 [k8scluster](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.115.0/receiver/k8sclusterreceiver/documentation.md)
 receiver were introduced as semantic conventions in:
@@ -330,8 +334,8 @@ The changes in their metrics are the following:
 
 | Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New                                                               |
 | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `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.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`)         |
@@ -345,6 +349,24 @@ The changes in their metrics are the following:
 
 <!-- prettier-ignore-end -->
 
+#### Resize CPU and Memory Resources assigned to Containers
+
+With the resize of cpu and memory resources being possible, limit and resources now have a desired state and the actual state.
+If k8s is not able to immediately honor the desired state, then actual and desired values might be different.
+
+Issue [#3558](https://github.com/open-telemetry/semantic-conventions/issues/3558) and PRs [] introduce the following metric changes:
+
+<!-- prettier-ignore-start -->
+
+| Old (SemConv) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New |
+| --------------------------------------------------------------------------------- | --- |
+| `k8s.container.cpu.limit` (type: `updowncounter`) | `k8s.container.cpu.limit.desired`, `k8s.container.cpu.limit.actual` (type: `updowncounter`) |
+| `k8s.container.cpu.request` (type: `updowncounter`) | `k8s.container.cpu.request.desired`, `k8s.container.cpu.request.actual` (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 -->
+
 ### 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.actual`](#metric-k8scontainercpulimitactual)
+  - [Metric: `k8s.container.cpu.limit.utilization`](#metric-k8scontainercpulimitutilization)
+  - [Metric: `k8s.container.cpu.request.desired`](#metric-k8scontainercpurequestdesired)
+  - [Metric: `k8s.container.cpu.request.actual`](#metric-k8scontainercpurequestactual)
+  - [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,125 @@ 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 [recommended][MetricRecommended].
 
-<!-- semconv metric.k8s.container.cpu.limit_utilization -->
+<!-- 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_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.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]:** 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 is derived from spec.containers[*].resources and shows the configured CPU limit on the container spec.
+See `Desired Resources` definition 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.actual`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.k8s.container.cpu.request_utilization -->
+<!-- semconv metric.k8s.container.cpu.limit.actual -->
 <!-- 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.actual` | 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]:** This metric is derived from status.containerStatuses[*].resources and shows the actual CPU limit for a running container.
+See `Actual Resources` definition 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`
+### Metric: `k8s.container.cpu.limit.utilization`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- markdownlint-disable -->
-<!-- semconv metric.k8s.container.cpu.limit -->
+<!-- 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.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.limit.utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU limit as defined by k8s.container.cpu.limit.actual [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 limit.
+If the CPU limit is not set, this metric SHOULD NOT be emitted for that container.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore-->
 
-### Metric: `k8s.container.cpu.request`
+### Metric: `k8s.container.cpu.request.desired`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- markdownlint-disable -->
-<!-- semconv metric.k8s.container.cpu.request -->
+<!-- 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` | 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.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]:** See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#resourcerequirements-v1-core for details.
+**[1]:** This metric is derived from spec.containers[*].resources and shows the configured CPU request on the container spec.
+See `Desired Resources` definition 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.actual`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.k8s.container.cpu.request.actual -->
+<!-- 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.actual` | 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]:** This metric is derived from status.containerStatuses[*].resources and shows the actual CPU request for a running container.
+See `Actual Resources` definition 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`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- 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.utilization` | Gauge | `1` | The ratio of container CPU usage to its CPU request as defined by k8s.container.cpu.request.actual [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 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.actual` 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.actual` 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"