diff --git a/docs/jvm/jvm-metrics.md b/docs/jvm/jvm-metrics.md new file mode 100644 index 000000000..6272e494f --- /dev/null +++ b/docs/jvm/jvm-metrics.md @@ -0,0 +1,430 @@ + + +# Semantic Conventions for JVM Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for JVM metrics in OpenTelemetry. + + + + + +- [JVM Memory](#jvm-memory) + * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) + * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) + * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) + * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) +- [JVM Garbage Collection](#jvm-garbage-collection) + * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) +- [JVM Threads](#jvm-threads) + * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) +- [JVM Classes](#jvm-classes) + * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) + * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) + * [Metric: `jvm.class.count`](#metric-jvmclasscount) +- [JVM CPU](#jvm-cpu) + * [Metric: `jvm.cpu.time`](#metric-jvmcputime) + * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) + * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) +- [Very experimental](#very-experimental) + * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) + * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) + * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) + * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) + * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) + + + +## JVM Memory + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.memory.*` + +### Metric: `jvm.memory.usage` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.committed` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.usage_after_last_gc` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +## JVM Garbage Collection + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.gc.*` + +### Metric: `jvm.gc.duration` + +This metric is [recommended][MetricRecommended]. +This metric is obtained by subscribing to +[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) +of `[]` (single bucket histogram capturing count, sum, min, max). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | +| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | + +**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). + +**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + + +## JVM Threads + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.thread.*` + +### Metric: `jvm.thread.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and +[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). +Note that this is the number of platform threads (as opposed to virtual threads). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | + + +## JVM Classes + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.class.*` + +### Metric: `jvm.class.loaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | + + + + + +### Metric: `jvm.class.unloaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | + + + + + +### Metric: `jvm.class.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | + + + + + +## JVM CPU + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.cpu.*` + +### Metric: `jvm.cpu.time` + +This metric is [recommended][MetricRecommended]. + +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | + + + + + +### Metric: `jvm.cpu.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). +Note that this is always an integer value (i.e. fractional or millicores are not represented). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | + + + + + +### Metric: `jvm.cpu.recent_utilization` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. +Note that the JVM does not provide a definition of what "recent" means. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). + + + + + +## Very experimental + +**Description:** Very experimental Java Virtual Machine (JVM) metrics captured under `jvm.` + +### Metric: `jvm.memory.init` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.system.cpu.utilization` + +This metric is [Opt-In][MetricOptIn]. +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, +and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). + + + + + +### Metric: `jvm.system.cpu.load_1m` + +This metric is [Opt-In][MetricOptIn]. +This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | + +**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). + + + + + +### Metric: `jvm.buffer.memory.usage` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index c8b8ce25a..c77222063 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -19,26 +19,6 @@ semantic conventions when instrumenting runtime environments. - [Metric Instruments](#metric-instruments) * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) - [Attributes](#attributes) -- [JVM Metrics](#jvm-metrics) - * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) - * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) - * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) - * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) - * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) - * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) - * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) - * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) - * [Metric: `jvm.class.count`](#metric-jvmclasscount) - * [Metric: `jvm.cpu.time`](#metric-jvmcputime) - * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) - * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) -- [JVM Metrics (Experimental)](#jvm-metrics-experimental) - * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) - * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) - * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) - * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) - * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) - * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -74,376 +54,4 @@ consider, for example pthreads vs green thread implementations. [`process.runtime`](/docs/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. -## JVM Metrics - -**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.` - -### Metric: `jvm.memory.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.committed` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.usage_after_last_gc` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.gc.duration` - -This metric is [recommended][MetricRecommended]. -This metric is obtained by subscribing to -[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) -of `[]` (single bucket histogram capturing count, sum, min, max). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | - -**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). - -**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - -### Metric: `jvm.thread.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and -[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). -Note that this is the number of platform threads (as opposed to virtual threads). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | - - -### Metric: `jvm.class.loaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - - - - - -### Metric: `jvm.class.unloaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - - - - - -### Metric: `jvm.class.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | - - - - - -### Metric: `jvm.cpu.time` - -This metric is [recommended][MetricRecommended]. - -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | - - - - - -### Metric: `jvm.cpu.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). -Note that this is always an integer value (i.e. fractional or millicores are not represented). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | - - - - - -### Metric: `jvm.cpu.recent_utilization` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. -Note that the JVM does not provide a definition of what "recent" means. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). - - - - - -## JVM Metrics (Experimental) - -**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.` - -### Metric: `jvm.memory.init` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.system.cpu.utilization` - -This metric is [Opt-In][MetricOptIn]. -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, -and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). - - - - - -### Metric: `jvm.system.cpu.load_1m` - -This metric is [Opt-In][MetricOptIn]. -This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | - -**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). - - - - - -### Metric: `jvm.buffer.memory.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `jvm.buffer.memory.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `jvm.buffer.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md -[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in -[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml similarity index 100% rename from model/metrics/process-runtime-jvm-metrics-experimental.yaml rename to model/metrics/jvm-metrics-experimental.yaml diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml similarity index 100% rename from model/metrics/process-runtime-jvm-metrics.yaml rename to model/metrics/jvm-metrics.yaml