(k8s): add CPU limit/request utilization metrics for pod and container (#2514)

Signed-off-by: ChrsMark <[email protected]>
Co-authored-by: Jina Jain <[email protected]>

Author: ChrsMark

.chloggen/semconv_k8s_cpu_utilization.yaml

@@ -0,0 +1,21 @@
+# 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: "Add container CPU limit/request utilization metrics."
+# 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: [1489]
+
+# (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:

docs/non-normative/k8s-migration.md

@@ -335,6 +335,8 @@ The changes in their metrics are the following:
 | `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 -->
 

docs/system/k8s-metrics.md

@@ -89,6 +89,8 @@ 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.memory.limit`](#metric-k8scontainermemorylimit)
@@ -1817,6 +1819,48 @@ This metric is [recommended][MetricRecommended].
 
 **Description:** K8s Container level metrics captured under the namespace `k8s.container`.
 
+### Metric: `k8s.container.cpu.limit_utilization`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- 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 -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| 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) |
+
+**[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.
+
+<!-- markdownlint-restore -->
+<!-- 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 -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| 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) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 ### Metric: `k8s.container.cpu.limit`
 
 This metric is [recommended][MetricRecommended].

model/k8s/metrics.yaml

@@ -1142,6 +1142,32 @@ groups:
     note: |
       This metric SHOULD reflect the value of the `ready` field in the
       [K8s ContainerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#containerstatus-v1-core).
+  - 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
+    brief: "The ratio of container CPU usage to its CPU limit."
+    entity_associations:
+      - k8s.container
+    note: >
+      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.
+    instrument: gauge
+    unit: "1"
+  - 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
+    brief: "The ratio of container CPU usage to its CPU request."
+    entity_associations:
+      - k8s.container
+    instrument: gauge
+    unit: "1"
 
   # k8s.resourcequota.cpu.* metrics
   - id: metric.k8s.resourcequota.cpu.limit.hard