Split out truly experimental JVM metrics (#56)

open-telemetry · Jun 14, 2023 · 8364aaa · 8364aaa
1 parent 8f9fbdf
commit 8364aaa
Show file tree

Hide file tree

Showing 4 changed files with 102 additions and 95 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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 |
 <!-- endsemconv -->
 
-### 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--).
-
-<!-- semconv metric.process.runtime.jvm.memory.init(metric_table) -->
-| Name     | Instrument Type | Unit (UCUM) | Description    |
-| -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. |
-<!-- endsemconv -->
-
-<!-- semconv metric.process.runtime.jvm.memory.init(full) -->
-| 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 |
-<!-- endsemconv -->
-
 ### 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.
 <!-- semconv metric.process.runtime.jvm.cpu.recent_utilization(full) -->
 <!-- endsemconv -->
 
+## 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--).
+
+<!-- semconv metric.process.runtime.jvm.memory.init(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. |
+<!-- endsemconv -->
+
+<!-- semconv metric.process.runtime.jvm.memory.init(full) -->
+| 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 |
+<!-- endsemconv -->
+
 ### Metric: `process.runtime.jvm.system.cpu.utilization`
 
 This metric is [recommended][MetricRecommended].