semantic-conventions/docs/runtime/dotnet-metrics.md

Semantic Conventions for .NET Common Language Runtime (CLR) Metrics

Status: Experimental

This document describes semantic conventions for .NET CLR runtime metrics in OpenTelemetry.

• .NET CLR Process
  • Metric: dotnet.process.cpu.count
  • Metric: dotnet.process.cpu.time
  • Metric: dotnet.process.memory.working_set
• .NET CLR Garbage Collection
  • Metric: dotnet.gc.collections
  • Metric: dotnet.gc.heap.total_allocated
  • Metric: dotnet.gc.last_collection.memory.committed_size
  • Metric: dotnet.gc.last_collection.heap.size
  • Metric: dotnet.gc.last_collection.heap.fragmentation.size
  • Metric: dotnet.gc.pause.time
• .NET CLR Just-In-Time (JIT) Compiler
  • Metric: dotnet.jit.compiled_il.size
  • Metric: dotnet.jit.compiled_methods
  • Metric: dotnet.jit.compilation.time
• .NET CLR Thread pool
  • Metric: dotnet.thread_pool.thread.count
  • Metric: dotnet.thread_pool.work_item.count
  • Metric: dotnet.thread_pool.queue.length
• .NET CLR General
  • Metric: dotnet.monitor.lock_contentions
  • Metric: dotnet.timer.count
  • Metric: dotnet.assembly.count
  • Metric: dotnet.exceptions

.NET CLR Process

Status: Experimental

Description: .NET Common Language Runtime (CLR) metrics relating to the process, captured under the namespace dotnet.process.*.

Note: These metrics represent measurements observed from the perspective of the .NET process and may differ from metrics measured from outside the process (e.g. process.cpu.* and process.memory.usage).

Metric: dotnet.process.cpu.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.process.cpu.count	UpDownCounter	{cpu}	The number of processors available to the process. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as accessing Environment.ProcessorCount.

Metric: dotnet.process.cpu.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.process.cpu.time	Counter	s	CPU time used by the process. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as accessing the corresponding processor time properties on System.Diagnostics.Process.

Attribute	Type	Description	Examples	Requirement Level	Stability
cpu.mode	string	The mode of the CPU	user; system	Required

---

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

Metric: dotnet.process.memory.working_set

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.process.memory.working_set	UpDownCounter	By	The number of bytes of physical memory mapped to the process context. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling Environment.WorkingSet.

.NET CLR Garbage Collection

Status: Experimental

Description: .NET Common Language Runtime (CLR) metrics relating to garbage collection, captured under the namespace dotnet.gc.*.

Metric: dotnet.gc.collections

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.collections	Counter	{collection}	The number of garbage collections that have occurred since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric uses the GC.CollectionCount(int generation) API to calculate exclusive collections per generation.

Attribute	Type	Description	Examples	Requirement Level	Stability
dotnet.gc.heap.generation	string	Name of the garbage collector managed heap generation.	gen0; gen1; gen2	Required

---

dotnet.gc.heap.generation 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
gen0	Generation 0
gen1	Generation 1
gen2	Generation 2
loh	Large Object Heap
poh	Pinned Object Heap

Metric: dotnet.gc.heap.total_allocated

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.heap.total_allocated	Counter	By	The approximate number of bytes allocated on the managed GC heap since the process has started. The returned value does not include any native allocations. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling GC.GetTotalAllocatedBytes().

Metric: dotnet.gc.last_collection.memory.committed_size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.last_collection.memory.committed_size	UpDownCounter	By	The amount of committed virtual memory in use by the .NET GC, as observed during the latest garbage collection. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling GC.GetGCMemoryInfo().TotalCommittedBytes. Committed virtual memory may be larger than the heap size because it includes both memory for storing existing objects (the heap size) and some extra memory that is ready to handle newly allocated objects in the future.

Metric: dotnet.gc.last_collection.heap.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.last_collection.heap.size	UpDownCounter	By	The managed GC heap size (including fragmentation), as observed during the latest garbage collection. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes.

