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)DescriptionStability
jvm.memory.usedUpDownCounterByMeasure of memory used.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.memory.pool.namestringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommendedStable
jvm.memory.typestringThe type of memory.heap; non_heapRecommendedStable

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

jvm.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
heapHeap memory.Stable
non_heapNon-heap memoryStable

Metric: jvm.memory.committed

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

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.memory.committedUpDownCounterByMeasure of memory committed.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.memory.pool.namestringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommendedStable
jvm.memory.typestringThe type of memory.heap; non_heapRecommendedStable

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

jvm.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
heapHeap memory.Stable
non_heapNon-heap memoryStable

Metric: jvm.memory.limit

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

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.memory.limitUpDownCounterByMeasure of max obtainable memory.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.memory.pool.namestringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommendedStable
jvm.memory.typestringThe type of memory.heap; non_heapRecommendedStable

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

jvm.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
heapHeap memory.Stable
non_heapNon-heap memoryStable

Metric: jvm.memory.used_after_last_gc

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

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.memory.used_after_last_gcUpDownCounterByMeasure of memory used, as measured after the most recent garbage collection event on this pool.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.memory.pool.namestringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommendedStable
jvm.memory.typestringThe type of memory.heap; non_heapRecommendedStable

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

jvm.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
heapHeap memory.Stable
non_heapNon-heap memoryStable

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)DescriptionStability
jvm.gc.durationHistogramsDuration of JVM garbage collection actions.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.gc.actionstringName of the garbage collector action. [1]end of minor GC; end of major GCRecommendedStable
jvm.gc.namestringName of the garbage collector. [2]G1 Young Generation; G1 Old GenerationRecommendedStable

[1]: Garbage collector action is generally obtained via GarbageCollectionNotificationInfo#getGcAction().

[2]: Garbage collector name is generally obtained via GarbageCollectionNotificationInfo#getGcName().

JVM Threads

Status: Stable

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)DescriptionStability
jvm.thread.countUpDownCounter{thread}Number of executing platform threads.Stable
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.thread.daemonbooleanWhether the thread is daemon or not.RecommendedStable
jvm.thread.statestringState of the thread.runnable; blockedRecommendedStable

jvm.thread.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
blockedA thread that is blocked waiting for a monitor lock is in this state.Stable
newA thread that has not yet started is in this state.Stable
runnableA thread executing in the Java virtual machine is in this state.Stable
terminatedA thread that has exited is in this state.Stable
timed_waitingA thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state.Stable
waitingA thread that is waiting indefinitely for another thread to perform a particular action is in this state.Stable

JVM Classes

Status: Stable

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)DescriptionStability
jvm.class.loadedCounter{class}Number of classes loaded since JVM start.Stable

Metric: jvm.class.unloaded

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

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

Metric: jvm.class.count

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

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

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 OpenJ9.

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.cpu.timeCountersCPU time used by the process as reported by the JVM.Stable

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)DescriptionStability
jvm.cpu.countUpDownCounter{cpu}Number of processors available to the Java virtual machine.Stable

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 OpenJ9. Note that the JVM does not provide a definition of what “recent” means.

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.cpu.recent_utilizationGauge1Recent CPU utilization for the process as reported by the JVM. [1]Stable

[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)DescriptionStability
jvm.memory.initUpDownCounterByMeasure of initial memory requested.Experimental
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.memory.pool.namestringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommendedStable
jvm.memory.typestringThe type of memory.heap; non_heapRecommendedStable

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

jvm.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
heapHeap memory.Stable
non_heapNon-heap memoryStable

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 OpenJ9.

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.system.cpu.utilizationGauge1Recent CPU utilization for the whole system as reported by the JVM. [1]Experimental

[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)DescriptionStability
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]Experimental

[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.used

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

NameInstrument TypeUnit (UCUM)DescriptionStability
jvm.buffer.memory.usedUpDownCounterByMeasure of memory used by buffers.Experimental
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommendedExperimental

[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)DescriptionStability
jvm.buffer.memory.limitUpDownCounterByMeasure of total memory capacity of buffers.Experimental
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommendedExperimental

[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)DescriptionStability
jvm.buffer.countUpDownCounter{buffer}Number of buffers in the pool.Experimental
AttributeTypeDescriptionExamplesRequirement LevelStability
jvm.buffer.pool.namestringName of the buffer pool. [1]mapped; directRecommendedExperimental

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