open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
semantic-conventions/docs/runtime/dotnet-metrics.md

29 KiB
Raw Permalink Blame History

Semantic conventions for .NET Common Language Runtime (CLR) metrics

Status: Stable

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

.NET CLR Process

Status: Stable

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 Entity Associations
dotnet.process.cpu.count UpDownCounter {cpu} The number of processors available to the process. [1] Stable

[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 Entity Associations
dotnet.process.cpu.time Counter s CPU time used by the process. [1] Stable

[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 Development

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 Development
interrupt interrupt Development
iowait iowait Development
kernel kernel Development
nice nice Development
steal steal Development
system system Development
user user Development

Metric: dotnet.process.memory.working_set

This metric is recommended.

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

[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: Stable

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 Entity Associations
dotnet.gc.collections Counter {collection} The number of garbage collections that have occurred since the process has started. [1] Stable

[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 Stable

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 Stable
gen1 Generation 1 Stable
gen2 Generation 2 Stable
loh Large Object Heap Stable
poh Pinned Object Heap Stable

Metric: dotnet.gc.heap.total_allocated

This metric is recommended.

Name Instrument Type Unit (UCUM) Description Stability Entity Associations
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] Stable

[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 Entity Associations
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] Stable

[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 Entity Associations
dotnet.gc.last_collection.heap.size UpDownCounter By The managed GC heap size (including fragmentation), as observed during the latest garbage collection. [1] Stable

[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 Stable

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 Stable
gen1 Generation 1 Stable
gen2 Generation 2 Stable
loh Large Object Heap Stable
poh Pinned Object Heap Stable

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

This metric is recommended.

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

[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 Stable

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 Stable
gen1 Generation 1 Stable
gen2 Generation 2 Stable
loh Large Object Heap Stable
poh Pinned Object Heap Stable

Metric: dotnet.gc.pause.time

This metric is recommended.

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

[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: Stable

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 Entity Associations
dotnet.jit.compiled_il.size Counter By Count of bytes of intermediate language that have been compiled since the process has started. [1] Stable

[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 Entity Associations
dotnet.jit.compiled_methods Counter {method} The number of times the JIT compiler (re)compiled methods since the process has started. [1] Stable

[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 Entity Associations
dotnet.jit.compilation.time Counter s The amount of time the JIT compiler has spent compiling methods since the process has started. [1] Stable

[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: Stable

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 Entity Associations
dotnet.thread_pool.thread.count UpDownCounter {thread} The number of thread pool threads that currently exist. [1] Stable

[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 Entity Associations
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] Stable

[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 Entity Associations
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] Stable

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

.NET CLR General

Status: Stable

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 Entity Associations
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] Stable

[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 Entity Associations
dotnet.timer.count UpDownCounter {timer} The number of timer instances that are currently active. [1] Stable

[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 Entity Associations
dotnet.assembly.count UpDownCounter {assembly} The number of .NET assemblies that are currently loaded. [1] Stable

[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 Entity Associations
dotnet.exceptions Counter {exception} The number of exceptions that have been thrown in managed code. [1] Stable

[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 Stable

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. Stable