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