# Semantic conventions for V8 JS engine runtime metrics **Status**: [Development][DocumentStatus] This document describes semantic conventions for V8 JS Engine Runtime metrics in OpenTelemetry. This engine is used in some javascript runtime such as Node.js and Deno. - [Metric: `v8js.gc.duration`](#metric-v8jsgcduration) - [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit) - [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused) - [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size) - [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size) **Description:** In-development V8 JS Engine Runtime metrics captured under `v8js`. ## Metric: `v8js.gc.duration` This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.42.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.1, 1, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `v8js.gc.duration` | Histogram | `s` | Garbage collection duration. [1] |  | **[1]:** The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`v8js.gc.type`](/docs/attributes-registry/v8js.md) | string | The type of garbage collection. | `major`; `minor`; `incremental` | `Required` |  | --- `v8js.gc.type` 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 | Stability | |---|---|---| | `incremental` | Incremental (Incremental Marking). |  | | `major` | Major (Mark Sweep Compact). |  | | `minor` | Minor (Scavenge). |  | | `weakcb` | Weak Callbacks (Process Weak Callbacks). |  | ## Metric: `v8js.memory.heap.limit` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `v8js.memory.heap.limit` | UpDownCounter | `By` | Total heap memory size pre-allocated. [1] |  | **[1]:** The value can be retrieved from value `space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  | **[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) --- `v8js.heap.space.name` 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 | Stability | |---|---|---| | `code_space` | Code memory space. |  | | `large_object_space` | Large object memory space. |  | | `map_space` | Map memory space. |  | | `new_space` | New memory space. |  | | `old_space` | Old memory space. |  | ## Metric: `v8js.memory.heap.used` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `v8js.memory.heap.used` | UpDownCounter | `By` | Heap Memory size allocated. [1] |  | **[1]:** The value can be retrieved from value `space_used_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  | **[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) --- `v8js.heap.space.name` 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 | Stability | |---|---|---| | `code_space` | Code memory space. |  | | `large_object_space` | Large object memory space. |  | | `map_space` | Map memory space. |  | | `new_space` | New memory space. |  | | `old_space` | Old memory space. |  | ## Metric: `v8js.heap.space.available_size` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `v8js.heap.space.available_size` | UpDownCounter | `By` | Heap space available size. [1] |  | **[1]:** Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  | **[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) --- `v8js.heap.space.name` 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 | Stability | |---|---|---| | `code_space` | Code memory space. |  | | `large_object_space` | Large object memory space. |  | | `map_space` | Map memory space. |  | | `new_space` | New memory space. |  | | `old_space` | Old memory space. |  | ## Metric: `v8js.heap.space.physical_size` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `v8js.heap.space.physical_size` | UpDownCounter | `By` | Committed size of a heap space. [1] |  | **[1]:** Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  | **[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) --- `v8js.heap.space.name` 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 | Stability | |---|---|---| | `code_space` | Code memory space. |  | | `large_object_space` | Large object memory space. |  | | `map_space` | Map memory space. |  | | `new_space` | New memory space. |  | | `old_space` | Old memory space. |  | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.42.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended