Semantic Conventions for JVM Metrics

Status: Mixed

This document describes semantic conventions for JVM metrics in OpenTelemetry.

JVM Memory

Status: Stable

Description: Java Virtual Machine (JVM) metrics captured under the namespace jvm.memory.*

Metric: jvm.memory.used

This metric is recommended. This metric is obtained from MemoryPoolMXBean#getUsage().

NameInstrument TypeUnit (UCUM)Description
jvm.memory.usedUpDownCounterByMeasure of memory used.
AttributeTypeDescriptionExamplesRequirement Level
jvm.memory.pool.namestringStable
Name of the memory pool. [1]
G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended
jvm.memory.typestringStable
The type of memory.
heap; non_heapRecommended

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().

jvm.memory.type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: jvm.memory.committed

This metric is recommended. This metric is obtained from MemoryPoolMXBean#getUsage().

NameInstrument TypeUnit (UCUM)Description
jvm.memory.committedUpDownCounterByMeasure of memory committed.
AttributeTypeDescriptionExamplesRequirement Level
jvm.memory.pool.namestringStable
Name of the memory pool. [1]
G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended
jvm.memory.typestringStable
The type of memory.
heap; non_heapRecommended

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().

jvm.memory.type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: jvm.memory.limit

This metric is recommended. This metric is obtained from MemoryPoolMXBean#getUsage().

NameInstrument TypeUnit (UCUM)Description
jvm.memory.limitUpDownCounterByMeasure of max obtainable memory.
AttributeTypeDescriptionExamplesRequirement Level
jvm.memory.pool.namestringStable
Name of the memory pool. [1]
G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended
jvm.memory.typestringStable
The type of memory.
heap; non_heapRecommended

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().

jvm.memory.type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: jvm.memory.used_after_last_gc

This metric is recommended. This metric is obtained from MemoryPoolMXBean#getCollectionUsage().

NameInstrument TypeUnit (UCUM)Description
jvm.memory.used_after_last_gcUpDownCounterByMeasure of memory used, as measured after the most recent garbage collection event on this pool.
AttributeTypeDescriptionExamplesRequirement Level
jvm.memory.pool.namestringStable
Name of the memory pool. [1]
G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended
jvm.memory.typestringStable
The type of memory.
heap; non_heapRecommended

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().

jvm.memory.type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

JVM Garbage Collection

Status: Stable

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 [ 0.01, 0.1, 1, 10 ].

NameInstrument TypeUnit (UCUM)Description
jvm.gc.durationHistogramsDuration of JVM garbage collection actions.
AttributeTypeDescriptionExamplesRequirement Level
jvm.gc.actionstringStable
Name of the garbage collector action. [1]
end of minor GC; end of major GCRecommended
jvm.gc.namestringStable
Name of the garbage collector. [2]
G1 Young Generation; G1 Old GenerationRecommended

[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

Note that this is the number of platform threads (as opposed to virtual threads).

NameInstrument TypeUnit (UCUM)Description
jvm.thread.countUpDownCounter{thread}Number of executing platform threads.
AttributeTypeDescriptionExamplesRequirement Level
jvm.thread.daemonbooleanStable
Whether the thread is daemon or not.
Recommended
jvm.thread.statestringStable
State of the thread.
runnable; blockedRecommended

jvm.thread.state MUST be one of the following:

ValueDescription
newA thread that has not yet started is in this state.
runnableA thread executing in the Java virtual machine is in this state.
blockedA thread that is blocked waiting for a monitor lock is in this state.
waitingA thread that is waiting indefinitely for another thread to perform a particular action is in this state.
timed_waitingA thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state.
terminatedA 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().

NameInstrument TypeUnit (UCUM)Description
jvm.class.loadedCounter{class}Number of classes loaded since JVM start.

Metric: jvm.class.unloaded

This metric is recommended. This metric is obtained from ClassLoadingMXBean#getUnloadedClassCount().

NameInstrument TypeUnit (UCUM)Description
jvm.class.unloadedCounter{class}Number of classes unloaded since JVM start.

Metric: jvm.class.count

This metric is recommended. This metric is obtained from ClassLoadingMXBean#getLoadedClassCount().

NameInstrument TypeUnit (UCUM)Description
jvm.class.countUpDownCounter{class}Number of classes currently loaded.

JVM CPU

Status: Stable

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.

NameInstrument TypeUnit (UCUM)Description
jvm.cpu.timeCountersCPU 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).

NameInstrument TypeUnit (UCUM)Description
jvm.cpu.countUpDownCounter{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.

NameInstrument TypeUnit (UCUM)Description
jvm.cpu.recent_utilizationGauge1Recent 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.

Experimental

Status: Experimental

Description: Experimental Java Virtual Machine (JVM) metrics captured under jvm.

Metric: jvm.memory.init

This metric is recommended. This metric is obtained from MemoryPoolMXBean#getUsage().

NameInstrument TypeUnit (UCUM)Description
jvm.memory.initUpDownCounterByMeasure of initial memory requested.
AttributeTypeDescriptionExamplesRequirement Level
jvm.memory.pool.namestringStable
Name of the memory pool. [1]
G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended
jvm.memory.typestringStable
The type of memory.
heap; non_heapRecommended

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().

jvm.memory.type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-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.

NameInstrument TypeUnit (UCUM)Description
jvm.system.cpu.utilizationGauge1Recent 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().

NameInstrument TypeUnit (UCUM)Description
jvm.system.cpu.load_1mGauge{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().

NameInstrument TypeUnit (UCUM)Description
jvm.buffer.memory.usageUpDownCounterByMeasure of memory used by buffers.
AttributeTypeDescriptionExamplesRequirement Level
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommended

[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().

NameInstrument TypeUnit (UCUM)Description
jvm.buffer.memory.limitUpDownCounterByMeasure of total memory capacity of buffers.
AttributeTypeDescriptionExamplesRequirement Level
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommended

[1]: Pool names are generally obtained via BufferPoolMXBean#getName().

Metric: jvm.buffer.count

This metric is recommended. This metric is obtained from BufferPoolMXBean#getCount().

NameInstrument TypeUnit (UCUM)Description
jvm.buffer.countUpDownCounter{buffer}Number of buffers in the pool.
AttributeTypeDescriptionExamplesRequirement Level
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommended

[1]: Pool names are generally obtained via BufferPoolMXBean#getName().