Semantic Conventions for JVM Metrics
Status: Experimental
This document describes semantic conventions for JVM metrics in OpenTelemetry.
JVM Memory
Description: Java Virtual Machine (JVM) metrics captured under the namespace jvm.memory.*
Metric: jvm.memory.usage
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#getUsage()
.
Name | Instrument Type | Unit (UCUM) | Description |
---|---|---|---|
jvm.memory.usage |
UpDownCounter | By |
Measure of memory used. |
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 |
[1]: Pool names are generally obtained via MemoryPoolMXBean#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.
This metric is obtained from MemoryPoolMXBean#getUsage()
.
Name | Instrument Type | Unit (UCUM) | Description |
---|---|---|---|
jvm.memory.committed |
UpDownCounter | By |
Measure of memory committed. |
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 |
[1]: Pool names are generally obtained via MemoryPoolMXBean#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.
This metric is obtained from MemoryPoolMXBean#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.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 |
[1]: Pool names are generally obtained via MemoryPoolMXBean#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.
This metric is obtained from MemoryPoolMXBean#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.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 |
[1]: Pool names are generally obtained via MemoryPoolMXBean#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.
This metric is obtained by subscribing to
GarbageCollectionNotificationInfo
events provided by GarbageCollectorMXBean
. The duration value is obtained from GcInfo
This metric SHOULD be specified with
ExplicitBucketBoundaries
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.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 |
[1]: Garbage collector action is generally obtained via GarbageCollectionNotificationInfo#getGcAction().
[2]: Garbage collector name is generally obtained via GarbageCollectionNotificationInfo#getGcName().
JVM Threads
Description: Java Virtual Machine (JVM) metrics captured under the namespace jvm.thread.*
Metric: jvm.thread.count
This metric is recommended.
This metric is obtained from ThreadMXBean#getDaemonThreadCount()
and
ThreadMXBean#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 |
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.
This metric is obtained from ClassLoadingMXBean#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.
This metric is obtained from ClassLoadingMXBean#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.
This metric is obtained from ClassLoadingMXBean#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.
This metric is obtained from com.sun.management.OperatingSystemMXBean#getProcessCpuTime()
on HotSpot
and com.ibm.lang.management.OperatingSystemMXBean#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.
This metric is obtained from Runtime#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.
This metric is obtained from com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()
on HotSpot
and com.ibm.lang.management.OperatingSystemMXBean#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.
Very experimental
Description: Very experimental Java Virtual Machine (JVM) metrics captured under jvm.
Metric: jvm.memory.init
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#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.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 |
[1]: Pool names are generally obtained via MemoryPoolMXBean#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.
This metric is obtained from com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()
on Java version 8..13, com.sun.management.OperatingSystemMXBean#getCpuLoad()
on Java version 14+,
and com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()
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.
Metric: jvm.system.cpu.load_1m
This metric is Opt-In.
This metric is obtained from OperatingSystemMXBean#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.
Metric: jvm.buffer.memory.usage
This metric is recommended.
This metric is obtained from BufferPoolMXBean#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().
Metric: jvm.buffer.memory.limit
This metric is recommended.
This metric is obtained from BufferPoolMXBean#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().
Metric: jvm.buffer.count
This metric is recommended.
This metric is obtained from BufferPoolMXBean#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().