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.
- 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.open_file_descriptor.count - Metric:
process.context_switches - Metric:
process.paging.faults - Metric:
process.uptime
- Metric:
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.
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] cpu.mode: 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 | |
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] cpu.mode: 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 | |
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
process.memory.usage |
UpDownCounter | By |
The amount of physical memory in use. | |
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
process.memory.virtual |
UpDownCounter | By |
The amount of committed virtual memory. | |
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 | |
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 | |
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
process.thread.count |
UpDownCounter | {thread} |
Process threads 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. | |
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 | |
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 | |
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
process.uptime |
Gauge | s |
The time the process has been running. [1] | |
[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.