Skip to content

Commit bdb26d9

Browse files
rogercollrogercoll
authored
refactor: move system cpu-related metrics to cpu namespace (#1896)
1 parent d1826a7 commit bdb26d9

13 files changed

+247
-175
lines changed

‎.chloggen/cpu_namespace.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: 'breaking'
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: system
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: Move CPU-related system.cpu.* metrics to CPU namespace
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
# The values here must be integers.
17+
issues: [1873]
18+
19+
# (Optional) One or more lines of additional information to render under the primary note.
20+
# These lines will be padded with 2 spaces and then inserted directly into the document.
21+
# Use pipe (|) for multiline entries.
22+
subtext:

‎docs/attributes-registry/cpu.md

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Attributes specific to a cpu instance.
99

1010
| Attribute | Type | Description | Examples | Stability |
1111
|---|---|---|---|---|
12+
| <a id="cpu-logical-number" href="#cpu-logical-number">`cpu.logical_number`</a> | int | The logical CPU number [0..n-1] | `1` | ![Development](https://img.shields.io/badge/-development-blue) |
1213
| <a id="cpu-mode" href="#cpu-mode">`cpu.mode`</a> | string | The mode of the CPU | `user`; `system` | ![Development](https://img.shields.io/badge/-development-blue) |
1314

1415
---

‎docs/attributes-registry/system.md

+1-9
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
# System
55

66
- [General System Attributes](#general-system-attributes)
7-
- [System CPU Attributes](#system-cpu-attributes)
87
- [Filesystem Attributes](#filesystem-attributes)
98
- [System Memory Attributes](#system-memory-attributes)
109
- [System Paging Attributes](#system-paging-attributes)
@@ -19,14 +18,6 @@ Describes System attributes
1918
|---|---|---|---|---|
2019
| <a id="system-device" href="#system-device">`system.device`</a> | string | The device identifier | `(identifier)` | ![Development](https://img.shields.io/badge/-development-blue) |
2120

22-
## System CPU Attributes
23-
24-
Describes System CPU attributes
25-
26-
| Attribute | Type | Description | Examples | Stability |
27-
|---|---|---|---|---|
28-
| <a id="system-cpu-logical-number" href="#system-cpu-logical-number">`system.cpu.logical_number`</a> | int | The logical CPU number [0..n-1] | `1` | ![Development](https://img.shields.io/badge/-development-blue) |
29-
3021
## Filesystem Attributes
3122

3223
Describes Filesystem attributes
@@ -142,6 +133,7 @@ Deprecated system attributes.
142133

143134
| Attribute | Type | Description | Examples | Stability |
144135
|---|---|---|---|---|
136+
| <a id="system-cpu-logical-number" href="#system-cpu-logical-number">`system.cpu.logical_number`</a> | int | Deprecated, use `cpu.logical_number` instead. | `1` | ![Development](https://img.shields.io/badge/-development-blue) |
145137
| <a id="system-cpu-state" href="#system-cpu-state">`system.cpu.state`</a> | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `cpu.mode` |
146138
| <a id="system-network-state" href="#system-network-state">`system.network.state`</a> | string | Deprecated, use `network.connection.state` instead. | `close_wait` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed, report network connection state with `network.connection.state` attribute |
147139
| <a id="system-processes-status" href="#system-processes-status">`system.processes.status`</a> | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `system.process.status`. |

‎docs/system/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ System semantic conventions are defined for the following metrics:
1212

1313
* [System](system-metrics.md): For standard system metrics.
1414
* [Container](container-metrics.md): For container-related metrics.
15+
* [CPU](cpu-metrics.md): For CPU-related metrics.
1516
* [K8s](k8s-metrics.md): For K8s-related metrics.
1617
* [Hardware](hardware-metrics.md): For hardware-related metrics.
1718
* [Process](process-metrics.md): For standard process metrics.

‎docs/system/cpu-metrics.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
linkTitle: CPU
3+
--->
4+
5+
# Semantic conventions for CPU metrics
6+
7+
**Status**: [Experimental][DocumentStatus]
8+
9+
This document describes instruments and attributes for common CPU level metrics
10+
in OpenTelemetry.
11+
12+
<!-- toc -->
13+
14+
- [CPU Metrics](#cpu-metrics)
15+
- [Metric: `cpu.time`](#metric-cputime)
16+
- [Metric: `cpu.utilization`](#metric-cpuutilization)
17+
- [Metric: `cpu.frequency`](#metric-cpufrequency)
18+
19+
<!-- tocstop -->
20+
21+
## CPU Metrics
22+
23+
### Metric: `cpu.time`
24+
25+
This metric is [recommended][MetricRecommended].
26+
27+
<!-- semconv metric.cpu.time -->
28+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
29+
<!-- see templates/registry/markdown/snippet.md.j2 -->
30+
<!-- prettier-ignore-start -->
31+
<!-- markdownlint-capture -->
32+
<!-- markdownlint-disable -->
33+
34+
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
35+
| -------- | --------------- | ----------- | -------------- | --------- |
36+
| `cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | ![Development](https://img.shields.io/badge/-development-blue) |
37+
38+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
39+
|---|---|---|---|---|---|
40+
| [`cpu.logical_number`](/docs/attributes-registry/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
41+
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
42+
43+
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
44+
45+
---
46+
47+
`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.
48+
49+
| Value | Description | Stability |
50+
|---|---|---|
51+
| `idle` | idle | ![Development](https://img.shields.io/badge/-development-blue) |
52+
| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) |
53+
| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) |
54+
| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) |
55+
| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) |
56+
| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) |
57+
| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) |
58+
| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) |
59+
60+
<!-- markdownlint-restore -->
61+
<!-- prettier-ignore-end -->
62+
<!-- END AUTOGENERATED TEXT -->
63+
<!-- endsemconv -->
64+
65+
### Metric: `cpu.utilization`
66+
67+
This metric is [opt-in][MetricOptIn].
68+
69+
<!-- semconv metric.cpu.utilization -->
70+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
71+
<!-- see templates/registry/markdown/snippet.md.j2 -->
72+
<!-- prettier-ignore-start -->
73+
<!-- markdownlint-capture -->
74+
<!-- markdownlint-disable -->
75+
76+
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
77+
| -------- | --------------- | ----------- | -------------- | --------- |
78+
| `cpu.utilization` | Gauge | `1` | For each logical CPU, the utilization is calculated as the change in cumulative CPU time (cpu.time) over a measurement interval, divided by the elapsed time. | ![Development](https://img.shields.io/badge/-development-blue) |
79+
80+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
81+
|---|---|---|---|---|---|
82+
| [`cpu.logical_number`](/docs/attributes-registry/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
83+
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
84+
85+
**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
86+
87+
---
88+
89+
`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.
90+
91+
| Value | Description | Stability |
92+
|---|---|---|
93+
| `idle` | idle | ![Development](https://img.shields.io/badge/-development-blue) |
94+
| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) |
95+
| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) |
96+
| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) |
97+
| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) |
98+
| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) |
99+
| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) |
100+
| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) |
101+
102+
<!-- markdownlint-restore -->
103+
<!-- prettier-ignore-end -->
104+
<!-- END AUTOGENERATED TEXT -->
105+
<!-- endsemconv -->
106+
107+
### Metric: `cpu.frequency`
108+
109+
This metric is [recommended][MetricRecommended].
110+
111+
<!-- semconv metric.cpu.frequency -->
112+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
113+
<!-- see templates/registry/markdown/snippet.md.j2 -->
114+
<!-- prettier-ignore-start -->
115+
<!-- markdownlint-capture -->
116+
<!-- markdownlint-disable -->
117+
118+
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
119+
| -------- | --------------- | ----------- | -------------- | --------- |
120+
| `cpu.frequency` | Gauge | `Hz` | Operating frequency of the logical CPU in Hertz. | ![Development](https://img.shields.io/badge/-development-blue) |
121+
122+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
123+
|---|---|---|---|---|---|
124+
| [`cpu.logical_number`](/docs/attributes-registry/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
125+
126+
<!-- markdownlint-restore -->
127+
<!-- prettier-ignore-end -->
128+
<!-- END AUTOGENERATED TEXT -->
129+
<!-- endsemconv -->
130+
131+
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
132+
[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
133+
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended

‎docs/system/system-metrics.md

-111
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,8 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
2222
- [General Metrics](#general-metrics)
2323
- [Metric: `system.uptime`](#metric-systemuptime)
2424
- [Processor Metrics](#processor-metrics)
25-
- [Metric: `system.cpu.time`](#metric-systemcputime)
26-
- [Metric: `system.cpu.utilization`](#metric-systemcpuutilization)
2725
- [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount)
2826
- [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount)
29-
- [Metric: `system.cpu.frequency`](#metric-systemcpufrequency)
3027
- [Memory Metrics](#memory-metrics)
3128
- [Metric: `system.memory.usage`](#metric-systemmemoryusage)
3229
- [Metric: `system.memory.limit`](#metric-systemmemorylimit)
@@ -102,90 +99,6 @@ The actual accuracy would depend on the instrumentation and operating system.
10299

103100
**Description:** System level processor metrics captured under the namespace `system.cpu`.
104101

105-
### Metric: `system.cpu.time`
106-
107-
This metric is [recommended][MetricRecommended].
108-
109-
<!-- semconv metric.system.cpu.time -->
110-
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
111-
<!-- see templates/registry/markdown/snippet.md.j2 -->
112-
<!-- prettier-ignore-start -->
113-
<!-- markdownlint-capture -->
114-
<!-- markdownlint-disable -->
115-
116-
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
117-
| -------- | --------------- | ----------- | -------------- | --------- |
118-
| `system.cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | ![Development](https://img.shields.io/badge/-development-blue) |
119-
120-
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
121-
|---|---|---|---|---|---|
122-
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
123-
| [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
124-
125-
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
126-
127-
---
128-
129-
`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.
130-
131-
| Value | Description | Stability |
132-
|---|---|---|
133-
| `idle` | idle | ![Development](https://img.shields.io/badge/-development-blue) |
134-
| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) |
135-
| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) |
136-
| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) |
137-
| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) |
138-
| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) |
139-
| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) |
140-
| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) |
141-
142-
<!-- markdownlint-restore -->
143-
<!-- prettier-ignore-end -->
144-
<!-- END AUTOGENERATED TEXT -->
145-
<!-- endsemconv -->
146-
147-
### Metric: `system.cpu.utilization`
148-
149-
This metric is [opt-in][MetricOptIn].
150-
151-
<!-- semconv metric.system.cpu.utilization -->
152-
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
153-
<!-- see templates/registry/markdown/snippet.md.j2 -->
154-
<!-- prettier-ignore-start -->
155-
<!-- markdownlint-capture -->
156-
<!-- markdownlint-disable -->
157-
158-
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
159-
| -------- | --------------- | ----------- | -------------- | --------- |
160-
| `system.cpu.utilization` | Gauge | `1` | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs | ![Development](https://img.shields.io/badge/-development-blue) |
161-
162-
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
163-
|---|---|---|---|---|---|
164-
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
165-
| [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
166-
167-
**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
168-
169-
---
170-
171-
`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.
172-
173-
| Value | Description | Stability |
174-
|---|---|---|
175-
| `idle` | idle | ![Development](https://img.shields.io/badge/-development-blue) |
176-
| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) |
177-
| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) |
178-
| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) |
179-
| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) |
180-
| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) |
181-
| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) |
182-
| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) |
183-
184-
<!-- markdownlint-restore -->
185-
<!-- prettier-ignore-end -->
186-
<!-- END AUTOGENERATED TEXT -->
187-
<!-- endsemconv -->
188-
189102
### Metric: `system.cpu.physical.count`
190103

191104
This metric is [recommended][MetricRecommended].
@@ -230,30 +143,6 @@ This metric is [recommended][MetricRecommended].
230143
<!-- END AUTOGENERATED TEXT -->
231144
<!-- endsemconv -->
232145

233-
### Metric: `system.cpu.frequency`
234-
235-
This metric is [recommended][MetricRecommended].
236-
237-
<!-- semconv metric.system.cpu.frequency -->
238-
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
239-
<!-- see templates/registry/markdown/snippet.md.j2 -->
240-
<!-- prettier-ignore-start -->
241-
<!-- markdownlint-capture -->
242-
<!-- markdownlint-disable -->
243-
244-
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
245-
| -------- | --------------- | ----------- | -------------- | --------- |
246-
| `system.cpu.frequency` | Gauge | `{Hz}` | Reports the current frequency of the CPU in Hz | ![Development](https://img.shields.io/badge/-development-blue) |
247-
248-
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
249-
|---|---|---|---|---|---|
250-
| [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
251-
252-
<!-- markdownlint-restore -->
253-
<!-- prettier-ignore-end -->
254-
<!-- END AUTOGENERATED TEXT -->
255-
<!-- endsemconv -->
256-
257146
## Memory Metrics
258147

259148
**Description:** System level memory metrics capture under the namespace `system.memory`.

‎model/cpu/metrics.yaml

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
groups:
2+
# cpu.* metrics
3+
- id: metric.cpu.time
4+
type: metric
5+
metric_name: cpu.time
6+
stability: development
7+
brief: "Seconds each logical CPU spent on each mode"
8+
instrument: counter
9+
unit: "s"
10+
attributes:
11+
- ref: cpu.mode
12+
note: "Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`"
13+
- ref: cpu.logical_number
14+
15+
- id: metric.cpu.utilization
16+
type: metric
17+
metric_name: cpu.utilization
18+
stability: development
19+
brief: "For each logical CPU, the utilization is calculated as the change in cumulative CPU time (cpu.time) over a measurement interval, divided by the elapsed time."
20+
instrument: gauge
21+
unit: "1"
22+
attributes:
23+
- ref: cpu.mode
24+
note: "Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`"
25+
- ref: cpu.logical_number
26+
27+
- id: metric.cpu.frequency
28+
type: metric
29+
metric_name: cpu.frequency
30+
stability: development
31+
brief: "Operating frequency of the logical CPU in Hertz."
32+
instrument: gauge
33+
unit: "Hz"
34+
attributes:
35+
- ref: cpu.logical_number

‎model/cpu/registry.yaml

+5
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,8 @@ groups:
3535
stability: development
3636
stability: development
3737
examples: [ "user", "system" ]
38+
- id: cpu.logical_number
39+
type: int
40+
stability: development
41+
brief: "The logical CPU number [0..n-1]"
42+
examples: [1]

0 commit comments

Comments
 (0)