From 97940e7f8606d16708df08d8065f3af0aa41d4a9 Mon Sep 17 00:00:00 2001 From: Robert Toyonaga Date: Mon, 8 May 2023 15:26:28 -0400 Subject: [PATCH] Add JVM runtime metric source API notes (#3463) Fixes #3418 ## Changes Add notes on where the JVM runtime metrics come from. --------- Co-authored-by: Mateusz Rzeszutek Co-authored-by: Trask Stalnaker Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- CHANGELOG.md | 2 ++ .../runtime-environment-metrics.md | 20 +++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fe750ed25d..b02c7e9ab86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,8 @@ release. - Specify second unit (`s`) and advice bucket boundaries of `[]` for `process.runtime.jvm.gc.duration`. ([#3458](https://github.com/open-telemetry/opentelemetry-specification/pull/3458)) +- Add links to the JMX APIs that are the JVM runtime metric sources. + ([#3463](https://github.com/open-telemetry/opentelemetry-specification/pull/3463)) ### Logs diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index 85058b9a062..160bf582fd1 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -78,6 +78,7 @@ consider, for example pthreads vs green thread implementations. ### Metric: `process.runtime.jvm.memory.usage` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -104,6 +105,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.memory.init` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -130,6 +132,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.memory.committed` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -156,6 +159,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.memory.limit` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -182,6 +186,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.memory.usage_after_last_gc` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -208,6 +213,8 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.gc.duration` This metric is [recommended](../metric-requirement-level.md#recommended). +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`](../../metrics/api.md#instrument-advice) @@ -233,6 +240,8 @@ of `[]` (single bucket histogram capturing count, sum, min, max). ### Metric: `process.runtime.jvm.threads.count` This metric is [recommended](../metric-requirement-level.md#recommended). +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--). | Name | Instrument Type | Unit (UCUM) | Description | @@ -249,6 +258,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.classes.loaded` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -262,6 +272,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.classes.unloaded` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -275,6 +286,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.classes.current_loaded` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -288,6 +300,8 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.cpu.utilization` This metric is [recommended](../metric-requirement-level.md#recommended). +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/com.ibm.java.api.80.doc/com.ibm.lang.management/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. | Name | Instrument Type | Unit (UCUM) | Description | @@ -301,6 +315,8 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.system.cpu.utilization` This metric is [recommended](../metric-requirement-level.md#recommended). +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/com.ibm.java.api.80.doc/com.ibm.lang.management/com/ibm/lang/management/OperatingSystemMXBean.html#getSystemCpuLoad--) on J9. | Name | Instrument Type | Unit (UCUM) | Description | @@ -314,6 +330,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.system.cpu.load_1m` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -327,6 +344,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.buffer.usage` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -345,6 +363,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.buffer.limit` This metric is [recommended](../metric-requirement-level.md#recommended). +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 | @@ -363,6 +382,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). ### Metric: `process.runtime.jvm.buffer.count` This metric is [recommended](../metric-requirement-level.md#recommended). +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 |