Attribute	Type	Description	Examples	Requirement Level	Stability
dotnet.gc.heap.generation	string	Name of the garbage collector managed heap generation.	gen0; gen1; gen2	Required

---

dotnet.gc.heap.generation 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
gen0	Generation 0
gen1	Generation 1
gen2	Generation 2
loh	Large Object Heap
poh	Pinned Object Heap

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

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.last_collection.heap.fragmentation.size	UpDownCounter	By	The heap fragmentation, as observed during the latest garbage collection. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes.

Attribute	Type	Description	Examples	Requirement Level	Stability
dotnet.gc.heap.generation	string	Name of the garbage collector managed heap generation.	gen0; gen1; gen2	Required

---

dotnet.gc.heap.generation 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
gen0	Generation 0
gen1	Generation 1
gen2	Generation 2
loh	Large Object Heap
poh	Pinned Object Heap

Metric: dotnet.gc.pause.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.gc.pause.time	Counter	s	The total amount of time paused in GC since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling GC.GetTotalPauseDuration().

.NET CLR Just-In-Time (JIT) Compiler

Status: Experimental

Description: .NET Common Language Runtime (CLR) metrics relating to the Just-In-Time compiler, captured under the namespace dotnet.jit.*.

Metric: dotnet.jit.compiled_il.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.jit.compiled_il.size	Counter	By	Count of bytes of intermediate language that have been compiled since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling JitInfo.GetCompiledILBytes().

Metric: dotnet.jit.compiled_methods

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.jit.compiled_methods	Counter	{method}	The number of times the JIT compiler (re)compiled methods since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling JitInfo.GetCompiledMethodCount().

Metric: dotnet.jit.compilation.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.jit.compilation.time	Counter	s	The amount of time the JIT compiler has spent compiling methods since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling JitInfo.GetCompilationTime().

.NET CLR Thread pool

Status: Experimental

Description: .NET Common Language Runtime (CLR) metrics relating to the thread pool, captured under the namespace dotnet.thread_pool.*.

Metric: dotnet.thread_pool.thread.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.thread_pool.thread.count	UpDownCounter	{thread}	The number of thread pool threads that currently exist. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling ThreadPool.ThreadCount.

Metric: dotnet.thread_pool.work_item.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.thread_pool.work_item.count	Counter	{work_item}	The number of work items that the thread pool has completed since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling ThreadPool.CompletedWorkItemCount.

Metric: dotnet.thread_pool.queue.length

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.thread_pool.queue.length	UpDownCounter	{work_item}	The number of work items that are currently queued to be processed by the thread pool. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling ThreadPool.PendingWorkItemCount.

.NET CLR General

Status: Experimental

Description: Other useful .NET Common Language Runtime (CLR) metrics.

Metric: dotnet.monitor.lock_contentions

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.monitor.lock_contentions	Counter	{contention}	The number of times there was contention when trying to acquire a monitor lock since the process has started. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling Monitor.LockContentionCount.

Metric: dotnet.timer.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.timer.count	UpDownCounter	{timer}	The number of timer instances that are currently active. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling Timer.ActiveCount.

Metric: dotnet.assembly.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.assembly.count	UpDownCounter	{assembly}	The number of .NET assemblies that are currently loaded. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as calling AppDomain.CurrentDomain.GetAssemblies().Length.

Metric: dotnet.exceptions

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
dotnet.exceptions	Counter	{exception}	The number of exceptions that have been thrown in managed code. [1]

[1]: Meter name: System.Runtime; Added in: .NET 9.0. This metric reports the same values as counting calls to AppDomain.CurrentDomain.FirstChanceException.

Attribute	Type	Description	Examples	Requirement Level	Stability
error.type	string	Describes a class of error the operation ended with.	System.OperationCanceledException; Contoso.MyException	Required

---

error.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
_OTHER	A fallback error value to be used when the instrumentation doesn't define a custom value.