Semantic conventions for CPU metrics

Status: Experimental

This document describes instruments and attributes for common CPU level metrics in OpenTelemetry.

CPU Metrics

Metric: cpu.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
cpu.time	Counter	s	Seconds each logical CPU spent on each mode

Attribute	Type	Description	Examples	Requirement Level	Stability
cpu.logical_number	int	The logical CPU number [0..n-1]	1	Recommended
cpu.mode	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.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
cpu.logical_number	int	The logical CPU number [0..n-1]	1	Recommended
cpu.mode	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.

Name	Instrument Type	Unit (UCUM)	Description	Stability
cpu.frequency	Gauge	Hz	Operating frequency of the logical CPU in Hertz.

Attribute	Type	Description	Examples	Requirement Level	Stability
cpu.logical_number	int	The logical CPU number [0..n-1]	1	Recommended