Merge *.cpu.state attributes to a common cpu.mode attribute (#1026)

Signed-off-by: ChrsMark <[email protected]> Co-authored-by: Alexandra Konrad <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]> Co-authored-by: Braydon Kains <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
open-telemetry · Jun 26, 2024 · db1b84d · db1b84d
1 parent ad05f1d
commit db1b84d
Show file tree

Hide file tree

Showing 24 changed files with 272 additions and 126 deletions.
diff --git a/.chloggen/merge_cpu_states.yaml b/.chloggen/merge_cpu_states.yaml
@@ -0,0 +1,22 @@
+# 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: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: system
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Rename `process.cpu.state`, `container.cpu.state`, and `system.cpu.state` attributes into a common `cpu.mode` attribute
+
+# 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: [840]
+
+# (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:
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -28,6 +28,7 @@ body:
         - area:cloudevents
         - area:code
         - area:container
+        - area:cpu
         - area:db
         - area:deployment
         - area:destination

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -21,6 +21,7 @@ body:
         - area:cloudevents
         - area:code
         - area:container
+        - area:cpu
         - area:db
         - area:deployment
         - area:destination

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -30,6 +30,7 @@ body:
         - area:cloudevents
         - area:code
         - area:container
+        - area:cpu
         - area:db
         - area:deployment
         - area:destination

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -40,6 +40,7 @@ Currently, the following namespaces exist:
 - [CloudEvents](cloudevents.md)
 - [Code](code.md)
 - [Container](container.md)
+- [CPU](cpu.md)
 - [Db](db.md)
 - [Deployment](deployment.md)
 - [Destination](destination.md)

diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md
@@ -18,7 +18,6 @@ A container instance.
 | `container.command`            | string   | The command used to run the container (i.e. the command name). [1]                                                                                                                                                                                                      | `otelcontribcol`                                                                                                                                                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `container.command_args`       | string[] | All the command arguments (including the command/executable itself) run by the container. [2]                                                                                                                                                                           | `["otelcontribcol, --config, config.yaml"]`                                                                                                                                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `container.command_line`       | string   | The full command run by the container as a single string representing the full command. [2]                                                                                                                                                                             | `otelcontribcol --config config.yaml`                                                                                                                                                                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `container.cpu.state`          | string   | The CPU state for this data point.                                                                                                                                                                                                                                      | `user`; `kernel`                                                                                                                                                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `container.id`                 | string   | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated.                                                                               | `a3bf90e006b2`                                                                                                                                                                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `container.image.id`           | string   | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2]                                                                                                                                                                                     | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f`                                                                                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `container.image.name`         | string   | Name of the image the container was built on.                                                                                                                                                                                                                           | `gcr.io/opentelemetry/operator`                                                                                                                                                                             | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -36,18 +35,19 @@ The ID is assigned by the container runtime and can vary in different environmen
 
 **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
 
-`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
-
-| Value    | Description                                                                                                     | Stability                                                        |
-| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `system` | When CPU is used by the system (host OS)                                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `user`   | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows).     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-
 ## Container Deprecated Attributes
 
 Describes deprecated container attributes.
 
 | Attribute                | Type   | Description                                | Examples                    | Stability                                                                                     |
 | ------------------------ | ------ | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- |
+| `container.cpu.state`    | string | Deprecated, use `cpu.mode` instead.        | `user`; `kernel`            | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `cpu.mode`         |
 | `container.labels.<key>` | string | Deprecated, use `container.label` instead. | `container.label.app=nginx` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `container.label`. |
+
+`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value    | Description                                                                                                     | Stability                                                        |
+| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `system` | When CPU is used by the system (host OS)                                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user`   | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows).     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
diff --git a/docs/attributes-registry/cpu.md b/docs/attributes-registry/cpu.md
@@ -0,0 +1,28 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CPU
+
+## CPU Attributes
+
+Attributes specific to a cpu instance.
+
+| Attribute  | Type   | Description         | Examples         | Stability                                                        |
+| ---------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- |
+| `cpu.mode` | string | The mode of the CPU | `user`; `system` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value       | Description | Stability                                                        |
+| ----------- | ----------- | ---------------------------------------------------------------- |
+| `idle`      | idle        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `interrupt` | interrupt   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `iowait`    | iowait      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `kernel`    | kernel      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nice`      | nice        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `steal`     | steal       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `system`    | system      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user`      | user        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md
@@ -7,7 +7,7 @@
 # Process
 
 - [Process](#process-attributes)
-- [Process Cpu](#process-cpu-attributes)
+- [Process Deprecated](#process-deprecated-attributes)
 
 ## Process Attributes
 
@@ -58,13 +58,13 @@ An operating system process.
 | `major` | major       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `minor` | minor       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-## Process Cpu Attributes
+## Process Deprecated Attributes
 
-Attributes for process CPU
+Deprecated process attributes.
 
-| Attribute           | Type   | Description                   | Examples                 | Stability                                                        |
-| ------------------- | ------ | ----------------------------- | ------------------------ | ---------------------------------------------------------------- |
-| `process.cpu.state` | string | The CPU state of the process. | `system`; `user`; `wait` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute           | Type   | Description                         | Examples                 | Stability                                                                             |
+| ------------------- | ------ | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------------- |
+| `process.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `system`; `user`; `wait` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `cpu.mode` |
 
 `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md
@@ -23,14 +23,22 @@ Describes System attributes
 | --------------- | ------ | --------------------- | -------------- | ---------------------------------------------------------------- |
 | `system.device` | string | The device identifier | `(identifier)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-## System Cpu Attributes
+## System CPU Attributes
 
 Describes System CPU attributes
 
-| Attribute                   | Type   | Description                     | Examples            | Stability                                                        |
-| --------------------------- | ------ | ------------------------------- | ------------------- | ---------------------------------------------------------------- |
-| `system.cpu.logical_number` | int    | The logical CPU number [0..n-1] | `1`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `system.cpu.state`          | string | The state of the CPU            | `idle`; `interrupt` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute                   | Type | Description                     | Examples | Stability                                                        |
+| --------------------------- | ---- | ------------------------------- | -------- | ---------------------------------------------------------------- |
+| `system.cpu.logical_number` | int  | The logical CPU number [0..n-1] | `1`      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+## System Deprecated Attributes
+
+Deprecated system attributes.
+
+| Attribute                 | Type   | Description                                      | Examples            | Stability                                                                                           |
+| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- |
+| `system.cpu.state`        | string | Deprecated, use `cpu.mode` instead.              | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `cpu.mode`               |
+| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running`           | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `system.process.status`. |
 
 `system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
@@ -44,14 +52,6 @@ Describes System CPU attributes
 | `system`    | system      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `user`      | user        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-## System Deprecated Attributes
-
-Deprecated system attributes.
-
-| Attribute                 | Type   | Description                                      | Examples  | Stability                                                                                           |
-| ------------------------- | ------ | ------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------- |
-| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `system.process.status`. |
-
 `system.processes.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value      | Description | Stability                                                        |

diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md
@@ -42,15 +42,24 @@ This metric is [opt-in][MetricOptIn].
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`container.cpu.state`](/docs/attributes-registry/container.md) | string | The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `user`; `kernel` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+**[1]:** Following states SHOULD be used: `user`, `system`, `kernel`
+
+
+
+`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |
 |---|---|---|
-| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) |