系统指标的语义约定

状态: 开发中

本文档描述了 OpenTelemetry 中常见系统级指标的仪器和属性。在创建规格中未明确定义的仪器时，请考虑 通用指标语义约定。

system.* 命名空间应仅用于报告主机的指标。system.* 命名空间仅应在指标从目标系统（物理服务器、虚拟机等）内部收集时使用。从特定于技术、定义明确的 API（例如 Kubelet 的 API 或容器运行时）收集的指标应在其各自的命名空间下报告（例如，k8s.*、container.*）。与主机相关的资源属性应在 host.* 命名空间下报告。

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

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

通用指标

指标: system.uptime

此指标是推荐的。

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

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

处理器指标

描述: 在 system.cpu 命名空间下捕获的系统级处理器指标。

指标: system.cpu.physical.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.cpu.physical.count	UpDownCounter	{cpu}	报告硬件上的实际物理处理器核心数。[1]		host

[1]: 通过将插槽数乘以每个插槽的核心数来计算。

指标: system.cpu.logical.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.cpu.logical.count	UpDownCounter	{cpu}	报告由操作系统管理多任务处理创建的逻辑（虚拟）处理器核心数。[1]		host

[1]: 通过将插槽数乘以每个插槽的核心数，然后乘以每个核心的线程数来计算。

指标: system.cpu.time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.cpu.time	Counter	s	每个逻辑 CPU 在每种模式下花费的秒数。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.mode		推荐	字符串	CPU 的模式 [1]	user; system
cpu.logical_number		选择加入	int	逻辑 CPU 编号 [0..n-1]	1

[1] cpu.mode: 应使用以下状态：user、system、nice、idle、iowait、interrupt、steal。

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

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

指标: system.cpu.frequency

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.cpu.frequency	Gauge	赫兹	逻辑 CPU 的运行频率（以赫兹为单位）。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.logical_number		推荐	int	逻辑 CPU 编号 [0..n-1]	1

指标: system.cpu.utilization

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.cpu.utilization	Gauge	1	对于每个逻辑 CPU，利用率计算为在测量间隔内累积 CPU 时间（cpu.time）的变化除以经过的时间。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.mode		推荐	字符串	CPU 的模式 [1]	user; system
cpu.logical_number		选择加入	int	逻辑 CPU 编号 [0..n-1]	1

[1] cpu.mode: 应使用以下模式：user、system、nice、idle、iowait、interrupt、steal。

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

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

内存指标

描述: 在 system.memory 命名空间下捕获的系统级内存指标。这不包括 分页/交换内存。

指标: system.memory.usage

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.memory.usage	UpDownCounter	每个调用的最大内存使用量的分布。	按状态报告使用中的内存。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.memory.state		推荐	字符串	内存状态	free; cached

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

值	描述	Stability
buffers	buffers
cached	cached
free	free
used	实际使用的虚拟内存（以字节为单位）。[1]

[1]: 基于操作系统指标的计算。在 Linux 上，这对应于 /proc/meminfo 中的“MemTotal - MemAvailable”，它比基于 free、cached 和 buffers 的旧公式更准确地反映了应用程序实际使用的内存。如果 MemAvailable 不可用，则可以使用旧公式进行回退。

指标: system.memory.limit

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.memory.limit	UpDownCounter	每个调用的最大内存使用量的分布。	系统中可用的总虚拟内存。		host

指标: system.memory.shared

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.memory.shared	UpDownCounter	每个调用的最大内存使用量的分布。	使用的共享内存（主要由 tmpfs 使用）。[1]		host

[1]: 相当于 free 命令的 shared 或 /proc/meminfo 的 Shmem。

指标: system.memory.utilization

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.memory.utilization	Gauge	1	已使用内存字节的百分比。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.memory.state		推荐	字符串	内存状态	free; cached

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

值	描述	Stability
buffers	buffers
cached	cached
free	free
used	实际使用的虚拟内存（以字节为单位）。[1]

[1]: 基于操作系统指标的计算。在 Linux 上，这对应于 /proc/meminfo 中的“MemTotal - MemAvailable”，它比基于 free、cached 和 buffers 的旧公式更准确地反映了应用程序实际使用的内存。如果 MemAvailable 不可用，则可以使用旧公式进行回退。

分页/交换指标

描述: 在 system.paging 命名空间下捕获的系统级分页/交换内存指标。

指标: system.paging.usage

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.paging.usage	UpDownCounter	每个调用的最大内存使用量的分布。	Unix 交换或 Windows 页面文件使用情况。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	负责管理分页操作的设备的唯一标识符。	/dev/dm-0
system.paging.state		推荐	字符串	内存分页状态	free

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

值	描述	Stability
free	free
used	used

指标: system.paging.utilization

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.paging.utilization	Gauge	1	交换（Unix）或页面文件（Windows）的利用率。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	负责管理分页操作的设备的唯一标识符。	/dev/dm-0
system.paging.state		推荐	字符串	内存分页状态	free

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

值	描述	Stability
free	free
used	used

指标: system.paging.faults

此指标是推荐的。

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

Attributes

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

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

值	描述	Stability
major	major
minor	minor

指标: system.paging.operations

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.paging.operations	Counter	{operation}	分页操作的数量。		host

Attributes

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

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

值	描述	Stability
in	in
out	out

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

值	描述	Stability
major	major
minor	minor

磁盘控制器指标

描述: 在 system.disk 命名空间下捕获的系统级磁盘性能指标。

指标: system.disk.io

此指标是推荐的。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
disk.io.direction		推荐	字符串	磁盘 IO 操作方向。	read
system.device		推荐	字符串	设备标识符	(identifier)

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

值	描述	Stability
read	read
write	write

指标: system.disk.operations

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.disk.operations	Counter	{operation}	磁盘操作计数。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
disk.io.direction		推荐	字符串	磁盘 IO 操作方向。	read
system.device		推荐	字符串	设备标识符	(identifier)

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

值	描述	Stability
read	read
write	write

指标: system.disk.io_time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.disk.io_time	Counter	s	磁盘激活时间。[1]		host

[1]: I/O 路径中使用的实际经过时间（“挂钟时间”）（不计算并行运行的操作时间）。测量方式为：

• Linux: procfs-diskstats 的第 13 个字段
• Windows: “Disk% Idle Time” 性能计数器的补数：uptime * (100 - "Disk\% Idle Time") / 100

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	设备标识符	(identifier)

指标: system.disk.operation_time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.disk.operation_time	Counter	s	每次操作花费的总时间。[1]		host

[1]: 由于它是每个请求花费时间的总和，因此并行发出的请求都会计入计数器增长。测量方式为：

• Linux: procfs-diskstats 的第 7 和 11 个字段
• Windows: “Avg. Disk sec/Read” 性能计数器乘以“Disk Reads/sec”性能计数器（写入操作类似）

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
disk.io.direction		推荐	字符串	磁盘 IO 操作方向。	read
system.device		推荐	字符串	设备标识符	(identifier)

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

值	描述	Stability
read	read
write	write

指标: system.disk.merged

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.disk.merged	Counter	{operation}	合并为单个物理磁盘访问操作的磁盘读/写次数。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
disk.io.direction		推荐	字符串	磁盘 IO 操作方向。	read
system.device		推荐	字符串	设备标识符	(identifier)

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

值	描述	Stability
read	read
write	write

指标: system.disk.limit

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.disk.limit	UpDownCounter	每个调用的最大内存使用量的分布。	磁盘的总存储容量。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	设备标识符	(identifier)

文件系统指标

描述: 在 system.filesystem 命名空间下捕获的系统级文件系统指标。

指标: system.filesystem.usage

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.filesystem.usage	UpDownCounter	每个调用的最大内存使用量的分布。	报告文件系统在不同状态下的空间使用情况。[1]		host

[1]: 所有 system.filesystem.usage 值在不同 system.filesystem.state 属性上的总和应等于文件系统的总存储容量，即 system.filesystem.limit。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	文件系统所在的设备标识符。	/dev/sda; \network-drive
system.filesystem.mode		推荐	字符串	文件系统模式	rw, ro
system.filesystem.mountpoint		推荐	字符串	文件系统挂载路径	/mnt/data
system.filesystem.state		推荐	字符串	文件系统状态	used
system.filesystem.type		推荐	字符串	文件系统类型	ext4

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

值	描述	Stability
free	free
reserved	reserved
used	used

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

值	描述	Stability
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

指标: system.filesystem.utilization

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.filesystem.utilization	Gauge	1	已使用的文件系统字节的比例。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	文件系统所在的设备标识符。	/dev/sda; \network-drive
system.filesystem.mode		推荐	字符串	文件系统模式	rw, ro
system.filesystem.mountpoint		推荐	字符串	文件系统挂载路径	/mnt/data
system.filesystem.state		推荐	字符串	文件系统状态	used
system.filesystem.type		推荐	字符串	文件系统类型	ext4

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

值	描述	Stability
free	free
reserved	reserved
used	used

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

值	描述	Stability
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

指标: system.filesystem.limit

此指标为 opt-in。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.filesystem.limit	UpDownCounter	每个调用的最大内存使用量的分布。	文件系统的总存储容量。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
system.device		推荐	字符串	文件系统所在的设备标识符。	/dev/sda; \network-drive
system.filesystem.mode		推荐	字符串	文件系统模式	rw, ro
system.filesystem.mountpoint		推荐	字符串	文件系统挂载路径	/mnt/data
system.filesystem.type		推荐	字符串	文件系统类型	ext4

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

值	描述	Stability
exfat	exfat
ext4	ext4
fat32	fat32
hfsplus	hfsplus
ntfs	ntfs
refs	refs

网络指标

描述: 在 system.network 命名空间下捕获的系统级网络指标。

指标: system.network.packet.dropped

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.network.packet.dropped	Counter	{packet}	即使没有错误，被丢弃或丢弃的数据包数量。[1]		host

[1]: 测量方式为：

• Linux: /proc/net/dev 中的 drop 列（来源）
• Windows: InDiscards/OutDiscards 从 GetIfEntry2

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.interface.name		推荐	字符串	网络接口名称。	lo; eth0
network.io.direction		推荐	字符串	网络 IO 操作方向。	transmit

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

值	描述	Stability
receive	receive
transmit	transmit

指标: system.network.packet.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.network.packet.count	Counter	{packet}	传输的数据包数量。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.io.direction		推荐	字符串	网络 IO 操作方向。	transmit
system.device		推荐	字符串	设备标识符	(identifier)

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

值	描述	Stability
receive	receive
transmit	transmit

指标: system.network.errors

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.network.errors	Counter	{error}	检测到的网络错误数量。[1]		host

[1]: 测量方式为：

• Linux: /proc/net/dev 中的 errs 列（来源）。
• Windows: InErrors/OutErrors 从 GetIfEntry2。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.interface.name		推荐	字符串	网络接口名称。	lo; eth0
network.io.direction		推荐	字符串	网络 IO 操作方向。	transmit

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

值	描述	Stability
receive	receive
transmit	transmit

指标: system.network.io

此指标是推荐的。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.interface.name		推荐	字符串	网络接口名称。	lo; eth0
network.io.direction		推荐	字符串	网络 IO 操作方向。	transmit

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

值	描述	Stability
receive	receive
transmit	transmit

指标: system.network.connection.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.network.connection.count	UpDownCounter	{connection}	连接数。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
network.connection.state		推荐	字符串	网络连接的状态 [1]	close_wait
network.interface.name		推荐	字符串	网络接口名称。	lo; eth0
network.transport		推荐	字符串	OSI 传输层或进程间通信方法。[2]	tcp；udp

[1] network.connection.state: 连接状态根据 rfc9293 定义。

[2] network.transport: 值应小写标准化。

在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

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

值	描述	Stability
close_wait	close_wait
closed	closed
closing	closing
established	established
fin_wait_1	fin_wait_1
fin_wait_2	fin_wait_2
last_ack	last_ack
listen	listen
syn_received	syn_received
syn_sent	syn_sent
time_wait	time_wait

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

值	描述	Stability
pipe	命名或匿名管道。
quic	QUIC
tcp	TCP
udp	UDP
unix	Unix 域套接字

聚合系统进程指标

描述: 在 system.process 命名空间下捕获的系统级聚合进程指标。对于单个进程级别的指标，请参阅 进程指标。

指标: system.process.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.process.count	UpDownCounter	{process}	处于每个状态的进程总数。		host

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
process.state		推荐	字符串	进程状态，例如 Linux 进程状态代码。	running

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

值	描述	Stability
defunct	defunct
running	running
sleeping	sleeping
stopped	stopped

指标: system.process.created

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.process.created	Counter	{process}	主机运行期间创建的进程总数。		host

system.{os}. - OS 特定系统指标

具有不同且在多个操作系统上具有冲突含义的系统级指标的仪器名称应以 system.{os}. 作为前缀，并遵循上面列出的不同实体的层次结构，如 CPU、内存和网络。

例如，UNIX 负载平均值在给定时间间隔内并不标准化，并且尽管处于相似的负载下，其在不同类 Unix 系统上的值也可能不同。

在不深入探讨存在的所有类 Unix 操作系统的细微差别的情况下，负载平均值或多或少代表了正在运行（使用 CPU）或可运行（等待 CPU）状态的进程的平均数量。存在一个显着的例外：Linux 包括处于不可中断睡眠状态的进程，通常在等待某些 I/O 活动完成。这可能会显著增加 Linux 系统的负载平均值。

(引用来源, Linux 源代码)

Linux 上 1 分钟的负载平均值的仪器可以命名为 system.linux.cpu.load_1m，重用上面提出的 cpu 名称，并具有 {os} 前缀以在不同操作系统之间区分此指标。

指标: system.linux.memory.available

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.linux.memory.available	UpDownCounter	每个调用的最大内存使用量的分布。	可用于启动新应用程序而不会导致交换的内存量的估计值。[1]		host

[1]: 这是 system.memory.usage 指标（状态为 free）的替代方案。Linux 从 3.14 开始导出“可用”内存。它以“free”内存为基准，然后考虑内核特定的值。这应该比仅“free”内存更准确。有关参考，请参阅 此处的计算。另请参阅 /proc/meminfo 中的 MemAvailable。

指标: system.linux.memory.slab.usage

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
system.linux.memory.slab.usage	UpDownCounter	每个调用的最大内存使用量的分布。	报告 Linux 内核用于管理常用对象缓存的内存。[1]		host

[1]: linux.memory.slab.usage 中 reclaimable 和 unreclaimable 状态值的总和应等于系统中可用的总 Slab 内存。请注意，总 Slab 内存不是恒定的，并且可能会随时间变化。另请参阅 Slab 分配器和 /proc/meminfo 中的 Slab。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
linux.memory.slab.state		推荐	字符串	Linux Slab 内存状态	reclaimable; unreclaimable

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

值	描述	Stability
reclaimable	reclaimable
unreclaimable	unreclaimable