From 8364aaada5484c93efe73bbb784c0abbf527b6c0 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 13 Jun 2023 20:05:49 -0700 Subject: [PATCH] Split out truly experimental JVM metrics (#56) --- CHANGELOG.md | 2 + ...cess-runtime-jvm-metrics-experimental.yaml | 67 +++++++++++++++++++ .../metrics/process-runtime-jvm-metrics.yaml | 67 ------------------- .../runtime-environment-metrics.md | 61 +++++++++-------- 4 files changed, 102 insertions(+), 95 deletions(-) create mode 100644 semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index e58cbea0e0..6ed63b7335 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,3 +82,5 @@ release. ([#104](https://github.com/open-telemetry/semantic-conventions/pull/104)) - Add `process.runtime.jvm.cpu.time` metric. ([#55](https://github.com/open-telemetry/semantic-conventions/pull/55)) +- Split out sections for proposed stable JVM metrics and experimental JVM metrics. + ([#56](https://github.com/open-telemetry/semantic-conventions/pull/56)) diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml b/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml new file mode 100644 index 0000000000..f8b134fba5 --- /dev/null +++ b/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml @@ -0,0 +1,67 @@ +groups: + - id: metric.process.runtime.jvm.memory.init + type: metric + metric_name: process.runtime.jvm.memory.init + extends: attributes.process.runtime.jvm.memory + brief: "Measure of initial memory requested." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.system.cpu.utilization + type: metric + metric_name: process.runtime.jvm.system.cpu.utilization + brief: "Recent CPU utilization for the whole system." + note: > + 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()). + instrument: gauge + unit: "1" + + - id: metric.process.runtime.jvm.system.cpu.load_1m + type: metric + metric_name: process.runtime.jvm.system.cpu.load_1m + brief: "Average CPU load of the whole system for the last minute." + note: > + The value range is [0,n], where n is the number of CPU cores - or a negative number of 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()). + instrument: gauge + unit: "1" + + - id: attributes.process.runtime.jvm.buffer + type: attribute_group + brief: "Describes JVM buffer metric attributes." + attributes: + - ref: pool + brief: Name of the buffer pool. + examples: [ "mapped", "direct" ] + note: > + 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()). + + - id: metric.process.runtime.jvm.buffer.usage + type: metric + metric_name: process.runtime.jvm.buffer.usage + extends: attributes.process.runtime.jvm.buffer + brief: "Measure of memory used by buffers." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.buffer.limit + type: metric + metric_name: process.runtime.jvm.buffer.limit + extends: attributes.process.runtime.jvm.buffer + brief: "Measure of total memory capacity of buffers." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.buffer.count + type: metric + metric_name: process.runtime.jvm.buffer.count + extends: attributes.process.runtime.jvm.buffer + brief: "Number of buffers in the pool." + instrument: updowncounter + unit: "{buffer}" diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml index 186c5e83bf..5cf5525192 100644 --- a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml +++ b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @@ -33,14 +33,6 @@ groups: instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.memory.init - type: metric - metric_name: process.runtime.jvm.memory.init - extends: attributes.process.runtime.jvm.memory - brief: "Measure of initial memory requested." - instrument: updowncounter - unit: "By" - - id: metric.process.runtime.jvm.memory.committed type: metric metric_name: process.runtime.jvm.memory.committed @@ -140,62 +132,3 @@ groups: [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). instrument: gauge unit: "1" - - - id: metric.process.runtime.jvm.system.cpu.utilization - type: metric - metric_name: process.runtime.jvm.system.cpu.utilization - brief: "Recent CPU utilization for the whole system." - note: > - 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()). - instrument: gauge - unit: "1" - - - id: metric.process.runtime.jvm.system.cpu.load_1m - type: metric - metric_name: process.runtime.jvm.system.cpu.load_1m - brief: "Average CPU load of the whole system for the last minute." - note: > - The value range is [0,n], where n is the number of CPU cores - or a negative number of 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()). - instrument: gauge - unit: "1" - - - id: attributes.process.runtime.jvm.buffer - type: attribute_group - brief: "Describes JVM buffer metric attributes." - attributes: - - ref: pool - brief: Name of the buffer pool. - examples: [ "mapped", "direct" ] - note: > - 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()). - - - id: metric.process.runtime.jvm.buffer.usage - type: metric - metric_name: process.runtime.jvm.buffer.usage - extends: attributes.process.runtime.jvm.buffer - brief: "Measure of memory used by buffers." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.buffer.limit - type: metric - metric_name: process.runtime.jvm.buffer.limit - extends: attributes.process.runtime.jvm.buffer - brief: "Measure of total memory capacity of buffers." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.buffer.count - type: metric - metric_name: process.runtime.jvm.buffer.count - extends: attributes.process.runtime.jvm.buffer - brief: "Number of buffers in the pool." - instrument: updowncounter - unit: "{buffer}" diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index fddf1b1640..9791f63651 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -21,7 +21,6 @@ semantic conventions when instrumenting runtime environments. - [Attributes](#attributes) - [JVM Metrics](#jvm-metrics) * [Metric: `process.runtime.jvm.memory.usage`](#metric-processruntimejvmmemoryusage) - * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) * [Metric: `process.runtime.jvm.memory.committed`](#metric-processruntimejvmmemorycommitted) * [Metric: `process.runtime.jvm.memory.limit`](#metric-processruntimejvmmemorylimit) * [Metric: `process.runtime.jvm.memory.usage_after_last_gc`](#metric-processruntimejvmmemoryusage_after_last_gc) @@ -32,6 +31,8 @@ semantic conventions when instrumenting runtime environments. * [Metric: `process.runtime.jvm.classes.current_loaded`](#metric-processruntimejvmclassescurrent_loaded) * [Metric: `process.runtime.jvm.cpu.time`](#metric-processruntimejvmcputime) * [Metric: `process.runtime.jvm.cpu.recent_utilization`](#metric-processruntimejvmcpurecent_utilization) +- [JVM Metrics (Experimental)](#jvm-metrics-experimental) + * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) * [Metric: `process.runtime.jvm.system.cpu.utilization`](#metric-processruntimejvmsystemcpuutilization) * [Metric: `process.runtime.jvm.system.cpu.load_1m`](#metric-processruntimejvmsystemcpuload_1m) * [Metric: `process.runtime.jvm.buffer.usage`](#metric-processruntimejvmbufferusage) @@ -103,33 +104,6 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `process.runtime.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 | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | 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()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - ### Metric: `process.runtime.jvm.memory.committed` This metric is [recommended][MetricRecommended]. @@ -331,6 +305,37 @@ Note that the JVM does not provide a definition of what "recent" means. +## JVM Metrics (Experimental) + +**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` + +### Metric: `process.runtime.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 | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `pool` | 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()). + +`type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + ### Metric: `process.runtime.jvm.system.cpu.utilization` This metric is [recommended][MetricRecommended].