diff --git a/.chloggen/nodejs-metrics.yaml b/.chloggen/nodejs-metrics.yaml new file mode 100755 index 0000000000..51b11a961e --- /dev/null +++ b/.chloggen/nodejs-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: nodejs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for Node.js 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/docs/runtime/README.md b/docs/runtime/README.md index bcabd1d7b6..0d0dd6033f 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -47,8 +47,9 @@ Also consider the [OS process metrics](/docs/system/process-metrics.md) semantic conventions when instrumenting runtime environments. -- [JVM](jvm-metrics.md) - [Go](go-metrics.md) +- [JVM](jvm-metrics.md) +- [Node.js](nodejs-metrics.md) ### Attributes diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md new file mode 100644 index 0000000000..60fcd283af --- /dev/null +++ b/docs/runtime/nodejs-metrics.md @@ -0,0 +1,343 @@ + + +# Semantic Conventions for Node.js Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Node.js Runtime metrics in OpenTelemetry. + + + + + +- [Experimental](#experimental) + - [Metric: `nodejs.eventloop.delay.min`](#metric-nodejseventloopdelaymin) + - [Metric: `nodejs.eventloop.delay.max`](#metric-nodejseventloopdelaymax) + - [Metric: `nodejs.eventloop.delay.mean`](#metric-nodejseventloopdelaymean) + - [Metric: `nodejs.eventloop.delay.stddev`](#metric-nodejseventloopdelaystddev) + - [Metric: `nodejs.eventloop.delay.p50`](#metric-nodejseventloopdelayp50) + - [Metric: `nodejs.eventloop.delay.p90`](#metric-nodejseventloopdelayp90) + - [Metric: `nodejs.eventloop.delay.p99`](#metric-nodejseventloopdelayp99) + - [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Node.js Runtime metrics captured under `nodejs`. + +Note: The metrics for eventloop delay are split into separated values instead of a single histogram, because node runtime +only returns single values through [`perf_hooks.monitorEventLoopDelay([options])`][Eventloop] and not the entire +histogram, so it's not possible to convert it to an OpenTelemetry histogram. + +### Metric: `nodejs.eventloop.delay.min` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.min` | Gauge | `s` | Event loop minimum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.max` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.max` | Gauge | `s` | Event loop maximum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.mean` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.mean` | Gauge | `s` | Event loop mean delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.stddev` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.stddev` | Gauge | `s` | Event loop standard deviation delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p50` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p50` | Gauge | `s` | Event loop 50 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p90` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p90` | Gauge | `s` | Event loop 90 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p99` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p99` | Gauge | `s` | Event loop 99 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.utilization` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.utilization` | Gauge | `1` | Event loop utilization. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value range is [0.0,1.0] and can be retrieved from value [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) + + + + + + + + + + + + + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended +[Eventloop]: https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions diff --git a/model/metrics/nodejs-metrics.yaml b/model/metrics/nodejs-metrics.yaml new file mode 100644 index 0000000000..9def4fa143 --- /dev/null +++ b/model/metrics/nodejs-metrics.yaml @@ -0,0 +1,81 @@ +groups: + - id: metric.nodejs.eventloop.delay.min + type: metric + metric_name: nodejs.eventloop.delay.min + brief: "Event loop minimum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.max + type: metric + metric_name: nodejs.eventloop.delay.max + brief: "Event loop maximum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.mean + type: metric + metric_name: nodejs.eventloop.delay.mean + brief: "Event loop mean delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.stddev + type: metric + metric_name: nodejs.eventloop.delay.stddev + brief: "Event loop standard deviation delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pfifty + type: metric + metric_name: nodejs.eventloop.delay.p50 + brief: "Event loop 50 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety + type: metric + metric_name: nodejs.eventloop.delay.p90 + brief: "Event loop 90 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety_nine + type: metric + metric_name: nodejs.eventloop.delay.p99 + brief: "Event loop 99 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.utilization + type: metric + metric_name: nodejs.eventloop.utilization + brief: "Event loop utilization." + instrument: gauge + unit: "1" + stability: experimental + note: > + The value range is [0.0,1.0] and can be retrieved from value + [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 64e16bead2..f698ae6754 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -20,6 +20,7 @@ acronyms: - GCE - HTTP - JVM + - NodeJS - OCI - OTel - OpenTracing