Skip to content

Latest commit

 

History

History
106 lines (82 loc) · 11.5 KB

runtime-environment-metrics.md

File metadata and controls

106 lines (82 loc) · 11.5 KB
Raw

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.

Name Description Unit Unit (UCUM) Instrument Type (*) Value Type Attribute Key Attribute Values
process.runtime.jvm.memory.usage Measure of memory used Bytes By UpDownCounter Int64 type "heap", "non_heap"
pool Name of pool [1]
process.runtime.jvm.memory.init Measure of initial memory requested Bytes By UpDownCounter Int64 type "heap", "non_heap"
pool Name of pool [1]
process.runtime.jvm.memory.committed Measure of memory committed Bytes By UpDownCounter Int64 type "heap", "non_heap"
pool Name of pool [1]
process.runtime.jvm.memory.limit Measure of max obtainable memory Bytes By UpDownCounter Int64 type "heap", "non_heap"
pool Name of pool [1]
process.runtime.jvm.memory.usage_after_last_gc Measure of memory used, as measured after the most recent garbage collection event on this pool Bytes By UpDownCounter Int64 type "heap", "non_heap"
pool Name of pool [1]
process.runtime.jvm.threads.count Number of executing threads threads {thread} UpDownCounter Int64 daemon true, false
process.runtime.jvm.classes.loaded Number of classes loaded since JVM start classes {class} Counter Int64
process.runtime.jvm.classes.unloaded Number of classes unloaded since JVM start classes {class} Counter Int64
process.runtime.jvm.classes.current_loaded Number of classes currently loaded classes {class} UpDownCounter Int64
process.runtime.jvm.cpu.utilization Recent CPU utilization for the process [2] 1 1 Asynchronous Gauge Double
process.runtime.jvm.system.cpu.utilization Recent CPU utilization for the whole system [2] 1 1 Asynchronous Gauge Double
process.runtime.jvm.system.cpu.load_1m Average CPU load of the whole system for the last minute 1 1 Asynchronous Gauge Double
process.runtime.jvm.buffer.usage Measure of memory used by buffers Bytes By UpDownCounter Int64 pool Name of pool[3]
process.runtime.jvm.buffer.limit Measure of total memory capacity of buffers Bytes By UpDownCounter Int64 pool Name of pool[3]
process.runtime.jvm.buffer.count Number of buffers in the pool buffers {buffer} UpDownCounter Int64 pool Name of pool[3]
process.runtime.jvm.gc.duration Duration of JVM garbage collection actions Milliseconds ms Histogram Int64 gc Name of gc[4]
action The gc action[4]

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

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

[4]: Garbage collector name and action are generally obtained via GarbageCollectionNotificationInfo#getGcName() and GarbageCollectionNotificationInfo#getGcAction() respectively. The following is an incomplete list of names and actions for several popular garbage collectors:

  • G1 Garbage Collector
    • Names: G1 Young Generation, G1 Old Generation
    • Actions: end of minor GC, end of major GC
  • Shenandoah Garbage Collector
    • Names: Shenandoah Cycles, Shenandoah Pauses
    • Actions: end of GC cycle, end of GC pause
  • Z Garbage Collector
    • Names: ZGC Cycles, ZGC Pauses
    • Actions: end of GC cycle, end of GC pause