diff --git a/.chloggen/cpu_time_revert.yaml b/.chloggen/cpu_time_revert.yaml new file mode 100644 index 0000000000..7cd6991398 --- /dev/null +++ b/.chloggen/cpu_time_revert.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: Revert the change that moved `system.cpu.*` to `cpu.*`. The 3 affected metrics are back in `system.cpu.*`. + +# 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: [1873] + +# (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/docs/system/README.md b/docs/system/README.md index a266f5c439..24ac1c7c51 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -12,7 +12,6 @@ System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. * [Container](container-metrics.md): For container-related metrics. -* [CPU](cpu-metrics.md): For CPU-related metrics. * [K8s](k8s-metrics.md): For K8s-related metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. diff --git a/docs/system/cpu-metrics.md b/docs/system/cpu-metrics.md deleted file mode 100644 index 2028c25f35..0000000000 --- a/docs/system/cpu-metrics.md +++ /dev/null @@ -1,133 +0,0 @@ - - -# Semantic conventions for CPU metrics - -**Status**: [Experimental][DocumentStatus] - -This document describes instruments and attributes for common CPU level metrics -in OpenTelemetry. - - - -- [CPU metrics](#cpu-metrics) - - [Metric: `cpu.time`](#metric-cputime) - - [Metric: `cpu.utilization`](#metric-cpuutilization) - - [Metric: `cpu.frequency`](#metric-cpufrequency) - - - -## CPU metrics - -### Metric: `cpu.time` - -This metric is [recommended][MetricRecommended]. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | ![Development](https://img.shields.io/badge/-development-blue) | | - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` - ---- - -`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 | ![Development](https://img.shields.io/badge/-development-blue) | -| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) | -| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) | -| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) | -| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) | -| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) | -| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) | -| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -### Metric: `cpu.utilization` - -This metric is [opt-in][MetricOptIn]. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `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) | | - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` - ---- - -`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 | ![Development](https://img.shields.io/badge/-development-blue) | -| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) | -| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) | -| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) | -| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) | -| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) | -| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) | -| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -### Metric: `cpu.frequency` - -This metric is [recommended][MetricRecommended]. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `cpu.frequency` | Gauge | `Hz` | Operating frequency of the logical CPU in Hertz. | ![Development](https://img.shields.io/badge/-development-blue) | | - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in -[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 97a5c5679c..7995d46f2e 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -24,6 +24,8 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Processor metrics](#processor-metrics) - [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount) - [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount) + - [Metric: `system.cpu.time`](#metric-systemcputime) + - [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) - [Memory metrics](#memory-metrics) - [Metric: `system.memory.usage`](#metric-systemmemoryusage) - [Metric: `system.memory.limit`](#metric-systemmemorylimit) @@ -143,6 +145,90 @@ This metric is [recommended][MetricRecommended]. +### Metric: `system.cpu.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `system.cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | ![Development](https://img.shields.io/badge/-development-blue) | `host` | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) | +| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) | +| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) | +| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) | +| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) | +| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) | +| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `system.cpu.utilization` + +This metric is [opt-in][MetricOptIn]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `system.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) | `host` | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `interrupt` | interrupt | ![Development](https://img.shields.io/badge/-development-blue) | +| `iowait` | iowait | ![Development](https://img.shields.io/badge/-development-blue) | +| `kernel` | kernel | ![Development](https://img.shields.io/badge/-development-blue) | +| `nice` | nice | ![Development](https://img.shields.io/badge/-development-blue) | +| `steal` | steal | ![Development](https://img.shields.io/badge/-development-blue) | +| `system` | system | ![Development](https://img.shields.io/badge/-development-blue) | +| `user` | user | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + ## Memory metrics **Description:** System level memory metrics capture under the namespace `system.memory`. diff --git a/model/cpu/metrics.yaml b/model/cpu/deprecated.yaml similarity index 55% rename from model/cpu/metrics.yaml rename to model/cpu/deprecated.yaml index 8819d40995..956b6924ce 100644 --- a/model/cpu/metrics.yaml +++ b/model/cpu/deprecated.yaml @@ -1,10 +1,12 @@ groups: - # cpu.* metrics - id: metric.cpu.time type: metric metric_name: cpu.time + brief: "Deprecated. Use `system.cpu.time` instead." + deprecated: + reason: renamed + renamed_to: system.cpu.time stability: development - brief: "Seconds each logical CPU spent on each mode" instrument: counter unit: "s" attributes: @@ -15,21 +17,25 @@ groups: - id: metric.cpu.utilization type: metric metric_name: cpu.utilization + brief: "Deprecated. Use `system.cpu.utilization` instead." + deprecated: + reason: renamed + renamed_to: system.cpu.utilization stability: development - 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." instrument: gauge unit: "1" attributes: - ref: cpu.mode - note: "Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" + note: "Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" - ref: cpu.logical_number - id: metric.cpu.frequency type: metric metric_name: cpu.frequency + brief: "Deprecated. Use `system.cpu.frequency` instead." + deprecated: + reason: renamed + renamed_to: system.cpu.frequency stability: development - brief: "Operating frequency of the logical CPU in Hertz." instrument: gauge - unit: "Hz" - attributes: - - ref: cpu.logical_number + unit: "{Hz}" diff --git a/model/system/deprecated/metrics-deprecated.yaml b/model/system/deprecated/metrics-deprecated.yaml deleted file mode 100644 index 969b0d8bd1..0000000000 --- a/model/system/deprecated/metrics-deprecated.yaml +++ /dev/null @@ -1,33 +0,0 @@ -groups: - - id: metric.system.cpu.time - type: metric - metric_name: system.cpu.time - brief: "Deprecated. Use `cpu.time` instead." - deprecated: - reason: renamed - renamed_to: cpu.time - stability: development - instrument: counter - unit: "s" - - - id: metric.system.cpu.utilization - type: metric - metric_name: system.cpu.utilization - brief: "Deprecated. Use `cpu.utilization` instead." - deprecated: - reason: renamed - renamed_to: cpu.utilization - stability: development - instrument: gauge - unit: "1" - - - id: metric.system.cpu.frequency - type: metric - metric_name: system.cpu.frequency - brief: "Deprecated. Use `cpu.frequency` instead." - deprecated: - reason: renamed - renamed_to: cpu.frequency - stability: development - instrument: gauge - unit: "{Hz}" diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index b027e0f6aa..0908e0f415 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -38,6 +38,46 @@ groups: entity_associations: - host + - id: metric.system.cpu.time + type: metric + metric_name: system.cpu.time + stability: development + brief: "Seconds each logical CPU spent on each mode" + instrument: counter + unit: "s" + attributes: + - ref: cpu.mode + note: "Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" + - ref: cpu.logical_number + entity_associations: + - host + + - id: metric.system.cpu.utilization + type: metric + metric_name: system.cpu.utilization + stability: development + 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." + instrument: gauge + unit: "1" + attributes: + - ref: cpu.mode + note: "Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" + - ref: cpu.logical_number + entity_associations: + - host + + - id: metric.system.cpu.frequency + type: metric + metric_name: system.cpu.frequency + stability: development + brief: "Operating frequency of the logical CPU in Hertz." + instrument: gauge + unit: "Hz" + attributes: + - ref: cpu.logical_number + entity_associations: + - host + # system.memory.* metrics - id: metric.system.memory.usage type: metric diff --git a/schema-next.yaml b/schema-next.yaml index 34ff2f8aa1..1938edf269 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -3,6 +3,13 @@ schema_url: https://opentelemetry.io/schemas/next versions: next: 1.34.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/2295 + - rename_metrics: + cpu.time: system.cpu.time + cpu.utilization: system.cpu.utilization + cpu.frequency: system.cpu.frequency 1.33.0: all: changes: