用于 .NET 公共语言运行时 (CLR) 指标的语义约定

状态: 稳定

本文档描述了 OpenTelemetry 中 .NET CLR 运行时指标的语义约定。

.NET CLR 进程

状态: 稳定

描述: .NET 公共语言运行时 (CLR) 与进程相关的指标，捕获在命名空间 dotnet.process.* 下。

注意: 这些指标代表从 .NET 进程角度观测到的测量值，可能与从进程外部测量的指标（例如 process.cpu.* 和 process.memory.usage）不同。

Metric: dotnet.process.cpu.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.process.cpu.count	UpDownCounter	{cpu}	可供进程使用的处理器数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与访问 Environment.ProcessorCount 相同。

Metric: dotnet.process.cpu.time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.process.cpu.time	Counter	s	进程使用的 CPU 时间。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与访问 System.Diagnostics.Process 上的相应处理器时间属性相同。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cpu.mode		必需	字符串	CPU 的模式	user; system

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

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

Metric: dotnet.process.memory.working_set

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.process.memory.working_set	UpDownCounter	每个调用的最大内存使用量的分布。	映射到进程上下文的物理内存字节数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 Environment.WorkingSet 相同。

.NET CLR 垃圾回收

状态: 稳定

描述: .NET 公共语言运行时 (CLR) 与垃圾回收相关的指标，捕获在命名空间 dotnet.gc.* 下。

Metric: dotnet.gc.collections

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.collections	Counter	{collection}	自进程启动以来发生的垃圾回收次数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标使用 GC.CollectionCount(int generation) API 来计算每个代别的独占回收次数。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
dotnet.gc.heap.generation		必需	字符串	垃圾回收器托管堆代别的名称。	gen0; gen1; gen2

dotnet.gc.heap.generation 具有以下一组预定义值。如果其中一个适用，则必须使用相应的 Pinyin；否则，可以 Pinyin 自定义值。

值	描述	Stability
gen0	第 0 代
gen1	第 1 代
gen2	第 2 代
loh	大对象堆
poh	固定对象堆

Metric: dotnet.gc.heap.total_allocated

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.heap.total_allocated	Counter	每个调用的最大内存使用量的分布。	自进程启动以来在托管 GC 堆上分配的字节数（近似）。返回值不包括任何本机分配。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 GC.GetTotalAllocatedBytes() 相同。

Metric: dotnet.gc.last_collection.memory.committed_size

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.last_collection.memory.committed_size	UpDownCounter	每个调用的最大内存使用量的分布。	在最近一次垃圾回收期间观察到的 .NET GC 使用的已提交虚拟内存量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 GC.GetGCMemoryInfo().TotalCommittedBytes 相同。已提交的虚拟内存可能大于堆大小，因为它包括用于存储现有对象的内存（堆大小）以及一些准备好将来处理新分配对象的额外内存。

Metric: dotnet.gc.last_collection.heap.size

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.last_collection.heap.size	UpDownCounter	每个调用的最大内存使用量的分布。	在最近一次垃圾回收期间观察到的托管 GC 堆大小（包括碎片）。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes 相同。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
dotnet.gc.heap.generation		必需	字符串	垃圾回收器托管堆代别的名称。	gen0; gen1; gen2

dotnet.gc.heap.generation 具有以下一组预定义值。如果其中一个适用，则必须使用相应的 Pinyin；否则，可以 Pinyin 自定义值。

值	描述	Stability
gen0	第 0 代
gen1	第 1 代
gen2	第 2 代
loh	大对象堆
poh	固定对象堆

Metric: dotnet.gc.last_collection.heap.fragmentation.size

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.last_collection.heap.fragmentation.size	UpDownCounter	每个调用的最大内存使用量的分布。	在最近一次垃圾回收期间观察到的堆碎片。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes 相同。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
dotnet.gc.heap.generation		必需	字符串	垃圾回收器托管堆代别的名称。	gen0; gen1; gen2

dotnet.gc.heap.generation 具有以下一组预定义值。如果其中一个适用，则必须使用相应的 Pinyin；否则，可以 Pinyin 自定义值。

值	描述	Stability
gen0	第 0 代
gen1	第 1 代
gen2	第 2 代
loh	大对象堆
poh	固定对象堆

Metric: dotnet.gc.pause.time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.gc.pause.time	Counter	s	自进程启动以来 GC 暂停的总时间。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 GC.GetTotalPauseDuration() 相同。

.NET CLR 即时 (JIT) 编译器

状态: 稳定

描述: .NET 公共语言运行时 (CLR) 与即时编译器相关的指标，捕获在命名空间 dotnet.jit.* 下。

Metric: dotnet.jit.compiled_il.size

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.jit.compiled_il.size	Counter	每个调用的最大内存使用量的分布。	自进程启动以来已编译的中间语言的字节数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 JitInfo.GetCompiledILBytes() 相同。

Metric: dotnet.jit.compiled_methods

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.jit.compiled_methods	Counter	{method}	自进程启动以来 JIT 编译器 (重新) 编译方法的次数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 JitInfo.GetCompiledMethodCount() 相同。

Metric: dotnet.jit.compilation.time

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.jit.compilation.time	Counter	s	自进程启动以来 JIT 编译器花费在编译方法上的时间。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 JitInfo.GetCompilationTime() 相同。

.NET CLR 线程池

状态: 稳定

描述: .NET 公共语言运行时 (CLR) 与线程池相关的指标，捕获在命名空间 dotnet.thread_pool.* 下。

Metric: dotnet.thread_pool.thread.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.thread_pool.thread.count	UpDownCounter	{thread}	当前存在的线程池线程数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 ThreadPool.ThreadCount 相同。

Metric: dotnet.thread_pool.work_item.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.thread_pool.work_item.count	Counter	{work_item}	自进程启动以来线程池已完成的工作项数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 ThreadPool.CompletedWorkItemCount 相同。

Metric: dotnet.thread_pool.queue.length

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.thread_pool.queue.length	UpDownCounter	{work_item}	当前排队等待线程池处理的工作项数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 ThreadPool.PendingWorkItemCount 相同。

.NET CLR 常规

状态: 稳定

描述: 其他有用的 .NET 公共语言运行时 (CLR) 指标。

Metric: dotnet.monitor.lock_contentions

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.monitor.lock_contentions	Counter	{contention}	自进程启动以来尝试获取监视器锁时发生争用的次数。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 Monitor.LockContentionCount 相同。

Metric: dotnet.timer.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.timer.count	UpDownCounter	{timer}	当前活动的计时器实例数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 Timer.ActiveCount 相同。

Metric: dotnet.assembly.count

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.assembly.count	UpDownCounter	{assembly}	当前加载的 .NET 程序集数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与调用 AppDomain.CurrentDomain.GetAssemblies().Length 相同。

Metric: dotnet.exceptions

此指标是推荐的。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
dotnet.exceptions	Counter	{exception}	在托管代码中抛出的异常数量。 [1]

[1]: Meter 名称: System.Runtime；添加于: .NET 9.0。此指标报告的值与计算调用 AppDomain.CurrentDomain.FirstChanceException 的次数相同。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
error.type		必需	字符串	描述了操作结束时的一类错误。	System.OperationCanceledException; Contoso.MyException

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

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。