From 9f267b1c625ae922bcfb46abbcc7d7758395dd2f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 12 Dec 2023 11:19:00 -0800 Subject: [PATCH] Mark JVM metrics stable (#569) --- CHANGELOG.md | 2 ++ docs/runtime/jvm-metrics.md | 44 ++++++++++++++++++++-------------- model/metrics/jvm-metrics.yaml | 6 +++++ 3 files changed, 34 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 17134a9a2..724ae3449 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,8 @@ release. ([#163](https://github.com/open-telemetry/semantic-conventions/pull/163)) - Add .NET 8.0 metrics for HTTP client, ASP.NET Core, SignalR server and Kestrel. ([#283](https://github.com/open-telemetry/semantic-conventions/pull/283)) +- JVM metrics marked stable + ([#569](https://github.com/open-telemetry/semantic-conventions/pull/569)) ### Fixes diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 41e2d38ac..eb72b1821 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -4,7 +4,7 @@ linkTitle: Runtime Environment # Semantic Conventions for JVM Metrics -**Status**: [Experimental][DocumentStatus] +**Status**: [Mixed][DocumentStatus] This document describes semantic conventions for JVM metrics in OpenTelemetry. @@ -29,7 +29,7 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. * [Metric: `jvm.cpu.time`](#metric-jvmcputime) * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) -- [Very experimental](#very-experimental) +- [Experimental](#experimental) * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) @@ -41,6 +41,8 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. ## JVM Memory +**Status**: [Stable][DocumentStatus] + **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.memory.*` ### Metric: `jvm.memory.used` @@ -57,8 +59,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of memory. | `heap`; `non_heap` | 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()). @@ -84,8 +86,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of memory. | `heap`; `non_heap` | 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()). @@ -111,8 +113,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of memory. | `heap`; `non_heap` | 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()). @@ -138,8 +140,8 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of memory. | `heap`; `non_heap` | 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()). @@ -153,6 +155,8 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d ## JVM Garbage Collection +**Status**: [Stable][DocumentStatus] + **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.gc.*` ### Metric: `jvm.gc.duration` @@ -174,8 +178,8 @@ of `[ 0.01, 0.1, 1, 10 ]`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.gc.action` | string | Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | Recommended | -| `jvm.gc.name` | string | Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | Recommended | +| `jvm.gc.action` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | Recommended | +| `jvm.gc.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | Recommended | **[1]:** 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()). @@ -207,8 +211,8 @@ Note that this is the number of platform threads (as opposed to virtual threads) | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | -| `jvm.thread.state` | string | State of the thread. | `runnable`; `blocked` | Recommended | +| `jvm.thread.daemon` | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Whether the thread is daemon or not. | | Recommended | +| `jvm.thread.state` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
State of the thread. | `runnable`; `blocked` | Recommended | `jvm.thread.state` MUST be one of the following: @@ -270,6 +274,8 @@ This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https: ## JVM CPU +**Status**: [Stable][DocumentStatus] + **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.cpu.*` ### Metric: `jvm.cpu.time` @@ -321,9 +327,11 @@ Note that the JVM does not provide a definition of what "recent" means. -## Very experimental +## Experimental -**Description:** Very experimental Java Virtual Machine (JVM) metrics captured under `jvm.` +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.` ### Metric: `jvm.memory.init` @@ -339,8 +347,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of memory. | `heap`; `non_heap` | 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()). diff --git a/model/metrics/jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml index ba1f56045..4db5ecd93 100644 --- a/model/metrics/jvm-metrics.yaml +++ b/model/metrics/jvm-metrics.yaml @@ -5,6 +5,7 @@ groups: prefix: jvm.memory attributes: - id: type + stability: stable type: allow_custom_values: false members: @@ -18,6 +19,7 @@ groups: brief: The type of memory. examples: ["heap", "non_heap"] - id: pool.name + stability: stable type: string requirement_level: recommended brief: Name of the memory pool. @@ -67,6 +69,7 @@ groups: prefix: jvm.gc attributes: - id: name + stability: stable type: string requirement_level: recommended brief: Name of the garbage collector. @@ -75,6 +78,7 @@ groups: 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()). - id: action + stability: stable type: string requirement_level: recommended brief: Name of the garbage collector action. @@ -91,10 +95,12 @@ groups: unit: "{thread}" attributes: - id: jvm.thread.daemon + stability: stable type: boolean requirement_level: recommended brief: "Whether the thread is daemon or not." - id: jvm.thread.state + stability: stable requirement_level: recommended type: allow_custom_values: false