# 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 |  | | | 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` |  | | [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` |  | **[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 |  | | `interrupt` | interrupt |  | | `iowait` | iowait |  | | `kernel` | kernel |  | | `nice` | nice |  | | `steal` | steal |  | | `system` | system |  | | `user` | user |  | ### 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. |  | | | 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` |  | | [`cpu.mode`](/docs/registry/attributes/cpu.md) | string | The mode of the CPU [1] | `user`; `system` | `Recommended` |  | **[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 |  | | `interrupt` | interrupt |  | | `iowait` | iowait |  | | `kernel` | kernel |  | | `nice` | nice |  | | `steal` | steal |  | | `system` | system |  | | `user` | user |  | ### 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. |  | | | 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` |  | [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