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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.memory.usage | UpDownCounter | By | Measure of memory used. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
type | string | The type of memory. | heap; non_heap | Recommended |
pool | string | Name of the memory pool. [1] | G1 Old Gen; G1 Eden space; G1 Survivor Space | Recommended |
[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().
type MUST be one of the following:
| Value | Description |
|---|---|
heap | Heap memory. |
non_heap | Non-heap memory |
Metric: process.runtime.jvm.memory.init
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#getUsage().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.memory.init | UpDownCounter | By | Measure of initial memory requested. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
type | string | The type of memory. | heap; non_heap | Recommended |
pool | string | Name of the memory pool. [1] | G1 Old Gen; G1 Eden space; G1 Survivor Space | Recommended |
[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().
type MUST be one of the following:
| Value | Description |
|---|---|
heap | Heap memory. |
non_heap | Non-heap memory |
Metric: process.runtime.jvm.memory.committed
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#getUsage().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.memory.committed | UpDownCounter | By | Measure of memory committed. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
type | string | The type of memory. | heap; non_heap | Recommended |
pool | string | Name of the memory pool. [1] | G1 Old Gen; G1 Eden space; G1 Survivor Space | Recommended |
[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().
type MUST be one of the following:
| Value | Description |
|---|---|
heap | Heap memory. |
non_heap | Non-heap memory |
Metric: process.runtime.jvm.memory.limit
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#getUsage().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.memory.limit | UpDownCounter | By | Measure of max obtainable memory. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
type | string | The type of memory. | heap; non_heap | Recommended |
pool | string | Name of the memory pool. [1] | G1 Old Gen; G1 Eden space; G1 Survivor Space | Recommended |
[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().
type MUST be one of the following:
| Value | Description |
|---|---|
heap | Heap memory. |
non_heap | Non-heap memory |
Metric: process.runtime.jvm.memory.usage_after_last_gc
This metric is recommended.
This metric is obtained from MemoryPoolMXBean#getCollectionUsage().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.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 |
|---|---|---|---|---|
type | string | The type of memory. | heap; non_heap | Recommended |
pool | string | Name of the memory pool. [1] | G1 Old Gen; G1 Eden space; G1 Survivor Space | Recommended |
[1]: Pool names are generally obtained via MemoryPoolMXBean#getName().
type MUST be one of the following:
| Value | Description |
|---|---|
heap | Heap memory. |
non_heap | Non-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).
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.gc.duration | Histogram | s | Duration of JVM garbage collection actions. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
gc | string | Name of the garbage collector. [1] | G1 Young Generation; G1 Old Generation | Recommended |
action | string | Name of the garbage collector action. [2] | end of minor GC; end of major GC | Recommended |
[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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.threads.count | UpDownCounter | {thread} | Number of executing threads. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
daemon | boolean | Whether the thread is daemon or not. | Recommended |
Metric: process.runtime.jvm.classes.loaded
This metric is recommended.
This metric is obtained from ClassLoadingMXBean#getTotalLoadedClassCount().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.classes.loaded | Counter | {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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.classes.unloaded | Counter | {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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.classes.current_loaded | UpDownCounter | {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.
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.cpu.utilization | Gauge | 1 | Recent 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.
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.system.cpu.utilization | Gauge | 1 | Recent 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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.system.cpu.load_1m | Gauge | 1 | Average 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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.buffer.usage | UpDownCounter | By | Measure of memory used by buffers. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
pool | string | Name of the buffer pool. [1] | mapped; direct | Recommended |
[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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.buffer.limit | UpDownCounter | By | Measure of total memory capacity of buffers. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
pool | string | Name of the buffer pool. [1] | mapped; direct | Recommended |
[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().
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
process.runtime.jvm.buffer.count | UpDownCounter | {buffer} | Number of buffers in the pool. |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
pool | string | Name of the buffer pool. [1] | mapped; direct | Recommended |
[1]: Pool names are generally obtained via BufferPoolMXBean#getName().