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

Name	Instrument Type	Unit (UCUM)	Description	Stability
jvm.memory.used	UpDownCounter	By	Measure of memory used.

Attribute	Type	Description	Examples	Requirement Level	Stability
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] jvm.memory.pool.name: 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.

Value	Description	Stability
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	Stability
jvm.memory.committed	UpDownCounter	By	Measure of memory committed.

Attribute	Type	Description	Examples	Requirement Level	Stability
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] jvm.memory.pool.name: 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.

Value	Description	Stability
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	Stability
jvm.memory.limit	UpDownCounter	By	Measure of max obtainable memory.

Attribute	Type	Description	Examples	Requirement Level	Stability
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] jvm.memory.pool.name: 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.

Value	Description	Stability
heap	Heap memory.
non_heap	Non-heap memory

Metric: jvm.memory.used_after_last_gc

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
jvm.memory.used_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	Stability
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] jvm.memory.pool.name: 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.

Value	Description	Stability
heap	Heap memory.
non_heap	Non-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 ].

Name	Instrument Type	Unit (UCUM)	Description	Stability
jvm.gc.duration	Histogram	s	Duration of JVM garbage collection actions.

Attribute	Type	Description	Examples	Requirement Level	Stability
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] jvm.gc.action: Garbage collector action is generally obtained via GarbageCollectionNotificationInfo#getGcAction().

[2] jvm.gc.name: 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

• 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	Stability
jvm.thread.count	UpDownCounter	{thread}	Number of executing platform threads.

Attribute	Type	Description	Examples	Requirement Level	Stability
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 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.

Value	Description	Stability
blocked	A thread that is blocked waiting for a monitor lock is in this state.
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.
terminated	A thread that has exited 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.
waiting	A thread that is waiting indefinitely for another thread to perform a particular action is in this state.

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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	Stability
jvm.class.count	UpDownCounter	{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 OpenJ9.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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 OpenJ9. Note that the JVM does not provide a definition of what “recent” means.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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.

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
jvm.memory.init	UpDownCounter	By	Measure of initial memory requested.

Attribute	Type	Description	Examples	Requirement Level	Stability
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] jvm.memory.pool.name: 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.

Value	Description	Stability
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 OpenJ9.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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.used

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
jvm.buffer.memory.used	UpDownCounter	By	Measure of memory used by buffers.

Attribute	Type	Description	Examples	Requirement Level	Stability
jvm.buffer.pool.name	string	Name of the buffer pool. [1]	mapped; direct	Recommended

[1] jvm.buffer.pool.name: 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	Stability
jvm.buffer.memory.limit	UpDownCounter	By	Measure of total memory capacity of buffers.

Attribute	Type	Description	Examples	Requirement Level	Stability
jvm.buffer.pool.name	string	Name of the buffer pool. [1]	mapped; direct	Recommended

[1] jvm.buffer.pool.name: 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	Stability
jvm.buffer.count	UpDownCounter	{buffer}	Number of buffers in the pool.

Attribute	Type	Description	Examples	Requirement Level	Stability
jvm.buffer.pool.name	string	Name of the buffer pool. [1]	mapped; direct	Recommended

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