Semantic Conventions for Runtime Environment Metrics

NOTICE Semantic Conventions are moving to a new location.

No changes to this document are allowed.

Status: Experimental

This document includes semantic conventions for runtime environment level metrics in OpenTelemetry. Also consider the general metric, system metrics and OS Process metrics semantic conventions when instrumenting runtime environments.

Metric Instruments

Runtime environments vary widely in their terminology, implementation, and relative values for a given metric. For example, Go and Python are both garbage collected languages, but comparing heap usage between the Go and CPython runtimes directly is not meaningful. For this reason, this document does not propose any standard top-level runtime metric instruments. See OTEP 108 for additional discussion.

Runtime Environment Specific Metrics - process.runtime.{environment}.

Metrics specific to a certain runtime environment should be prefixed with process.runtime.{environment}. and follow the semantic conventions outlined in general metric semantic conventions. Authors of runtime instrumentations are responsible for the choice of {environment} to avoid ambiguity when interpreting a metric’s name or values.

For example, some programming languages have multiple runtime environments that vary significantly in their implementation, like Python which has many implementations. For such languages, consider using specific {environment} prefixes to avoid ambiguity, like process.runtime.cpython. and process.runtime.pypy..

There are other dimensions even within a given runtime environment to consider, for example pthreads vs green thread implementations.

Attributes

process.runtime resource attributes SHOULD be included on runtime metric events as appropriate.

JVM Metrics

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

Metric: process.runtime.jvm.memory.usage

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

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.memory.usageUpDownCounterByMeasure of memory used.
AttributeTypeDescriptionExamplesRequirement Level
typestringThe type of memory.heap; non_heapRecommended
poolstringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended

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

type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: process.runtime.jvm.memory.init

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

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.memory.initUpDownCounterByMeasure of initial memory requested.
AttributeTypeDescriptionExamplesRequirement Level
typestringThe type of memory.heap; non_heapRecommended
poolstringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended

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

type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: process.runtime.jvm.memory.committed

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

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.memory.committedUpDownCounterByMeasure of memory committed.
AttributeTypeDescriptionExamplesRequirement Level
typestringThe type of memory.heap; non_heapRecommended
poolstringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended

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

type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: process.runtime.jvm.memory.limit

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

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.memory.limitUpDownCounterByMeasure of max obtainable memory.
AttributeTypeDescriptionExamplesRequirement Level
typestringThe type of memory.heap; non_heapRecommended
poolstringName of the memory pool. [1]G1 Old Gen; G1 Eden space; G1 Survivor SpaceRecommended

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

type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: process.runtime.jvm.memory.usage_after_last_gc

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

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

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

type MUST be one of the following:

ValueDescription
heapHeap memory.
non_heapNon-heap memory

Metric: process.runtime.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).

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

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

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

Metric: process.runtime.jvm.threads.count

This metric is recommended. This metric is obtained from ThreadMXBean#getDaemonThreadCount() and ThreadMXBean#getThreadCount().

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.threads.countUpDownCounter{thread}Number of executing threads.
AttributeTypeDescriptionExamplesRequirement Level
daemonbooleanWhether the thread is daemon or not.Recommended

Metric: process.runtime.jvm.classes.loaded

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

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

Metric: process.runtime.jvm.classes.unloaded

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

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

Metric: process.runtime.jvm.classes.current_loaded

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

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

Metric: process.runtime.jvm.cpu.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.

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.cpu.utilizationGauge1Recent CPU utilization for the process.

Metric: process.runtime.jvm.system.cpu.utilization

This metric is recommended. 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
process.runtime.jvm.system.cpu.utilizationGauge1Recent CPU utilization for the whole system.

Metric: process.runtime.jvm.system.cpu.load_1m

This metric is recommended. This metric is obtained from OperatingSystemMXBean#getSystemLoadAverage().

NameInstrument TypeUnit (UCUM)Description
process.runtime.jvm.system.cpu.load_1mGauge1Average CPU load of the whole system for the last minute.

Metric: process.runtime.jvm.buffer.usage

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

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

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

Metric: process.runtime.jvm.buffer.limit

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

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

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

Metric: process.runtime.jvm.buffer.count

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

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

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