[k8s] Improve *.cpu.usage description

.chloggen/fix_cpu_usage_desc.yaml

@@ -0,0 +1,26 @@
+# 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: Clarifies how cpu.usage is calculated for K8s and container entities.
+
+# 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: [2418]
+
+# (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: |
+  CPU usage is meaasured in cores/CPUs and is calculated based on the formula:
+  `usageCores = (cpuTimeEnd - cpuTimeStart) / elapsedSeconds`
+  This PR improves the description making it aligned with the corresponding
+  system and prosses metrics.

.chloggen/web_vital-attributes.yaml

@@ -10,7 +10,7 @@ change_type: 'breaking'
 component: browser
 
 # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Reworked the browser.web_vital event - moved name/value/delta/id from the event body to browser.web_vital.* attributes, and added new attributes per current instrumentation.
+note: Reworked the browser.web_vital event - moved name/value/delta/ID from the event body to browser.web_vital.* attributes, and added new attributes per current instrumentation.
 
 # 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.

docs/system/container-metrics.md

@@ -109,7 +109,7 @@ This metric is [opt-in][MetricOptIn].
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
 | `container.cpu.usage` | Gauge | `{cpu}` | Container's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/registry/entities/container.md#container) |
 
-**[1]:** CPU usage of the specific container on all available CPU cores, averaged over the sample window
+**[1]:** CPU usage of the specific container on all available CPU cores. It is calculated as the change in cumulative CPU time (container.cpu.time) over a measurement interval, divided by the elapsed time.
 
 **Attributes:**
 

docs/system/k8s-metrics.md

@@ -286,7 +286,7 @@ This metric is [recommended][MetricRecommended].
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
 | `k8s.pod.cpu.usage` | Gauge | `{cpu}` | Pod's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.pod`](/docs/registry/entities/k8s.md#k8s-pod) |
 
-**[1]:** CPU usage of the specific Pod on all available CPU cores, averaged over the sample window
+**[1]:** CPU usage of the specific Pod on all available CPU cores. It is calculated as the change in cumulative CPU time (k8s.pod.cpu.time) over a measurement interval, divided by the elapsed time.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
@@ -1063,7 +1063,7 @@ This metric is [recommended][MetricRecommended].
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
 | `k8s.node.cpu.usage` | Gauge | `{cpu}` | Node's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.node`](/docs/registry/entities/k8s.md#k8s-node) |
 
-**[1]:** CPU usage of the specific Node on all available CPU cores, averaged over the sample window
+**[1]:** CPU usage of the specific Node on all available CPU cores. It is calculated as the change in cumulative CPU time (k8s.node.cpu.time) over a measurement interval, divided by the elapsed time.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
@@ -1330,7 +1330,7 @@ This metric is [recommended][MetricRecommended].
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
 | `k8s.node.system_container.cpu.usage` | Gauge | `{cpu}` | Node's system container CPU usage, measured in CPUs. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.node.system_container`](/docs/registry/entities/k8s.md#k8s-node-system-container) |
 
-**[1]:** This metric is derived from the [CPUStats.UsageNanoCores](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L233) field of the [ContainerStats](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L157C6-L157C20) of [Node.SystemContainers](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L40) of the Kubelet's stats API.
+**[1]:** CPU usage of the specific System Container on all available CPU cores. It is calculated as the change in cumulative CPU time (k8s.node.system_container.cpu.time) over a measurement interval, divided by the elapsed time.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

model/container/metrics.yaml

@@ -67,7 +67,8 @@ groups:
     stability: development
     brief: "Container's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs."
     note: >
-      CPU usage of the specific container on all available CPU cores, averaged over the sample window
+      CPU usage of the specific container on all available CPU cores. It is calculated as the change in
+      cumulative CPU time (container.cpu.time) over a measurement interval, divided by the elapsed time.
     instrument: gauge
     unit: "{cpu}"
     entity_associations:

model/k8s/metrics.yaml

@@ -80,7 +80,8 @@ groups:
     stability: development
     brief: "Pod's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs."
     note: >
-      CPU usage of the specific Pod on all available CPU cores, averaged over the sample window
+      CPU usage of the specific Pod on all available CPU cores. It is calculated as the change in
+      cumulative CPU time (k8s.pod.cpu.time) over a measurement interval, divided by the elapsed time.
     instrument: gauge
     unit: "{cpu}"
 
@@ -554,7 +555,8 @@ groups:
     stability: development
     brief: "Node's CPU usage, measured in CPUs. Range from 0 to the number of allocatable CPUs."
     note: >
-      CPU usage of the specific Node on all available CPU cores, averaged over the sample window
+      CPU usage of the specific Node on all available CPU cores. It is calculated as the change in
+      cumulative CPU time (k8s.node.cpu.time) over a measurement interval, divided by the elapsed time.
     instrument: gauge
     entity_associations:
       - k8s.node
@@ -570,11 +572,8 @@ groups:
     stability: development
     brief: "Node's system container CPU usage, measured in CPUs."
     note: >
-      This metric is derived from the
-      [CPUStats.UsageNanoCores](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L233)
-      field of the [ContainerStats](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L157C6-L157C20)
-      of [Node.SystemContainers](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L40)
-      of the Kubelet's stats API.
+      CPU usage of the specific System Container on all available CPU cores. It is calculated as the change in
+      cumulative CPU time (k8s.node.system_container.cpu.time) over a measurement interval, divided by the elapsed time.
     instrument: gauge
     entity_associations:
       - k8s.node.system_container