Semantic Conventions for OS Process Metrics

Status: Experimental

This document describes instruments and attributes for common OS process level metrics in OpenTelemetry. Also consider the general metric semantic conventions when creating instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see semantic conventions for runtime environment metrics.

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.

Process Metrics

Metric: process.cpu.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.cpu.time	Counter	s	Total CPU seconds broken down by different states.

Attribute	Type	Description	Examples	Requirement Level	Stability
cpu.mode	string	A process SHOULD be characterized either by data points with no mode labels, or only data points with mode labels. [1]	user; system	Recommended

[1]: Following states SHOULD be used: user, system, wait

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: process.cpu.utilization

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.cpu.utilization	Gauge	1	Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process.

Attribute	Type	Description	Examples	Requirement Level	Stability
cpu.mode	string	A process SHOULD be characterized either by data points with no mode labels, or only data points with mode labels. [1]	user; system	Recommended

[1]: Following states SHOULD be used: user, system, wait

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: process.memory.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.memory.usage	UpDownCounter	By	The amount of physical memory in use.

Metric: process.memory.virtual

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.memory.virtual	UpDownCounter	By	The amount of committed virtual memory.

Metric: process.disk.io

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.disk.io	Counter	By	Disk bytes transferred.

Attribute	Type	Description	Examples	Requirement Level	Stability
disk.io.direction	string	The disk IO operation direction.	read	Recommended

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: process.network.io

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.network.io	Counter	By	Network bytes transferred.

Attribute	Type	Description	Examples	Requirement Level	Stability
network.io.direction	string	The network IO operation direction.	transmit	Recommended

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: process.thread.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.thread.count	UpDownCounter	{thread}	Process threads count.

Metric: process.open_file_descriptor.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.open_file_descriptor.count	UpDownCounter	{count}	Number of file descriptors in use by the process.

Metric: process.context_switches

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.context_switches	Counter	{count}	Number of times the process has been context switched.

Attribute	Type	Description	Examples	Requirement Level	Stability
process.context_switch_type	string	Specifies whether the context switches for this data point were voluntary or involuntary.	voluntary; involuntary	Recommended

process.context_switch_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
involuntary	involuntary
voluntary	voluntary

Metric: process.paging.faults

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.paging.faults	Counter	{fault}	Number of page faults the process has made.

Attribute	Type	Description	Examples	Requirement Level	Stability
process.paging.fault_type	string	The type of page fault for this data point. Type major is for major/hard page faults, and minor is for minor/soft page faults.	major; minor	Recommended

process.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: process.uptime

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
process.uptime	Counter	s	The time the process has been running. [1]

[1]: Instrumentations SHOULD use counter with type double and measure uptime with at least millisecond precision