Skip to content

Latest commit

 

History

History
404 lines (300 loc) · 21.9 KB

runtime-environment-metrics.md

File metadata and controls

404 lines (300 loc) · 21.9 KB

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