OS 进程指标的语义约定

状态: 开发中

本文档描述了 OpenTelemetry 中常见的 OS 进程级指标的仪表和属性。在创建本文档中未明确定义的仪表时，也请考虑通用的指标语义约定。OS 进程指标与程序的运行时环境无关，应从操作系统获取测量值。有关运行时环境指标，请参阅运行时环境指标的语义约定。

警告 现有仪表和收集器如果正在使用本文档的 v1.21.0 版本（或更早版本）

• 在系统语义约定被标记为稳定之前，SHOULD NOT 采纳文档中的任何重大更改。约定包括但不限于属性、指标名称和计量单位。
• 在迁移计划最终确定后，SHOULD 引入一种控制机制，允许用户选择加入新的约定。

进程指标

指标: process.cpu.time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.cpu.time	Counter	s	按不同状态分解的总 CPU 秒数。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.mode		推荐	字符串	进程 SHOULD 仅使用没有 mode 标签的数据点进行表征，或仅使用带有 mode 标签的数据点进行表征。[1]	user; system

[1] cpu.mode: SHOULD 使用以下状态： user、system、wait

cpu.mode 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以（MAY）使用自定义值。

值	描述	Stability
idle	空闲
interrupt	中断
iowait	IO 等待
kernel	内核
nice	Nice
steal	Steal
system	系统
user	User

指标: process.cpu.utilization

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.cpu.utilization	Gauge	1	与上次测量相比，process.cpu.time 的差值，除以经过的时间和进程可用的 CPU 数量。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.mode		推荐	字符串	进程 SHOULD 仅使用没有 mode 标签的数据点进行表征，或仅使用带有 mode 标签的数据点进行表征。[1]	user; system

[1] cpu.mode: SHOULD 使用以下状态： user、system、wait

cpu.mode 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以（MAY）使用自定义值。

值	描述	Stability
idle	空闲
interrupt	中断
iowait	IO 等待
kernel	内核
nice	Nice
steal	Steal
system	系统
user	User

指标: process.memory.usage

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.memory.usage	UpDownCounter	每个调用的最大内存使用量的分布。	已使用的物理内存量。		process

指标: process.memory.virtual

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.memory.virtual	UpDownCounter	每个调用的最大内存使用量的分布。	已提交的虚拟内存量。		process

指标: process.disk.io

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.disk.io	Counter	每个调用的最大内存使用量的分布。	已传输的磁盘字节数。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
disk.io.direction		推荐	字符串	磁盘 IO 操作方向。	read

disk.io.direction 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以（MAY）使用自定义值。

值	描述	Stability
read	read
write	write

指标: process.network.io

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.network.io	Counter	每个调用的最大内存使用量的分布。	已传输的网络字节数。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.io.direction		推荐	字符串	网络 IO 操作方向。	transmit

network.io.direction 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
receive	receive
transmit	transmit

指标: process.thread.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.thread.count	UpDownCounter	{thread}	进程线程数。		process

指标: process.open_file_descriptor.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.open_file_descriptor.count	UpDownCounter	{file_descriptor}	进程使用的文件描述符数量。		process

指标: process.context_switches

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.context_switches	Counter	{context_switch}	进程发生上下文切换的次数。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
process.context_switch.type		推荐	字符串	指定此数据点的上下文切换是自愿的还是非自愿的。	voluntary; involuntary

process.context_switch.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以根据需要使用自定义值。

值	描述	Stability
involuntary	involuntary
voluntary	voluntary

指标: process.paging.faults

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.paging.faults	Counter	{fault}	进程发生的页面错误数量。		process

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.paging.fault.type		推荐	字符串	分页错误类型	minor

system.paging.fault.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以（MAY）使用自定义值。

值	描述	Stability
major	major
minor	minor

指标: process.uptime

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
process.uptime	Gauge	s	进程运行的时间。[1]		process

[1]: 观测点 SHOULD 使用类型为 double 的 gauge，并以秒为单位测量运行时间，作为具有最高可用精度的浮点数。实际精度取决于观测点和操作系统。