diff --git a/.chloggen/clr-runtime.yaml b/.chloggen/clr-runtime.yaml new file mode 100644 index 0000000000..d143617c94 --- /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: clr + +# 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 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/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 003b21c5b4..72438212a1 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -41,6 +41,7 @@ Currently, the following namespaces exist: - [Client](client.md) - [Cloud](cloud.md) - [CloudEvents](cloudevents.md) +- [CLR](clr.md) - [Code](code.md) - [Container](container.md) - [CPU](cpu.md) diff --git a/docs/attributes-registry/clr.md b/docs/attributes-registry/clr.md new file mode 100644 index 0000000000..4f153f31a3 --- /dev/null +++ b/docs/attributes-registry/clr.md @@ -0,0 +1,15 @@ + + + + + +# CLR + +## Clr Attributes + +This document defines .NET Common Language Runtime (CLR) related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------- | ------ | ---------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- | +| `clr.gc.generation` | string | Name of the garbage collector heap generation. | `gen0`; `gen1`; `gen2`; `loh`; `poh` | ![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/clr-metrics.md b/docs/runtime/clr-metrics.md new file mode 100644 index 0000000000..1509635a68 --- /dev/null +++ b/docs/runtime/clr-metrics.md @@ -0,0 +1,324 @@ + + +# Semantic Conventions for .NET CLR Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for .NET CLR runtime metrics in OpenTelemetry. + + + + + +- [CLR Garbage Collection](#clr-garbage-collection) + - [Metric: `clr.gc.collections.count`](#metric-clrgccollectionscount) + - [Metric: `clr.gc.objects.size`](#metric-clrgcobjectssize) + - [Metric: `clr.gc.allocations.size`](#metric-clrgcallocationssize) + - [Metric: `clr.gc.committed_memory.size`](#metric-clrgccommitted_memorysize) + - [Metric: `clr.gc.heap.size`](#metric-clrgcheapsize) + - [Metric: `clr.gc.heap.fragmentation.size`](#metric-clrgcheapfragmentationsize) + - [Metric: `clr.gc.duration`](#metric-clrgcduration) +- [Just-In-Time (JIT) Compiler](#just-in-time-jit-compiler) + - [Metric: `clr.jit.il_compiled.size`](#metric-clrjitil_compiledsize) + - [Metric: `clr.jit.methods_compiled.count`](#metric-clrjitmethods_compiledcount) + - [Metric: `clr.jit.compilation_time`](#metric-clrjitcompilation_time) +- [Thread pool](#thread-pool) + - [Metric: `clr.thread_pool.threads.count`](#metric-clrthread_poolthreadscount) + - [Metric: `clr.thread_pool.work_items.count`](#metric-clrthread_poolwork_itemscount) + - [Metric: `clr.thread_pool.queue.length`](#metric-clrthread_poolqueuelength) +- [General](#general) + - [Metric: `clr.monitor.lock_contention.count`](#metric-clrmonitorlock_contentioncount) + - [Metric: `clr.timer.count`](#metric-clrtimercount) + - [Metric: `clr.assemblies.count`](#metric-clrassembliescount) + - [Metric: `clr.exceptions.count`](#metric-clrexceptionscount) + + + +## CLR Garbage Collection + +**Status**: [Experimental][DocumentStatus] + +**Description:** .NET Common Language Runtime (CLR) metrics relating to garbage collection, captured under the namespace `clr.gc.*`. + +### Metric: `clr.gc.collections.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.CollectionCount(int generation)`](https://learn.microsoft.com/en-us/dotnet/api/system.gc.collectioncount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.collections.count` | Counter | `{collection}` | Number of garbage collections that have occurred since the process started. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`clr.gc.generation`](/docs/attributes-registry/clr.md) | string | Name of the garbage collector heap generation. | `gen0`; `gen1`; `gen2`; `loh`; `poh` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `clr.gc.objects.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetTotalMemory(false)`](https://learn.microsoft.com/en-us/dotnet/api/system.gc.gettotalmemory). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.objects.size` | UpDownCounter | `By` | The number of bytes currently allocated on the managed GC heap. Fragmentation and other GC committed memory pools are excluded. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.gc.allocations.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetTotalAllocatedBytes()`](https://learn.microsoft.com/en-us/dotnet/api/system.gc.gettotalallocatedbytes). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.allocations.size` | Counter | `By` | The number of bytes allocated on the managed GC heap since the process started. The returned value does not include any native allocations. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.gc.committed_memory.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetGCMemoryInfo().TotalCommittedBytes`](https://learn.microsoft.com/en-us/dotnet/api/system.gcmemoryinfo.totalcommittedbytes). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.committed_memory.size` | UpDownCounter | `By` | The amount of committed virtual memory for the managed GC heap, as observed during the latest garbage collection. + [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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: `clr.gc.heap.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes`](https://learn.microsoft.com/en-us/dotnet/api/system.gcgenerationinfo.sizeafterbytes). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.heap.size` | UpDownCounter | `By` | The heap size (including fragmentation), as observed during the latest garbage collection. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`clr.gc.generation`](/docs/attributes-registry/clr.md) | string | Name of the garbage collector heap generation. | `gen0`; `gen1`; `gen2`; `loh`; `poh` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `clr.gc.heap.fragmentation.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes`](https://learn.microsoft.com/en-us/dotnet/api/system.gcgenerationinfo.fragmentationafterbytes). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.heap.fragmentation.size` | UpDownCounter | `By` | The heap fragmentation, as observed during the latest garbage collection. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`clr.gc.generation`](/docs/attributes-registry/clr.md) | string | Name of the garbage collector heap generation. | `gen0`; `gen1`; `gen2`; `loh`; `poh` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `clr.gc.duration` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`GC.GetTotalPauseDuration()`](https://learn.microsoft.com/en-us/dotnet/api/system.gc.gettotalpauseduration). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.gc.duration` | Counter | `ns` | The total amount of time paused in GC since the process started. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +## 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 `clr.jit.*`. + +### Metric: `clr.jit.il_compiled.size` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`JitInfo.GetCompiledILBytes()`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.jitinfo.getcompiledilbytes). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.jit.il_compiled.size` | Counter | `By` | Count of bytes of intermediate language that have been compiled since the process start. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.jit.methods_compiled.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`JitInfo.GetCompiledMethodCount()`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.jitinfo.getcompiledmethodcount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.jit.methods_compiled.count` | Counter | `{method}` | The number of times the JIT compiler (re)compiled methods since the process start. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.jit.compilation_time` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`JitInfo.GetCompilationTime()`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.jitinfo.getcompilationtime). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.jit.compilation_time` | Counter | `ns` | The amount of time the JIT compiler has spent compiling methods since the process start. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +## Thread pool + +**Status**: [Experimental][DocumentStatus] + +**Description:** .NET Common Language Runtime (CLR) metrics relating to the thread pool, captured under the namespace `clr.thread_pool.*`. + +### Metric: `clr.thread_pool.threads.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ThreadPool.ThreadCount`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.threadpool.threadcount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.thread_pool.threads.count` | UpDownCounter | `{thread}` | The number of thread pool threads that currently exist. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.thread_pool.work_items.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ThreadPool.CompletedWorkItemCount`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.threadpool.completedworkitemcount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.thread_pool.work_items.count` | Counter | `{work_item}` | The number of work items that the thread pool has processed since the process start. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.thread_pool.queue.length` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ThreadPool.PendingWorkItemCount`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.threadpool.pendingworkitemcount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.thread_pool.queue.length` | UpDownCounter | `{queue}` | The number of work items that are currently queued to be processed by the thread pool. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +## General + +**Status**: [Experimental][DocumentStatus] + +**Description:** Other useful .NET Common Language Runtime (CLR) metrics. + +### Metric: `clr.monitor.lock_contention.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Monitor.LockContentionCount`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.monitor.lockcontentioncount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.monitor.lock_contention.count` | Counter | `{contention}` | The number of times there was contention when trying to acquire a monitor lock since the process start. + | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.timer.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Timer.ActiveCount`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.timer.activecount). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.timer.count` | UpDownCounter | `{timer}` | The number of timer instances that are currently active. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.assemblies.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`AppDomain.CurrentDomain.GetAssemblies().Length`](https://learn.microsoft.com/en-us/dotnet/api/system.appdomain.getassemblies). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.assemblies.count` | UpDownCounter | `{assembly}` | The number of .NET assemblies that are currently loaded. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `clr.exceptions.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`AppDomain.CurrentDomain.FirstChanceException`](https://learn.microsoft.com/en-us/dotnet/api/system.appdomain.firstchanceexception). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `clr.exceptions.count` | Counter | `{exception}` | Count of exceptions that have been thrown in managed code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/metrics/clr-metrics.yaml b/model/metrics/clr-metrics.yaml new file mode 100644 index 0000000000..de76bd605f --- /dev/null +++ b/model/metrics/clr-metrics.yaml @@ -0,0 +1,154 @@ +groups: + - id: metric.clr.gc.collections.count + type: metric + metric_name: clr.gc.collections.count + brief: > + Number of garbage collections that have occurred since the process started. + instrument: counter + unit: "{collection}" + stability: experimental + attributes: + - ref: clr.gc.generation + requirement_level: required + - id: metric.clr.gc.objects.size + type: metric + metric_name: clr.gc.objects.size + brief: > + The number of bytes currently allocated on the managed GC heap. + Fragmentation and other GC committed memory pools are excluded. + instrument: updowncounter + unit: "By" + stability: experimental + - id: metric.clr.gc.allocations.size + type: metric + metric_name: clr.gc.allocations.size + brief: > + The number of bytes allocated on the managed GC heap since the process + started. The returned value does not include any native allocations. + instrument: counter + unit: "By" + stability: experimental + - id: metric.clr.gc.committed_memory.size + type: metric + metric_name: clr.gc.committed_memory.size + brief: > + The amount of committed virtual memory for the managed GC heap, as + observed during the latest garbage collection. + note: > + 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.clr.gc.heap.size + type: metric + metric_name: clr.gc.heap.size + brief: > + The heap size (including fragmentation), as observed during the latest + garbage collection. + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: clr.gc.generation + requirement_level: required + - id: metric.clr.gc.heap.fragmentation.size + type: metric + metric_name: clr.gc.heap.fragmentation.size + brief: > + The heap fragmentation, as observed during the latest garbage collection. + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: clr.gc.generation + requirement_level: required + - id: metric.clr.gc.duration + type: metric + metric_name: clr.gc.duration + brief: "The total amount of time paused in GC since the process started." + instrument: counter + unit: "ns" + stability: experimental + - id: metric.clr.jit.il_compiled.size + type: metric + metric_name: clr.jit.il_compiled.size + brief: "Count of bytes of intermediate language that have been compiled since the process start." + instrument: counter + unit: "By" + stability: experimental + - id: metric.clr.jit.methods_compiled.count + type: metric + metric_name: clr.jit.methods_compiled.count + brief: > + The number of times the JIT compiler (re)compiled methods since the + process start. + instrument: counter + unit: "{method}" + stability: experimental + - id: metric.clr.jit.compilation_time + type: metric + metric_name: clr.jit.compilation_time + brief: > + The amount of time the JIT compiler has spent compiling methods since the + process start. + instrument: counter + unit: "ns" + stability: experimental + - id: metric.clr.monitor.lock_contention.count + type: metric + metric_name: clr.monitor.lock_contention.count + brief: > + The number of times there was contention when trying to acquire a monitor + lock since the process start. + instrument: counter + unit: "{contention}" + stability: experimental + - id: metric.clr.thread_pool.threads.count + type: metric + metric_name: clr.thread_pool.threads.count + brief: "The number of thread pool threads that currently exist." + instrument: updowncounter + unit: "{thread}" + stability: experimental + - id: metric.clr.thread_pool.work_items.count + type: metric + metric_name: clr.thread_pool.work_items.count + brief: > + The number of work items that the thread pool has processed since + the process start. + instrument: counter + unit: "{work_item}" + stability: experimental + - id: metric.clr.thread_pool.queue.length + type: metric + metric_name: clr.thread_pool.queue.length + brief: > + The number of work items that are currently queued to be processed by the + thread pool. + instrument: updowncounter + unit: "{queue}" + stability: experimental + - id: metric.clr.timer.count + type: metric + metric_name: clr.timer.count + brief: "The number of timer instances that are currently active." + instrument: updowncounter + unit: "{timer}" + stability: experimental + - id: metric.clr.assemblies.count + type: metric + metric_name: clr.assemblies.count + brief: "The number of .NET assemblies that are currently loaded." + instrument: updowncounter + unit: "{assembly}" + stability: experimental + - id: metric.clr.exceptions.count + type: metric + metric_name: clr.exceptions.count + brief: "Count of exceptions that have been thrown in managed code." + instrument: counter + unit: "{exception}" + stability: experimental \ No newline at end of file diff --git a/model/registry/clr.yaml b/model/registry/clr.yaml new file mode 100644 index 0000000000..aa999a10ed --- /dev/null +++ b/model/registry/clr.yaml @@ -0,0 +1,12 @@ +groups: + - id: registry.clr + type: attribute_group + prefix: clr + brief: > + This document defines .NET Common Language Runtime (CLR) related attributes. + attributes: + - id: gc.generation + stability: experimental + type: string + brief: Name of the garbage collector heap generation. + examples: ["gen0", "gen1", "gen2", "loh", "poh"] \ No newline at end of file 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