Semantic conventions for system metrics

Status: Development

This document describes instruments and attributes for common system level metrics in OpenTelemetry. Consider the general metric semantic conventions when creating instruments not explicitly defined in the specification.

The system.* namespace SHOULD be exclusively used to report hosts’ metrics. The system.* namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). Metrics collected from technology-specific, well-defined APIs (e.g. Kubelet’s API or container runtimes) should be reported under their respective namespace (e.g. k8s., container.). Resource attributes related to a host, SHOULD be reported under the host.* namespace.

Warning Existing instrumentations and collector that are using v1.21.0 of this document (or prior):

• SHOULD NOT adopt any breaking changes from document until the system semantic conventions are marked stable. Conventions include, but are not limited to, attributes, metric names, and unit of measure.
• SHOULD introduce a control mechanism to allow users to opt-in to the new conventions once the migration plan is finalized.

General metrics

Metric: system.uptime

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.uptime	Gauge	s	The time the system has been running. [1]		host

[1]: Instrumentations SHOULD use a gauge with type double and measure uptime in seconds as a floating point number with the highest precision available. The actual accuracy would depend on the instrumentation and operating system.

Processor metrics

Description: System level processor metrics captured under the namespace system.cpu.

Metric: system.cpu.physical.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.cpu.physical.count	UpDownCounter	{cpu}	Reports the number of actual physical processor cores on the hardware. [1]		host

[1]: Calculated by multiplying the number of sockets by the number of cores per socket

Metric: system.cpu.logical.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.cpu.logical.count	UpDownCounter	{cpu}	Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking. [1]		host

[1]: Calculated by multiplying the number of sockets by the number of cores per socket, and then by the number of threads per core

Metric: system.cpu.time

This metric is recommended.

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cpu.mode		Recommended	string	The mode of the CPU [1]	user; system
cpu.logical_number		Opt-In	int	The logical CPU number [0..n-1]	1

