Semantic Conventions for Runtime Environment Metrics

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.

All JVM metric attributes are required unless otherwise indicated.

NameDescriptionUnitUnit (UCUM)Instrument Type (*)Value TypeAttribute KeyAttribute Values
process.runtime.jvm.memory.usageMeasure of memory usedBytesByUpDownCounterInt64type"heap", "nonheap"
poolName of pool [1]
process.runtime.jvm.memory.initMeasure of initial memory requestedBytesByUpDownCounterInt64type"heap", "nonheap"
poolName of pool [1]
process.runtime.jvm.memory.committedMeasure of memory committedBytesByUpDownCounterInt64type"heap", "nonheap"
poolName of pool [1]
process.runtime.jvm.memory.limitMeasure of max obtainable memoryBytesByUpDownCounterInt64type"heap", "nonheap"
poolName of pool [1]
process.runtime.jvm.threads.countNumber of executing threadsthreads{threads}UpDownCounterInt64
process.runtime.jvm.classes.loadedNumber of classes loaded since JVM startclasses{classes}CounterInt64
process.runtime.jvm.classes.unloadedNumber of classes unloaded since JVM startclasses{classes}CounterInt64
process.runtime.jvm.classes.current_loadedNumber of classes currently loadedclasses{classes}UpDownCounterInt64
process.runtime.jvm.cpu.utilizationRecent cpu utilization for the process [2]11Asynchronous GaugeDouble
process.runtime.jvm.system.cpu.utilizationRecent cpu utilization for the whole system [2]11Asynchronous GaugeDouble
process.runtime.jvm.system.cpu.load_1mAverage CPU load of the whole system for the last minute11Asynchronous GaugeDouble

[1]: Pool names are generally obtained via MemoryPoolMXBean#getName(). Examples include G1 Old Gen, G1 Eden space, G1 Survivor Space, Metaspace, etc. [2]: These utilizations are not defined as being for the specific interval since last measurement (unlike system.cpu.utilization).