Semantic conventions for OS process metrics

Status: Development

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.

• Process metrics
  • Metric: process.cpu.time
  • Metric: process.cpu.utilization
  • Metric: process.memory.usage
  • Metric: process.memory.virtual
  • Metric: process.disk.io
  • Metric: process.network.io
  • Metric: process.thread.count
  • Metric: process.unix.file_descriptor.count
  • Metric: process.windows.handle.count
  • Metric: process.context_switches
  • Metric: process.paging.faults
  • Metric: process.uptime

Process metrics

Metric: process.cpu.time

This metric is recommended.

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cpu.mode		Required	string	The CPU mode for this data point. [1]	user; system

[1] cpu.mode: The following values for cpu.mode SHOULD be used: user, system, wait Other modes SHOULD NOT be used unless a particular platform mandates a unique set of modes.

---

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
nice	Nice
steal	Steal
system	System
user	User

Metric: process.cpu.utilization

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
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.		process

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cpu.mode		Required	string	The CPU mode for this data point. [1]	user; system

[1] cpu.mode: The following values for cpu.mode SHOULD be used: user, system, wait Other modes SHOULD NOT be used unless a particular platform mandates a unique set of modes.

---

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
nice	Nice
steal	Steal
system	System
user	User

Metric: process.memory.usage

This metric is recommended.

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

Metric: process.memory.virtual

This metric is recommended.

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

Metric: process.disk.io

This metric is recommended.

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
disk.io.direction		Required	string	The disk IO operation direction.	read

---

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	Entity Associations
process.network.io	Counter	By	Network bytes transferred.		process

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.io.direction		Required	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: process.thread.count

This metric is recommended.

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

Metric: process.unix.file_descriptor.count

This metric is recommended.

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

Metric: process.windows.handle.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
process.windows.handle.count	UpDownCounter	{handle}	Number of handles held by the process.		process

Metric: process.context_switches

This metric is recommended.

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
process.context_switch.type		Required	string	Specifies whether the context switches for this data point were voluntary or involuntary.	voluntary; involuntary

---

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	Entity Associations
process.paging.faults	Counter	{fault}	Number of page faults the process has made.		process

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
system.paging.fault.type		Recommended	string	The type of paging fault. Value MUST be either major or minor. If the metric is reported without this attribute, it should be the sum of major and minor page faults.	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: process.uptime

This metric is recommended.

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

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