From b1ad9ae785c3d97cf0c80fe320d9b9156f37e927 Mon Sep 17 00:00:00 2001 From: Marylia Gutierrez Date: Mon, 8 Jul 2024 10:25:55 -0400 Subject: [PATCH] Add v8 js engine runtime metrics semantic conventions (#1066) Signed-off-by: maryliag Co-authored-by: Liudmila Molkova Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/v8js-metrics.yaml | 17 ++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/v8js.md | 37 +++ docs/runtime/README.md | 1 + docs/runtime/v8js-metrics.md | 315 ++++++++++++++++++++ model/metrics/v8js-metrics.yaml | 69 +++++ model/registry/v8js.yaml | 54 ++++ 10 files changed, 497 insertions(+) create mode 100644 .chloggen/v8js-metrics.yaml create mode 100644 docs/attributes-registry/v8js.md create mode 100644 docs/runtime/v8js-metrics.md create mode 100644 model/metrics/v8js-metrics.yaml create mode 100644 model/registry/v8js.yaml diff --git a/.chloggen/v8js-metrics.yaml b/.chloggen/v8js-metrics.yaml new file mode 100644 index 0000000000..276a49d500 --- /dev/null +++ b/.chloggen/v8js-metrics.yaml @@ -0,0 +1,17 @@ +# 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: v8js + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for V8 JS Engine runtime metrics. + +# 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: [990] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index f4add087f9..92d1f8f1e3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -72,6 +72,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index e5c7532f76..bb06caa150 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -65,6 +65,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index b4099a42cb..01b2c53764 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -74,6 +74,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 97eab1087b..fe0413bb19 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -86,6 +86,7 @@ Currently, the following namespaces exist: - [URL](url.md) - [User](user.md) - [User Agent](user-agent.md) +- [V8js](v8js.md) - [Webengine](webengine.md) [developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md new file mode 100644 index 0000000000..2e2bf3fec3 --- /dev/null +++ b/docs/attributes-registry/v8js.md @@ -0,0 +1,37 @@ + + + + + +# V8js + +## V8js Attributes + +Describes V8 JS Engine Runtime related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `v8js.gc.type` | string | The type of garbage collection. | `major`; `minor`; `incremental` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `v8js.heap.space.name` | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + +`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). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 0d0dd6033f..7f17940f36 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -50,6 +50,7 @@ semantic conventions when instrumenting runtime environments. - [Go](go-metrics.md) - [JVM](jvm-metrics.md) - [Node.js](nodejs-metrics.md) +- [V8 JS Engine](v8js-metrics.md) ### Attributes diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md new file mode 100644 index 0000000000..d8b4e07a65 --- /dev/null +++ b/docs/runtime/v8js-metrics.md @@ -0,0 +1,315 @@ + + +# Semantic Conventions for V8 JS Engine Runtime Metrics + +**Status**: [Experimental][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. + + + + + +- [Experimental](#experimental) + - [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) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental 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.31.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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### 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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/metrics/v8js-metrics.yaml b/model/metrics/v8js-metrics.yaml new file mode 100644 index 0000000000..be0a43b09a --- /dev/null +++ b/model/metrics/v8js-metrics.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.veightjs.gc.duration + type: metric + metric_name: v8js.gc.duration + brief: "Garbage collection duration." + instrument: histogram + unit: "s" + stability: experimental + prefix: v8js.gc + attributes: + - ref: v8js.gc.type + requirement_level: required + note: > + The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + - id: metric.veightjs.memory.heap.limit + type: metric + metric_name: v8js.memory.heap.limit + brief: "Total heap memory size pre-allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.memory.heap.used + type: metric + metric_name: v8js.memory.heap.used + brief: "Heap Memory size allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_used_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.available_size + type: metric + metric_name: v8js.heap.space.available_size + brief: "Heap space available size." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.physical_size + type: metric + metric_name: v8js.heap.space.physical_size + brief: "Committed size of a heap space." + instrument: updowncounter + unit: "By" + stability: experimental + prefix: v8js.heap.space.physical_size + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) diff --git a/model/registry/v8js.yaml b/model/registry/v8js.yaml new file mode 100644 index 0000000000..a03cbe7143 --- /dev/null +++ b/model/registry/v8js.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.v8js + type: attribute_group + brief: Describes V8 JS Engine Runtime related attributes. + prefix: v8js + attributes: + - id: gc.type + stability: experimental + brief: The type of garbage collection. + type: + members: + - id: major + value: 'major' + brief: 'Major (Mark Sweep Compact).' + stability: experimental + - id: minor + value: 'minor' + brief: 'Minor (Scavenge).' + stability: experimental + - id: incremental + value: 'incremental' + brief: 'Incremental (Incremental Marking).' + stability: experimental + - id: weakcb + value: 'weakcb' + brief: 'Weak Callbacks (Process Weak Callbacks).' + stability: experimental + - id: heap.space.name + stability: experimental + brief: The name of the space type of heap memory. + note: > + Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + type: + members: + - id: new_space + value: 'new_space' + brief: 'New memory space.' + stability: experimental + - id: old_space + value: 'old_space' + brief: 'Old memory space.' + stability: experimental + - id: code_space + value: 'code_space' + brief: 'Code memory space.' + stability: experimental + - id: map_space + value: 'map_space' + brief: 'Map memory space.' + stability: experimental + - id: large_object_space + value: 'large_object_space' + brief: 'Large object memory space.' + stability: experimental