[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	IO Wait
kernel	Kernel
nice	Nice
steal	Steal
system	System
user	User

Metric: system.cpu.frequency

This metric is recommended.

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cpu.logical_number		Recommended	int	The logical CPU number [0..n-1]	1

Metric: system.cpu.utilization

This metric is opt-in.

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.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cpu.mode		Recommended	string	The mode of the CPU [1]	user; system
cpu.logical_number		Opt-In	int	The logical CPU number [0..n-1]	1

[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	IO Wait
kernel	Kernel
nice	Nice
steal	Steal
system	System
user	User

Memory metrics

Description: System level memory metrics capture under the namespace system.memory. This does not include paging/swap memory.

Metric: system.memory.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.memory.usage	UpDownCounter	By	Reports memory in use by state.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.memory.state		Recommended	string	The memory state	free; cached

system.memory.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
buffers	buffers
cached	cached
free	free
used	Actual used virtual memory in bytes. [1]

[1]: Calculation based on the operating system metrics. On Linux, this corresponds to “MemTotal - MemAvailable” from /proc/meminfo, which more accurately reflects memory in active use by applications compared to older formulas based on free, cached, and buffers. If MemAvailable is not available, a fallback to those older formulas may be used.

Metric: system.memory.limit

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.memory.limit	UpDownCounter	By	Total virtual memory available in the system.		host

Metric: system.memory.shared

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.memory.shared	UpDownCounter	By	Shared memory used (mostly by tmpfs). [1]		host

[1]: Equivalent of shared from free command or Shmem from /proc/meminfo"

Metric: system.memory.utilization

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.memory.utilization	Gauge	1	Percentage of memory bytes in use.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.memory.state		Recommended	string	The memory state	free; cached

system.memory.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
buffers	buffers
cached	cached
free	free
used	Actual used virtual memory in bytes. [1]

[1]: Calculation based on the operating system metrics. On Linux, this corresponds to “MemTotal - MemAvailable” from /proc/meminfo, which more accurately reflects memory in active use by applications compared to older formulas based on free, cached, and buffers. If MemAvailable is not available, a fallback to those older formulas may be used.

Paging/Swap Metrics

Description: System level paging/swap memory metrics captured under the namespace system.paging.

Metric: system.paging.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.paging.usage	UpDownCounter	By	Unix swap or windows pagefile usage.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	Unique identifier for the device responsible for managing paging operations.	/dev/dm-0
system.paging.state		Recommended	string	The memory paging state	free

system.paging.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
free	free
used	used

Metric: system.paging.utilization

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.paging.utilization	Gauge	1	Swap (unix) or pagefile (windows) utilization.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	Unique identifier for the device responsible for managing paging operations.	/dev/dm-0
system.paging.state		Recommended	string	The memory paging state	free

system.paging.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
free	free
used	used

Metric: system.paging.faults

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.paging.faults	Counter	{fault}	The number of page faults.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.paging.fault.type		Recommended	string	The paging fault type	minor

system.paging.fault.type 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
major	major
minor	minor

Metric: system.paging.operations

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.paging.operations	Counter	{operation}	The number of paging operations.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.paging.direction		Recommended	string	The paging access direction	in
system.paging.fault.type		Recommended	string	The paging fault type	minor

system.paging.direction 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
in	in
out	out

system.paging.fault.type 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
major	major
minor	minor

Disk controller metrics

Description: System level disk performance metrics captured under the namespace system.disk.

Metric: system.disk.io

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.io	Counter	By	Disk bytes transferred.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
disk.io.direction		Recommended	string	The disk IO operation direction.	read
system.device		Recommended	string	The device identifier	(identifier)

disk.io.direction 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
read	read
write	write

Metric: system.disk.operations

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.operations	Counter	{operation}	Disk operations count.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
disk.io.direction		Recommended	string	The disk IO operation direction.	read
system.device		Recommended	string	The device identifier	(identifier)

disk.io.direction 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
read	read
write	write

Metric: system.disk.io_time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.io_time	Counter	s	Time disk spent activated. [1]		host

[1]: The real elapsed time (“wall clock”) used in the I/O path (time from operations running in parallel are not counted). Measured as:

• Linux: Field 13 from procfs-diskstats
• Windows: The complement of “Disk% Idle Time” performance counter: uptime * (100 - "Disk\% Idle Time") / 100

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	The device identifier	(identifier)

Metric: system.disk.operation_time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.operation_time	Counter	s	Sum of the time each operation took to complete. [1]		host

[1]: Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as:

• Linux: Fields 7 & 11 from procfs-diskstats
• Windows: “Avg. Disk sec/Read” perf counter multiplied by “Disk Reads/sec” perf counter (similar for Writes)

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
disk.io.direction		Recommended	string	The disk IO operation direction.	read
system.device		Recommended	string	The device identifier	(identifier)

disk.io.direction 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
read	read
write	write

Metric: system.disk.merged

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.merged	Counter	{operation}	The number of disk reads/writes merged into single physical disk access operations.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
disk.io.direction		Recommended	string	The disk IO operation direction.	read
system.device		Recommended	string	The device identifier	(identifier)

disk.io.direction 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
read	read
write	write

Metric: system.disk.limit

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.disk.limit	UpDownCounter	By	The total storage capacity of the disk.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	The device identifier	(identifier)

Filesystem metrics

Description: System level filesystem metrics captured under the namespace system.filesystem.

Metric: system.filesystem.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.filesystem.usage	UpDownCounter	By	Reports a filesystem’s space usage across different states. [1]		host

[1]: The sum of all system.filesystem.usage values over the different system.filesystem.state attributes SHOULD equal the total storage capacity of the filesystem, that is system.filesystem.limit.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	Identifier for the device where the filesystem resides.	/dev/sda; \network-drive
system.filesystem.mode		Recommended	string	The filesystem mode	rw, ro
system.filesystem.mountpoint		Recommended	string	The filesystem mount path	/mnt/data
system.filesystem.state		Recommended	string	The filesystem state	used
system.filesystem.type		Recommended	string	The filesystem type	ext4

system.filesystem.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
free	free
reserved	reserved
used	used

system.filesystem.type 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
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

Metric: system.filesystem.utilization

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.filesystem.utilization	Gauge	1	Fraction of filesystem bytes used.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	Identifier for the device where the filesystem resides.	/dev/sda; \network-drive
system.filesystem.mode		Recommended	string	The filesystem mode	rw, ro
system.filesystem.mountpoint		Recommended	string	The filesystem mount path	/mnt/data
system.filesystem.state		Recommended	string	The filesystem state	used
system.filesystem.type		Recommended	string	The filesystem type	ext4

system.filesystem.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
free	free
reserved	reserved
used	used

system.filesystem.type 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
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

Metric: system.filesystem.limit

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.filesystem.limit	UpDownCounter	By	The total storage capacity of the filesystem.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.device		Recommended	string	Identifier for the device where the filesystem resides.	/dev/sda; \network-drive
system.filesystem.mode		Recommended	string	The filesystem mode	rw, ro
system.filesystem.mountpoint		Recommended	string	The filesystem mount path	/mnt/data
system.filesystem.type		Recommended	string	The filesystem type	ext4

system.filesystem.type 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
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

Network metrics

Description: System level network metrics captured under the namespace system.network.

Metric: system.network.packet.dropped

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.network.packet.dropped	Counter	{packet}	Count of packets that are dropped or discarded even though there was no error. [1]		host

[1]: Measured as:

• Linux: the drop column in /proc/net/dev (source)
• Windows: InDiscards/OutDiscards from GetIfEntry2

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.interface.name		Recommended	string	The network interface name.	lo; eth0
network.io.direction		Recommended	string	The network IO operation direction.	transmit

network.io.direction 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
receive	receive
transmit	transmit

Metric: system.network.packet.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.network.packet.count	Counter	{packet}	The number of packets transferred.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.io.direction		Recommended	string	The network IO operation direction.	transmit
system.device		Recommended	string	The device identifier	(identifier)

network.io.direction 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
receive	receive
transmit	transmit

Metric: system.network.errors

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.network.errors	Counter	{error}	Count of network errors detected. [1]		host

[1]: Measured as:

• Linux: the errs column in /proc/net/dev (source).
• Windows: InErrors/OutErrors from GetIfEntry2.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.interface.name		Recommended	string	The network interface name.	lo; eth0
network.io.direction		Recommended	string	The network IO operation direction.	transmit

network.io.direction 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
receive	receive
transmit	transmit

Metric: system.network.io

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.network.io	Counter	By	The number of bytes transmitted and received.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.interface.name		Recommended	string	The network interface name.	lo; eth0
network.io.direction		Recommended	string	The network IO operation direction.	transmit

network.io.direction 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
receive	receive
transmit	transmit

Metric: system.network.connection.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.network.connection.count	UpDownCounter	{connection}	The number of connections.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.connection.state		Recommended	string	The state of network connection [1]	close_wait
network.interface.name		Recommended	string	The network interface name.	lo; eth0
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [2]	tcp; udp

[1] network.connection.state: Connection states are defined as part of the rfc9293

[2] network.transport: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

network.connection.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
close_wait	close_wait
closed	closed
closing	closing
established	established
fin_wait_1	fin_wait_1
fin_wait_2	fin_wait_2
last_ack	last_ack
listen	listen
syn_received	syn_received
syn_sent	syn_sent
time_wait	time_wait

network.transport 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
unix	Unix domain socket

Aggregate system process metrics

Description: System level aggregate process metrics captured under the namespace system.process. For metrics at the individual process level, see process metrics.

Metric: system.process.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.process.count	UpDownCounter	{process}	Total number of processes in each state.		host

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
process.state		Recommended	string	The process state, e.g., Linux Process State Codes	running

process.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
defunct	defunct
running	running
sleeping	sleeping
stopped	stopped

Metric: system.process.created

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.process.created	Counter	{process}	Total number of processes created over uptime of the host.		host

system.{os}. - OS Specific System Metrics

Instrument names for system level metrics that have different and conflicting meaning across multiple OSes should be prefixed with system.{os}. and follow the hierarchies listed above for different entities like CPU, memory, and network.

For example, UNIX load average over a given interval is not well standardized and its value across different UNIX like OSes may vary despite being under similar load:

Without getting into the vagaries of every Unix-like operating system in existence, the load average more or less represents the average number of processes that are in the running (using the CPU) or runnable (waiting for the CPU) states. One notable exception exists: Linux includes processes in uninterruptible sleep states, typically waiting for some I/O activity to complete. This can markedly increase the load average on Linux systems.

(source of quote, linux source code)

An instrument for load average over 1 minute on Linux could be named system.linux.cpu.load_1m, reusing the cpu name proposed above and having an {os} prefix to split this metric across OSes.

Metric: system.linux.memory.available

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.linux.memory.available	UpDownCounter	By	An estimate of how much memory is available for starting new applications, without causing swapping. [1]		host

[1]: This is an alternative to system.memory.usage metric with state=free. Linux starting from 3.14 exports “available” memory. It takes “free” memory as a baseline, and then factors in kernel-specific values. This is supposed to be more accurate than just “free” memory. For reference, see the calculations here. See also MemAvailable in /proc/meminfo.

Metric: system.linux.memory.slab.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
system.linux.memory.slab.usage	UpDownCounter	By	Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1]		host

[1]: The sum over the reclaimable and unreclaimable state values in linux.memory.slab.usage SHOULD be equal to the total slab memory available on the system. Note that the total slab memory is not constant and may vary over time. See also the Slab allocator and Slab in /proc/meminfo.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
linux.memory.slab.state		Recommended	string	The Linux Slab memory state	reclaimable; unreclaimable

linux.memory.slab.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
reclaimable	reclaimable
unreclaimable	unreclaimable