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 a combination of
ThreadMXBean#getAllThreadIds()ThreadMXBean#getThreadInfo()ThreadInfo#getThreadState()ThreadInfo#isDaemon()(requires Java 9+)
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 |
|---|---|---|---|---|
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.state MUST be one of the following:
| Value | Description |
|---|---|
new | A thread that has not yet started is in this state. |
runnable | A thread executing in the Java virtual machine is in this state. |
blocked | A thread that is blocked waiting for a monitor lock is in this state. |
waiting | A thread that is waiting indefinitely for another thread to perform a particular action is in this state. |
timed_waiting | A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state. |
terminated | A thread that has exited is in this state. |
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().