diff --git a/.chloggen/clr-runtime.yaml b/.chloggen/clr-runtime.yaml new file mode 100644 index 0000000000..ecad868a1c --- /dev/null +++ b/.chloggen/clr-runtime.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: dotnet + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds experimental metrics for the .NET Common Language Runtime (CLR)." + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [956] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7e4202ff76..9be2aef1a2 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -65,10 +65,13 @@ /model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers # .NET semantic conventions approvers -/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers -/model/registry/aspnetcore.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers -/model/registry/signalr.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers -/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/registry/aspnetcore.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/registry/signalr.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/metrics/dotnet-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver +/model/registry/dotnet.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver +/docs/runtime/dotnet-metrics.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver # Gen-AI semantic conventions approvers /model/registry/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index ef601a5b8e..e808ec4b1e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -39,6 +39,7 @@ body: - area:device - area:disk - area:dns + - area:dotnet - area:error - area:event - area:exception diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index d2a5bca98c..6717c98fba 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -31,6 +31,7 @@ body: - area:device - area:disk - area:dns + - area:dotnet - area:error - area:event - area:exception diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 610edd03cb..5df4d54de4 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -40,6 +40,7 @@ body: - area:device - area:disk - area:dns + - area:dotnet - area:error - area:event - area:exception diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 119a6c1437..2a3894f1b7 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -50,6 +50,7 @@ Currently, the following namespaces exist: - [Device](device.md) - [Disk](disk.md) - [Dns](dns.md) +- [Dotnet](dotnet.md) - [Enduser](enduser.md) - [Error](error.md) - [Event](event.md) diff --git a/docs/attributes-registry/dotnet.md b/docs/attributes-registry/dotnet.md new file mode 100644 index 0000000000..28acf6e429 --- /dev/null +++ b/docs/attributes-registry/dotnet.md @@ -0,0 +1,25 @@ + + + + + +# Dotnet + +## .NET Attributes + +This document defines .NET related attributes. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ------ | ------------------------------------------------------ | ---------------------- | ---------------------------------------------------------------- | +| `dotnet.gc.heap.generation` | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen1` | Generation 1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen2` | Generation 2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `loh` | Large Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `poh` | Pinned Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 7f17940f36..f04801dd0d 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -51,6 +51,7 @@ semantic conventions when instrumenting runtime environments. - [JVM](jvm-metrics.md) - [Node.js](nodejs-metrics.md) - [V8 JS Engine](v8js-metrics.md) +- [.NET](dotnet-metrics.md) ### Attributes diff --git a/docs/runtime/dotnet-metrics.md b/docs/runtime/dotnet-metrics.md new file mode 100644 index 0000000000..b9ad04bb77 --- /dev/null +++ b/docs/runtime/dotnet-metrics.md @@ -0,0 +1,890 @@ + + +# Semantic Conventions for .NET Common Language Runtime (CLR) Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for .NET CLR runtime metrics in OpenTelemetry. + + + + + +- [.NET CLR Process](#net-clr-process) + - [Metric: `dotnet.process.cpu.count`](#metric-dotnetprocesscpucount) + - [Metric: `dotnet.process.cpu.time`](#metric-dotnetprocesscputime) + - [Metric: `dotnet.process.memory.working_set`](#metric-dotnetprocessmemoryworking_set) +- [.NET CLR Garbage Collection](#net-clr-garbage-collection) + - [Metric: `dotnet.gc.collections`](#metric-dotnetgccollections) + - [Metric: `dotnet.gc.heap.total_allocated`](#metric-dotnetgcheaptotal_allocated) + - [Metric: `dotnet.gc.last_collection.memory.committed_size`](#metric-dotnetgclast_collectionmemorycommitted_size) + - [Metric: `dotnet.gc.last_collection.heap.size`](#metric-dotnetgclast_collectionheapsize) + - [Metric: `dotnet.gc.last_collection.heap.fragmentation.size`](#metric-dotnetgclast_collectionheapfragmentationsize) + - [Metric: `dotnet.gc.pause.time`](#metric-dotnetgcpausetime) +- [.NET CLR Just-In-Time (JIT) Compiler](#net-clr-just-in-time-jit-compiler) + - [Metric: `dotnet.jit.compiled_il.size`](#metric-dotnetjitcompiled_ilsize) + - [Metric: `dotnet.jit.compiled_methods`](#metric-dotnetjitcompiled_methods) + - [Metric: `dotnet.jit.compilation.time`](#metric-dotnetjitcompilationtime) +- [.NET CLR Thread pool](#net-clr-thread-pool) + - [Metric: `dotnet.thread_pool.thread.count`](#metric-dotnetthread_poolthreadcount) + - [Metric: `dotnet.thread_pool.work_item.count`](#metric-dotnetthread_poolwork_itemcount) + - [Metric: `dotnet.thread_pool.queue.length`](#metric-dotnetthread_poolqueuelength) +- [.NET CLR General](#net-clr-general) + - [Metric: `dotnet.monitor.lock_contentions`](#metric-dotnetmonitorlock_contentions) + - [Metric: `dotnet.timer.count`](#metric-dotnettimercount) + - [Metric: `dotnet.assembly.count`](#metric-dotnetassemblycount) + - [Metric: `dotnet.exceptions`](#metric-dotnetexceptions) + + + +## .NET CLR Process + +**Status**: [Experimental][DocumentStatus] + +**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][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.process.cpu.count` | UpDownCounter | `{cpu}` | The number of processors available to the process. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as accessing [`Environment.ProcessorCount`](https://learn.microsoft.com/dotnet/api/system.environment.processorcount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.process.cpu.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.process.cpu.time` | Counter | `s` | CPU time used by the process. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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`](https://learn.microsoft.com/dotnet/api/system.diagnostics.process). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The mode of the CPU | `user`; `system` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `dotnet.process.memory.working_set` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`Environment.WorkingSet`](https://learn.microsoft.com/dotnet/api/system.environment.workingset). + + + + + + + + + + + + + + + + + + + + + +## .NET CLR Garbage Collection + +**Status**: [Experimental][DocumentStatus] + +**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][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric uses the [`GC.CollectionCount(int generation)`](https://learn.microsoft.com/dotnet/api/system.gc.collectioncount) API to calculate exclusive collections per generation. + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen1` | Generation 1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen2` | Generation 2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `loh` | Large Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `poh` | Pinned Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `dotnet.gc.heap.total_allocated` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`GC.GetTotalAllocatedBytes()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalallocatedbytes). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.gc.last_collection.memory.committed_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`GC.GetGCMemoryInfo().TotalCommittedBytes`](https://learn.microsoft.com/dotnet/api/system.gcmemoryinfo.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][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.sizeafterbytes). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen1` | Generation 1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen2` | Generation 2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `loh` | Large Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `poh` | Pinned Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `dotnet.gc.last_collection.heap.fragmentation.size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.fragmentationafterbytes). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen1` | Generation 1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen2` | Generation 2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `loh` | Large Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `poh` | Pinned Object Heap | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `dotnet.gc.pause.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`GC.GetTotalPauseDuration()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalpauseduration). + + + + + + + + + + + + + + + + + + + + + +## .NET CLR Just-In-Time (JIT) Compiler + +**Status**: [Experimental][DocumentStatus] + +**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][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`JitInfo.GetCompiledILBytes()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledilbytes). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.jit.compiled_methods` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`JitInfo.GetCompiledMethodCount()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledmethodcount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.jit.compilation.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`JitInfo.GetCompilationTime()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompilationtime). + + + + + + + + + + + + + + + + + + + + + +## .NET CLR Thread pool + +**Status**: [Experimental][DocumentStatus] + +**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][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.thread_pool.thread.count` | UpDownCounter | `{thread}` | The number of thread pool threads that currently exist. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`ThreadPool.ThreadCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.threadcount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.thread_pool.work_item.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`ThreadPool.CompletedWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.completedworkitemcount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.thread_pool.queue.length` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`ThreadPool.PendingWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.pendingworkitemcount). + + + + + + + + + + + + + + + + + + + + + +## .NET CLR General + +**Status**: [Experimental][DocumentStatus] + +**Description:** Other useful .NET Common Language Runtime (CLR) metrics. + +### Metric: `dotnet.monitor.lock_contentions` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`Monitor.LockContentionCount`](https://learn.microsoft.com/dotnet/api/system.threading.monitor.lockcontentioncount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.timer.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.timer.count` | UpDownCounter | `{timer}` | The number of timer instances that are currently active. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`Timer.ActiveCount`](https://learn.microsoft.com/dotnet/api/system.threading.timer.activecount). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.assembly.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.assembly.count` | UpDownCounter | `{assembly}` | The number of .NET assemblies that are currently loaded. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as calling [`AppDomain.CurrentDomain.GetAssemblies().Length`](https://learn.microsoft.com/dotnet/api/system.appdomain.getassemblies). + + + + + + + + + + + + + + + + + + + + + +### Metric: `dotnet.exceptions` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dotnet.exceptions` | Counter | `{exception}` | The number of exceptions that have been thrown in managed code. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0. +This metric reports the same values as counting calls to [`AppDomain.CurrentDomain.FirstChanceException`](https://learn.microsoft.com/dotnet/api/system.appdomain.firstchanceexception). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. | `System.OperationCanceledException`; `Contoso.MyException` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/metrics/dotnet-metrics.yaml b/model/metrics/dotnet-metrics.yaml new file mode 100644 index 0000000000..313ee3b574 --- /dev/null +++ b/model/metrics/dotnet-metrics.yaml @@ -0,0 +1,279 @@ +groups: + - id: metric.dotnet.process.cpu.count + type: metric + metric_name: dotnet.process.cpu.count + brief: "The number of processors available to the process." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as accessing [`Environment.ProcessorCount`](https://learn.microsoft.com/dotnet/api/system.environment.processorcount). + instrument: updowncounter + unit: "{cpu}" + stability: experimental + + - id: metric.dotnet.process.cpu.time + type: metric + metric_name: dotnet.process.cpu.time + brief: "CPU time used by the process." + note: > + 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`](https://learn.microsoft.com/dotnet/api/system.diagnostics.process). + instrument: counter + unit: "s" + stability: experimental + attributes: + - ref: cpu.mode + requirement_level: required + + - id: metric.dotnet.process.memory.working_set + type: metric + metric_name: dotnet.process.memory.working_set + brief: "The number of bytes of physical memory mapped to the process context." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling [`Environment.WorkingSet`](https://learn.microsoft.com/dotnet/api/system.environment.workingset). + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.dotnet.gc.collections + type: metric + metric_name: dotnet.gc.collections + brief: "The number of garbage collections that have occurred since the process has started." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric uses the [`GC.CollectionCount(int generation)`](https://learn.microsoft.com/dotnet/api/system.gc.collectioncount) + API to calculate exclusive collections per generation. + instrument: counter + unit: "{collection}" + stability: experimental + attributes: + - ref: dotnet.gc.heap.generation + requirement_level: required + + - id: metric.dotnet.gc.heap.total_allocated + type: metric + metric_name: dotnet.gc.heap.total_allocated + brief: > + 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. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling [`GC.GetTotalAllocatedBytes()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalallocatedbytes). + instrument: counter + unit: "By" + stability: experimental + + - id: metric.dotnet.gc.last_collection.memory.committed_size + type: metric + metric_name: dotnet.gc.last_collection.memory.committed_size + brief: > + The amount of committed virtual memory in use by the .NET GC, as + observed during the latest garbage collection. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`GC.GetGCMemoryInfo().TotalCommittedBytes`](https://learn.microsoft.com/dotnet/api/system.gcmemoryinfo.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. + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.dotnet.gc.last_collection.heap.size + type: metric + metric_name: dotnet.gc.last_collection.heap.size + brief: > + The managed GC heap size (including fragmentation), as observed during the + latest garbage collection. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.sizeafterbytes). + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: dotnet.gc.heap.generation + requirement_level: required + + - id: metric.dotnet.gc.last_collection.heap.fragmentation.size + type: metric + metric_name: dotnet.gc.last_collection.heap.fragmentation.size + brief: > + The heap fragmentation, as observed during the latest garbage collection. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.fragmentationafterbytes). + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: dotnet.gc.heap.generation + requirement_level: required + + - id: metric.dotnet.gc.pause.time + type: metric + metric_name: dotnet.gc.pause.time + brief: "The total amount of time paused in GC since the process has started." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling [`GC.GetTotalPauseDuration()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalpauseduration). + instrument: counter + unit: "s" + stability: experimental + + - id: metric.dotnet.jit.compiled_il.size + type: metric + metric_name: dotnet.jit.compiled_il.size + brief: "Count of bytes of intermediate language that have been compiled since the process has started." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`JitInfo.GetCompiledILBytes()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledilbytes). + instrument: counter + unit: "By" + stability: experimental + + - id: metric.dotnet.jit.compiled_methods + type: metric + metric_name: dotnet.jit.compiled_methods + brief: > + The number of times the JIT compiler (re)compiled methods since the + process has started. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`JitInfo.GetCompiledMethodCount()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledmethodcount). + instrument: counter + unit: "{method}" + stability: experimental + + - id: metric.dotnet.jit.compilation.time + type: metric + metric_name: dotnet.jit.compilation.time + brief: > + The amount of time the JIT compiler has spent compiling methods since the + process has started. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`JitInfo.GetCompilationTime()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompilationtime). + instrument: counter + unit: "s" + stability: experimental + + - id: metric.dotnet.monitor.lock_contentions + type: metric + metric_name: dotnet.monitor.lock_contentions + brief: > + The number of times there was contention when trying to acquire a monitor + lock since the process has started. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`Monitor.LockContentionCount`](https://learn.microsoft.com/dotnet/api/system.threading.monitor.lockcontentioncount). + instrument: counter + unit: "{contention}" + stability: experimental + + - id: metric.dotnet.thread_pool.thread.count + type: metric + metric_name: dotnet.thread_pool.thread.count + brief: "The number of thread pool threads that currently exist." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling [`ThreadPool.ThreadCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.threadcount). + instrument: updowncounter + unit: "{thread}" + stability: experimental + + - id: metric.dotnet.thread_pool.work_item.count + type: metric + metric_name: dotnet.thread_pool.work_item.count + brief: > + The number of work items that the thread pool has completed since + the process has started. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`ThreadPool.CompletedWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.completedworkitemcount). + instrument: counter + unit: "{work_item}" + stability: experimental + + - id: metric.dotnet.thread_pool.queue.length + type: metric + metric_name: dotnet.thread_pool.queue.length + brief: > + The number of work items that are currently queued to be processed by the + thread pool. + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`ThreadPool.PendingWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.pendingworkitemcount). + instrument: updowncounter + unit: "{work_item}" + stability: experimental + + - id: metric.dotnet.timer.count + type: metric + metric_name: dotnet.timer.count + brief: "The number of timer instances that are currently active." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling [`Timer.ActiveCount`](https://learn.microsoft.com/dotnet/api/system.threading.timer.activecount). + instrument: updowncounter + unit: "{timer}" + stability: experimental + + - id: metric.dotnet.assembly.count + type: metric + metric_name: dotnet.assembly.count + brief: "The number of .NET assemblies that are currently loaded." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as calling + [`AppDomain.CurrentDomain.GetAssemblies().Length`](https://learn.microsoft.com/dotnet/api/system.appdomain.getassemblies). + instrument: updowncounter + unit: "{assembly}" + stability: experimental + + - id: metric.dotnet.exceptions + type: metric + metric_name: dotnet.exceptions + brief: "The number of exceptions that have been thrown in managed code." + note: > + Meter name: `System.Runtime`; Added in: .NET 9.0. + + This metric reports the same values as counting calls to + [`AppDomain.CurrentDomain.FirstChanceException`](https://learn.microsoft.com/dotnet/api/system.appdomain.firstchanceexception). + instrument: counter + unit: "{exception}" + stability: experimental + attributes: + - ref: error.type + note: "" + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + requirement_level: required diff --git a/model/registry/dotnet.yaml b/model/registry/dotnet.yaml new file mode 100644 index 0000000000..2024718f4f --- /dev/null +++ b/model/registry/dotnet.yaml @@ -0,0 +1,33 @@ +groups: + - id: registry.dotnet + type: attribute_group + display_name: .NET Attributes + brief: > + This document defines .NET related attributes. + attributes: + - id: dotnet.gc.heap.generation + stability: experimental + type: + members: + - id: gen0 + value: 'gen0' + brief: "Generation 0" + stability: experimental + - id: gen1 + value: 'gen1' + brief: "Generation 1" + stability: experimental + - id: gen2 + value: 'gen2' + brief: "Generation 2" + stability: experimental + - id: loh + value: 'loh' + brief: "Large Object Heap" + stability: experimental + - id: poh + value: 'poh' + brief: "Pinned Object Heap" + stability: experimental + brief: Name of the garbage collector managed heap generation. + examples: ["gen0", "gen1", "gen2"] diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index f0d8849c7f..a3e7f60b25 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -11,6 +11,7 @@ acronyms: - AWS - CICD - CloudEvents + - CLR - CPU - CosmosDB - DynamoDB