Skip to content

process-metrics.md

Latest commit

 

History

History
364 lines (262 loc) · 18 KB

process-metrics.md

File metadata and controls

364 lines (262 loc) · 18 KB

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.

Important

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 Entity Associations
process.cpu.time Counter s Total CPU seconds broken down by different CPU modes. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
cpu.mode Development 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 Development
interrupt Interrupt Development
iowait IO Wait Development
kernel Kernel Development
nice Nice Development
steal Steal Development
system System Development
user User Development

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. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
cpu.mode Development 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 Development
interrupt Interrupt Development
iowait IO Wait Development
kernel Kernel Development
nice Nice Development
steal Steal Development
system System Development
user User Development

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. Development 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. Development 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. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
disk.io.direction Development 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 Development
write write Development

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. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
network.io.direction Development 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 Development
transmit transmit Development

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. Development 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. Development 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. Development 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. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
process.context_switch.type Development 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 Development
voluntary voluntary Development

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. Development process

Attributes:

Key Stability Requirement Level Value Type Description Example Values
system.paging.fault.type Development 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 Development
minor minor Development

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] Development 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.