From 696c10a1c15ad52d2e2b060a159521405be4fcd3 Mon Sep 17 00:00:00 2001 From: Andreas Schultz Date: Wed, 20 Mar 2024 12:40:43 +0100 Subject: [PATCH] Add metrics for the BEAM-VM --- .chloggen/add_beam.yaml | 22 + docs/runtime/README.md | 1 + docs/runtime/beam-metrics.md | 748 ++++++++++++++++++++++++++++++ model/metrics/beamvm-metrics.yaml | 501 ++++++++++++++++++++ 4 files changed, 1272 insertions(+) create mode 100644 .chloggen/add_beam.yaml create mode 100644 docs/runtime/beam-metrics.md create mode 100644 model/metrics/beamvm-metrics.yaml diff --git a/.chloggen/add_beam.yaml b/.chloggen/add_beam.yaml new file mode 100644 index 0000000000..f4a5b0d75e --- /dev/null +++ b/.chloggen/add_beam.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: beamvm + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add metrics for the BEAM-VM (use by Erlang, Elixir and others) + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 8b8b2ebb1b..eb34b66edc 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -48,6 +48,7 @@ Also consider the semantic conventions when instrumenting runtime environments. - [JVM](jvm-metrics.md) +- [BEAM](beam-metrics.md) ### Attributes diff --git a/docs/runtime/beam-metrics.md b/docs/runtime/beam-metrics.md new file mode 100644 index 0000000000..5f1f5bd165 --- /dev/null +++ b/docs/runtime/beam-metrics.md @@ -0,0 +1,748 @@ + + +# Semantic Conventions for BEAM Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for BEAM in OpenTelemetry. + + + + + +- [BEAM Atom](#beam-atom) + - [Metric: `beam.atom.count`](#metric-beamatomcount) + - [Metric: `beam.atom.limit`](#metric-beamatomlimit) +- [BEAM CPU](#beam-cpu) + - [Metric: `beam.cpu.async.time`](#metric-beamcpuasynctime) + - [Metric: `beam.cpu.aux.time`](#metric-beamcpuauxtime) + - [Metric: `beam.cpu.dirty_cpu_scheduler.count`](#metric-beamcpudirty_cpu_schedulercount) + - [Metric: `beam.cpu.dirty_cpu_scheduler.online`](#metric-beamcpudirty_cpu_scheduleronline) + - [Metric: `beam.cpu.dirty_cpu_scheduler.run_queue_length`](#metric-beamcpudirty_cpu_schedulerrun_queue_length) + - [Metric: `beam.cpu.dirty_cpu_scheduler.time`](#metric-beamcpudirty_cpu_schedulertime) + - [Metric: `beam.cpu.dirty_io_scheduler.count`](#metric-beamcpudirty_io_schedulercount) + - [Metric: `beam.cpu.dirty_io_scheduler.online`](#metric-beamcpudirty_io_scheduleronline) + - [Metric: `beam.cpu.dirty_io_scheduler.run_queue_length`](#metric-beamcpudirty_io_schedulerrun_queue_length) + - [Metric: `beam.cpu.dirty_io_scheduler.time`](#metric-beamcpudirty_io_schedulertime) + - [Metric: `beam.cpu.logical_processors`](#metric-beamcpulogical_processors) + - [Metric: `beam.cpu.logical_processors_available`](#metric-beamcpulogical_processors_available) + - [Metric: `beam.cpu.logical_processors_online`](#metric-beamcpulogical_processors_online) + - [Metric: `beam.cpu.poll.time`](#metric-beamcpupolltime) + - [Metric: `beam.cpu.scheduler.count`](#metric-beamcpuschedulercount) + - [Metric: `beam.cpu.scheduler.online`](#metric-beamcpuscheduleronline) + - [Metric: `beam.cpu.scheduler.run_queues_length`](#metric-beamcpuschedulerrun_queues_length) + - [Metric: `beam.cpu.scheduler.time`](#metric-beamcpuschedulertime) + - [Metric: `beam.cpu.thread_pool_size`](#metric-beamcputhread_pool_size) +- [BEAM ETS](#beam-ets) + - [Metric: `beam.ets.limit`](#metric-beametslimit) +- [BEAM Memory](#beam-memory) + - [Metric: `beam.memory.allocated`](#metric-beammemoryallocated) + - [Metric: `beam.memory.allocators`](#metric-beammemoryallocators) + - [Metric: `beam.memory.atoms`](#metric-beammemoryatoms) + - [Metric: `beam.memory.garbage_collection.bytes_reclaimed`](#metric-beammemorygarbage_collectionbytes_reclaimed) + - [Metric: `beam.memory.garbage_collection.count`](#metric-beammemorygarbage_collectioncount) + - [Metric: `beam.memory.garbage_collection.words_reclaimed`](#metric-beammemorygarbage_collectionwords_reclaimed) + - [Metric: `beam.memory.processes`](#metric-beammemoryprocesses) + - [Metric: `beam.memory.system`](#metric-beammemorysystem) +- [BEAM Port](#beam-port) + - [Metric: `beam.port.count`](#metric-beamportcount) + - [Metric: `beam.port.io`](#metric-beamportio) + - [Metric: `beam.port.limit`](#metric-beamportlimit) +- [BEAM Process](#beam-process) + - [Metric: `beam.process.context_switches`](#metric-beamprocesscontext_switches) + - [Metric: `beam.process.count`](#metric-beamprocesscount) + - [Metric: `beam.process.cpu.time`](#metric-beamprocesscputime) + - [Metric: `beam.process.limit`](#metric-beamprocesslimit) + - [Metric: `beam.process.reductions`](#metric-beamprocessreductions) +- [BEAM System](#beam-system) + - [Metric: `beam.system.wordsize`](#metric-beamsystemwordsize) + + + +## BEAM Atom + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.atom.*` + +### Metric: `beam.atom.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.atom_count` | UpDownCounter | `{atom}` | The number of atom currently existing at the local node. | + + + + + +### Metric: `beam.atom.limit` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.atom_limit` | UpDownCounter | `{atom}` | The maximum number of simultaneously existing atoms at the local node. | + + + + + +## BEAM CPU + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.cpu.*` + +### Metric: `beam.cpu.async.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.async.time` | Counter | `s` | Async threads are used by various linked-in drivers (mainly the file drivers) do offload non-CPU intensive work. See erl +A for more details. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.aux.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.aux.time` | Counter | `s` | Takes care of any work that is not specifically assigned to a scheduler. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.dirty_cpu_scheduler.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_cpu_scheduler.count` | UpDownCounter | `{scheduler}` | The number of scheduler dirty CPU scheduler threads used by the emulator. | + + + + + +### Metric: `beam.cpu.dirty_cpu_scheduler.online` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_cpu_scheduler.online` | UpDownCounter | `{scheduler}` | The number of dirty CPU scheduler threads online. | + + + + + +### Metric: `beam.cpu.dirty_cpu_scheduler.run_queue_length` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_cpu_scheduler_run_queue_length` | UpDownCounter | `{process}` | Length of the dirty CPU run-queue. | + + + + + +### Metric: `beam.cpu.dirty_cpu_scheduler.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_cpu_scheduler.time` | Counter | `s` | The threads for long running cpu intensive work. See erl +SDcpu for more details. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.dirty_io_scheduler.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_io_scheduler.count` | UpDownCounter | `{scheduler}` | The number of scheduler dirty I/O scheduler threads used by the emulator. | + + + + + +### Metric: `beam.cpu.dirty_io_scheduler.online` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_io_scheduler.online` | UpDownCounter | `{scheduler}` | The number of scheduler dirty I/O scheduler threads online. | + + + + + +### Metric: `beam.cpu.dirty_io_scheduler.run_queue_length` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_io_scheduler_run_queue_length` | UpDownCounter | `{process}` | Length of the dirty I/O run-queue. | + + + + + +### Metric: `beam.cpu.dirty_io_scheduler.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.dirty_io_scheduler.time` | Counter | `s` | The threads for long running I/O work. See erl +SDio for more details. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.logical_processors` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.logical_processors` | UpDownCounter | `{cpu}` | The detected number of logical processors configured in the system. | + + + + + +### Metric: `beam.cpu.logical_processors_available` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.logical_processors_available` | UpDownCounter | `{cpu}` | The detected number of logical processors available to the Erlang runtime system. | + + + + + +### Metric: `beam.cpu.logical_processors_online` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.logical_processors_online` | UpDownCounter | `{cpu}` | The detected number of logical processors online on the system. | + + + + + +### Metric: `beam.cpu.poll.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.poll.time` | Counter | `s` | Does the IO polling for the emulator. See erl +IOt for more details. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.scheduler.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.scheduler.count` | UpDownCounter | `{scheduler}` | The number of scheduler threads used by the emulator. | + + + + + +### Metric: `beam.cpu.scheduler.online` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.scheduler.online` | UpDownCounter | `{scheduler}` | The number of schedulers online. | + + + + + +### Metric: `beam.cpu.scheduler.run_queues_length` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.scheduler.run_queues_length` | UpDownCounter | `{process}` | Length of the normal run-queue. | + + + + + +### Metric: `beam.cpu.scheduler.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.scheduler.time` | Counter | `s` | The main execution threads that do most of the work. See erl +S for more details. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.cpu.logical_number` | int | The logical thread number [0..n-1] | `1` | Recommended | +| `beam.cpu.work` | string | The work peformed for this data point. | `gc` | Recommended | + +`beam.cpu.work` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `aux` | Time spent handling auxiliary jobs. | +| `check_io` | Time spent checking for new I/O events. | +| `emulator` | Time spent executing Erlang processes. | +| `gc` | Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections. | +| `other` | Time spent doing unaccounted things. | +| `port` | Time spent executing ports. | +| `sleep` | Time spent sleeping. | +| `alloc` | Time spent managing memory. Without extra states this time is spread out over all other states. | +| `bif` | Time spent in BIFs. Without extra states this time is part of the emulator state. | +| `busy_wait` | Time spent busy waiting. | +| `ets` | Time spent executing ETS BIFs. Without extra states this time is part of the emulator state. | +| `gc_full` | Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state. | +| `nif` | Time spent in NIFs. Without extra states this time is part of the emulator state. | +| `send` | Time spent sending messages (processes only). Without extra states this time is part of the emulator state. | +| `timers` | Time spent managing timers. Without extra states this time is part of the other state. | + + +### Metric: `beam.cpu.thread_pool_size` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.cpu.thread_pool_size` | UpDownCounter | `{thread}` | The number of async threads in the async thread pool used for asynchronous driver calls. | + + + + + +## BEAM ETS + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.ets.*` + +### Metric: `beam.ets.limit` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.ets.limit` | UpDownCounter | `{table}` | The maximum number of ETS tables allowed. | + + + + + +## BEAM Memory + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.memory.*` + +### Metric: `beam.memory.allocated` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.allocated` | UpDownCounter | `By` | The total amount of memory currently allocated. [1] | + +**[1]:** This is the same as the sum of the memory size for processes and system. + + + + + +### Metric: `beam.memory.allocators` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.allocators` | UpDownCounter | `By` | Allocated (carriers_size) and used (blocks_size) memory for the different allocators in the VM. See erts_alloc(3). | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `alloc` | string | The allocation type. | `sys_alloc` | Recommended | +| `instance_no` | int | The logical instance number [0..n] | `1` | Recommended | +| `kind` | string | The allocation kind. | `mbcs` | Recommended | +| `usage` | string | The usage type. | `blocks` | Recommended | + +`alloc` MUST be one of the following: + +| Value | Description | +|---|---| +| `temp_alloc` | Allocator used for temporary allocations. | +| `eheap_alloc` | Allocator used for Erlang heap data, such as Erlang process heaps. | +| `binary_alloc` | Allocator used for Erlang binary data. | +| `ets_alloc` | Allocator used for ets data. | +| `driver_alloc` | Allocator used for driver data. | +| `literal_alloc` | Allocator used for constant terms in Erlang code. | +| `sl_alloc` | Allocator used for memory blocks that are expected to be short-lived. | +| `ll_alloc` | Allocator used for memory blocks that are expected to be long-lived, for example, Erlang code. | +| `fix_alloc` | A fast allocator used for some frequently used fixed size data types. | +| `std_alloc` | Allocator used for most memory blocks not allocated through any of the other allocators described above. | +| `sys_alloc` | This is normally the default malloc implementation used on the specific OS. | +| `mseg_alloc` | A memory segment allocator. | + +`kind` MUST be one of the following: + +| Value | Description | +|---|---| +| `sbcs` | sbcs | +| `mbcs` | mbcs | +| `mbcs_pool` | mbcs_pool | + +`usage` MUST be one of the following: + +| Value | Description | +|---|---| +| `carriers` | carriers | +| `carriers_size` | carriers_size | +| `blocks` | blocks | +| `blocks_size` | blocks_size | + + +### Metric: `beam.memory.atoms` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.atoms` | UpDownCounter | `By` | The total amount of memory currently allocated for atoms. [1] | + +**[1]:** This memory is part of the memory presented as system memory. + + + + + +### Metric: `beam.memory.garbage_collection.bytes_reclaimed` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.garbage_collection.bytes_reclaimed` | Counter | `By` | Garbage collection: bytes reclaimed. | + + + + + +### Metric: `beam.memory.garbage_collection.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.garbage_collection.count` | Counter | `{garbage_collection}` | Garbage collection: number of GCs. | + + + + + +### Metric: `beam.memory.garbage_collection.words_reclaimed` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.garbage_collection.words_reclaimed` | Counter | `{words}` | Garbage collection: words reclaimed. | + + + + + +### Metric: `beam.memory.processes` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.processes` | UpDownCounter | `By` | The total amount of memory currently allocated for the Erlang processes. | + + + + + +### Metric: `beam.memory.system` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.memory.system` | UpDownCounter | `By` | The total amount of memory currently allocated for the emulator that is not directly related to any Erlang process. [1] | + +**[1]:** Memory presented as processes is not included in this memory. + + + + + +## BEAM Port + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.port.*` + +### Metric: `beam.port.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.port.count` | UpDownCounter | `{port}` | The number of ports currently existing at the local node. | + + + + + +### Metric: `beam.port.io` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.port.io` | Counter | `By` | Total number of bytes read and written to/from ports. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `port.io.direction` | string | The port I/O operation direction. | `read` | Recommended | + +`port.io.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `beam.port.limit` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.port.limit` | UpDownCounter | `{port}` | The maximum number of simultaneously existing ports at the local node. | + + + + + +## BEAM Process + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.process.*` + +### Metric: `beam.process.context_switches` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.process.context_switches` | Counter | `{context_switch}` | Total number of context switches since the system started. | + + + + + +### Metric: `beam.process.count` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.process.count` | UpDownCounter | `{process}` | The number of processes currently existing at the local node. | + + + + + +### Metric: `beam.process.cpu.time` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.process.cpu.time` | Counter | `s` | The sum of the runtime for all threads in the Erlang runtime system. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `beam.process.cpu.state` | string | The CPU state for this data point. | `user` | Recommended | + +`beam.process.cpu.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `user` | user | +| `wall` | wall | + + +### Metric: `beam.process.limit` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.process.limit` | UpDownCounter | `{process}` | The maximum number of simultaneously existing processes at the local node. | + + + + + +### Metric: `beam.process.reductions` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.process.reductions` | Counter | `{reductions}` | Total reductions. | + + + + + +## BEAM System + +**Status**: [Experimental][DocumentStatus] + +**Description:** BEAM metrics captured under the namespace `beam.system.*` + +### Metric: `beam.system.wordsize` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `beam.system.wordsize` | UpDownCounter | `By` | The size of Erlang term words in bytes. | + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/beamvm-metrics.yaml b/model/metrics/beamvm-metrics.yaml new file mode 100644 index 0000000000..896c4f4725 --- /dev/null +++ b/model/metrics/beamvm-metrics.yaml @@ -0,0 +1,501 @@ +groups: + - id: metric.beam.system.wordsize + type: metric + metric_name: beam.system.wordsize + stability: experimental + instrument: updowncounter + unit: By + brief: "The size of Erlang term words in bytes." + + - id: metric.beam.memory.allocators + type: metric + metric_name: beam.memory.allocators + stability: experimental + instrument: updowncounter + unit: By + brief: "Allocated (carriers_size) and used (blocks_size) memory for the different allocators in the VM. See erts_alloc(3)." + attributes: + - id: instance_no + type: int + stability: experimental + brief: "The logical instance number [0..n]" + examples: [1] + - id: kind + type: + allow_custom_values: false + members: + - id: sbcs + value: 'sbcs' + - id: mbcs + value: 'mbcs' + - id: mbcs_pool + value: 'mbcs_pool' + stability: experimental + brief: "The allocation kind." + examples: ["mbcs"] + - id: alloc + type: + allow_custom_values: false + members: + - id: temp_alloc + value: 'temp_alloc' + brief: "Allocator used for temporary allocations." + - id: eheap_alloc + value: 'eheap_alloc' + brief: "Allocator used for Erlang heap data, such as Erlang process heaps." + - id: binary_alloc + value: 'binary_alloc' + brief: "Allocator used for Erlang binary data." + - id: ets_alloc + value: 'ets_alloc' + brief: "Allocator used for ets data." + - id: driver_alloc + value: 'driver_alloc' + brief: "Allocator used for driver data." + - id: literal_alloc + value: 'literal_alloc' + brief: "Allocator used for constant terms in Erlang code." + - id: sl_alloc + value: 'sl_alloc' + brief: "Allocator used for memory blocks that are expected to be short-lived." + - id: ll_alloc + value: 'll_alloc' + brief: "Allocator used for memory blocks that are expected to be long-lived, for example, Erlang code." + - id: fix_alloc + value: 'fix_alloc' + brief: "A fast allocator used for some frequently used fixed size data types." + - id: std_alloc + value: 'std_alloc' + brief: "Allocator used for most memory blocks not allocated through any of the other allocators described above." + - id: sys_alloc + value: 'sys_alloc' + brief: "This is normally the default malloc implementation used on the specific OS." + - id: mseg_alloc + value: 'mseg_alloc' + brief: "A memory segment allocator." + stability: experimental + brief: "The allocation type." + examples: ["sys_alloc"] + - id: usage + type: + allow_custom_values: false + members: + - id: carriers + value: 'carriers' + - id: carriers_size + value: 'carriers_size' + - id: blocks + value: 'blocks' + - id: blocks_size + value: 'blocks_size' + stability: experimental + brief: "The usage type." + examples: ["blocks"] + + - id: metric.beam.memory.garbage_collection.count + type: metric + metric_name: beam.memory.garbage_collection.count + stability: experimental + instrument: counter + unit: "{garbage_collection}" + brief: "Garbage collection: number of GCs." + + - id: metric.beam.memory.garbage_collection.bytes_reclaimed + type: metric + metric_name: beam.memory.garbage_collection.bytes_reclaimed + stability: experimental + instrument: counter + unit: "By" + brief: "Garbage collection: bytes reclaimed." + + - id: metric.beam.memory.garbage_collection.words_reclaimed + type: metric + metric_name: beam.memory.garbage_collection.words_reclaimed + stability: experimental + instrument: counter + unit: "{words}" + brief: "Garbage collection: words reclaimed." + + - id: metric.beam.memory.atoms + type: metric + metric_name: beam.memory.atoms + stability: experimental + instrument: updowncounter + unit: By + brief: "The total amount of memory currently allocated for atoms." + note: > + This memory is part of the memory presented as system memory. + + - id: metric.beam.memory.allocated + type: metric + metric_name: beam.memory.allocated + stability: experimental + instrument: updowncounter + unit: By + brief: "The total amount of memory currently allocated." + note: > + This is the same as the sum of the memory size for processes and system. + + - id: metric.beam.memory.processes + type: metric + metric_name: beam.memory.processes + stability: experimental + instrument: updowncounter + unit: By + brief: "The total amount of memory currently allocated for the Erlang processes." + + - id: metric.beam.memory.system + type: metric + metric_name: beam.memory.system + stability: experimental + instrument: updowncounter + unit: By + brief: "The total amount of memory currently allocated for the emulator that is not directly related to any Erlang process." + note: > + Memory presented as processes is not included in this memory. + + - id: metric.beam.process.reductions + type: metric + metric_name: beam.process.reductions + stability: experimental + instrument: counter + unit: "{reductions}" + brief: Total reductions. + + - id: metric.beam.process.context_switches + type: metric + metric_name: beam.process.context_switches + stability: experimental + instrument: counter + unit: "{context_switch}" + brief: Total number of context switches since the system started. + + - id: metric.beam.process.cpu.time + type: metric + metric_name: beam.process.cpu.time + stability: experimental + brief: "The sum of the runtime for all threads in the Erlang runtime system." + instrument: counter + unit: "s" + attributes: + - id: beam.process.cpu.state + type: + allow_custom_values: false + members: + - id: user + value: 'user' + - id: wall + value: 'wall' + stability: experimental + brief: "The CPU state for this data point." + examples: ["user"] + + - id: metric.beam.process.count + type: metric + metric_name: beam.process.count + stability: experimental + instrument: updowncounter + unit: "{process}" + brief: "The number of processes currently existing at the local node." + + - id: metric.beam.process.limit + type: metric + metric_name: beam.process.limit + stability: experimental + instrument: updowncounter + unit: "{process}" + brief: "The maximum number of simultaneously existing processes at the local node." + + - id: metric.beam.cpu.logical_processors + type: metric + metric_name: beam.cpu.logical_processors + stability: experimental + instrument: updowncounter + unit: "{cpu}" + brief: "The detected number of logical processors configured in the system." + + - id: metric.beam.cpu.logical_processors_available + type: metric + metric_name: beam.logical_processors_available + stability: experimental + instrument: updowncounter + unit: "{cpu}" + brief: "The detected number of logical processors available to the Erlang runtime system." + + - id: metric.beam.cpu.logical_processors_online + type: metric + metric_name: beam.logical_processors_online + stability: experimental + instrument: updowncounter + unit: "{cpu}" + brief: "The detected number of logical processors online on the system." + + - id: metric.beam.cpu.thread_pool_size + type: metric + metric_name: beam.cpu.thread_pool_size + stability: experimental + instrument: updowncounter + unit: "{thread}" + brief: "The number of async threads in the async thread pool used for asynchronous driver calls." + + - id: metric.beam.cpu.scheduler.run_queues_length + type: metric + metric_name: beam.cpu.scheduler.run_queues_length + stability: experimental + instrument: updowncounter + unit: "{process}" + brief: Length of the normal run-queue. + + - id: metric.beam.cpu.scheduler.count + type: metric + metric_name: beam.cpu.scheduler.count + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of scheduler threads used by the emulator." + + - id: metric.beam.cpu.scheduler.online + type: metric + metric_name: beam.cpu.scheduler.online + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of schedulers online." + + - id: metric.beam.cpu.dirty_cpu_scheduler.run_queue_length + type: metric + metric_name: beam.cpu.dirty_cpu_scheduler_run_queue_length + stability: experimental + instrument: updowncounter + unit: "{process}" + brief: Length of the dirty CPU run-queue. + + - id: metric.beam.cpu.dirty_cpu_scheduler.count + type: metric + metric_name: beam.cpu.dirty_cpu_scheduler.count + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of scheduler dirty CPU scheduler threads used by the emulator." + + - id: metric.beam.cpu.dirty_cpu_scheduler.online + type: metric + metric_name: beam.cpu.dirty_cpu_scheduler.online + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of dirty CPU scheduler threads online." + + - id: metric.beam.cpu.dirty_io_scheduler.run_queue_length + type: metric + metric_name: beam.cpu.dirty_io_scheduler_run_queue_length + stability: experimental + instrument: updowncounter + unit: "{process}" + brief: Length of the dirty I/O run-queue. + + - id: metric.beam.cpu.dirty_io_scheduler.count + type: metric + metric_name: beam.cpu.dirty_io_scheduler.count + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of scheduler dirty I/O scheduler threads used by the emulator." + + - id: metric.beam.cpu.dirty_io_scheduler.online + type: metric + metric_name: beam.cpu.dirty_io_scheduler.online + stability: experimental + instrument: updowncounter + unit: "{scheduler}" + brief: "The number of scheduler dirty I/O scheduler threads online." + + - id: metric.beam.port.io + type: metric + metric_name: beam.port.io + stability: experimental + instrument: counter + unit: "By" + brief: Total number of bytes read and written to/from ports. + attributes: + - id: port.io.direction + type: + allow_custom_values: false + members: + - id: read + value: 'read' + - id: write + value: 'write' + stability: experimental + brief: "The port I/O operation direction." + examples: ["read"] + + - id: metric.beam.port.count + type: metric + metric_name: beam.port.count + stability: experimental + instrument: updowncounter + unit: "{port}" + brief: "The number of ports currently existing at the local node." + + - id: metric.beam.port.limit + type: metric + metric_name: beam.port.limit + stability: experimental + instrument: updowncounter + unit: "{port}" + brief: "The maximum number of simultaneously existing ports at the local node." + + - id: metric.beam.atom.count + type: metric + metric_name: beam.atom_count + stability: experimental + instrument: updowncounter + unit: "{atom}" + brief: "The number of atom currently existing at the local node." + + - id: metric.beam.atom.limit + type: metric + metric_name: beam.atom_limit + stability: experimental + instrument: updowncounter + unit: "{atom}" + brief: "The maximum number of simultaneously existing atoms at the local node." + + - id: metric.beam.ets.limit + type: metric + metric_name: beam.ets.limit + stability: experimental + instrument: updowncounter + unit: "{table}" + brief: "The maximum number of ETS tables allowed." + + # Metrics only available if Microstate Accounting has been enabled + - id: attributes.beam.cpu + prefix: beam.cpu + type: attribute_group + brief: "Describes BEAM thread CPU metric attributes" + attributes: + - id: work + type: + allow_custom_values: true + members: + - id: aux + value: 'aux' + brief: "Time spent handling auxiliary jobs." + - id: check_io + value: 'check_io' + brief: "Time spent checking for new I/O events." + - id: emulator + value: 'emulator' + brief: "Time spent executing Erlang processes." + - id: gc + value: 'gc' + brief: "Time spent doing garbage collection. When extra states are enabled this is the time spent doing non-fullsweep garbage collections." + - id: other + value: 'other' + brief: "Time spent doing unaccounted things." + - id: port + value: 'port' + brief: "Time spent executing ports." + - id: sleep + value: 'sleep' + brief: "Time spent sleeping." + - id: alloc + value: 'alloc' + brief: "Time spent managing memory. Without extra states this time is spread out over all other states." + - id: bif + value: 'bif' + brief: "Time spent in BIFs. Without extra states this time is part of the emulator state." + - id: busy_wait + value: 'busy_wait' + brief: "Time spent busy waiting." + - id: ets + value: 'ets' + brief: "Time spent executing ETS BIFs. Without extra states this time is part of the emulator state." + - id: gc_full + value: 'gc_full' + brief: "Time spent doing fullsweep garbage collection. Without extra states this time is part of the gc state." + - id: nif + value: 'nif' + brief: "Time spent in NIFs. Without extra states this time is part of the emulator state." + - id: send + value: 'send' + brief: "Time spent sending messages (processes only). Without extra states this time is part of the emulator state." + - id: timers + value: 'timers' + brief: "Time spent managing timers. Without extra states this time is part of the other state." + brief: "The work peformed for this data point." + stability: experimental + examples: ["gc"] + - id: logical_number + type: int + stability: experimental + brief: "The logical thread number [0..n-1]" + examples: [1] + + - id: metric.beam.cpu.scheduler.time + type: metric + metric_name: beam.cpu.scheduler.time + stability: experimental + brief: "The main execution threads that do most of the work. See erl +S for more details." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number + + - id: metric.beam.cpu.dirty_cpu_scheduler.time + type: metric + metric_name: beam.cpu.dirty_cpu_scheduler.time + stability: experimental + brief: "The threads for long running cpu intensive work. See erl +SDcpu for more details." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number + + - id: metric.beam.cpu.dirty_io_scheduler.time + type: metric + metric_name: beam.cpu.dirty_io_scheduler.time + stability: experimental + brief: "The threads for long running I/O work. See erl +SDio for more details." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number + + - id: metric.beam.cpu.async.time + type: metric + metric_name: beam.cpu.async.time + stability: experimental + brief: "Async threads are used by various linked-in drivers (mainly the file drivers) do offload non-CPU intensive work. See erl +A for more details." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number + + - id: metric.beam.cpu.aux.time + type: metric + metric_name: beam.cpu.aux.time + stability: experimental + brief: "Takes care of any work that is not specifically assigned to a scheduler." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number + + - id: metric.beam.cpu.poll.time + type: metric + metric_name: beam.cpu.poll.time + stability: experimental + brief: "Does the IO polling for the emulator. See erl +IOt for more details." + instrument: counter + unit: "s" + attributes: + - ref: beam.cpu.work + - ref: beam.cpu.logical_number