diff --git a/.chloggen/nodejs-metrics.yaml b/.chloggen/nodejs-metrics.yaml new file mode 100755 index 0000000000..a1cdc83de9 --- /dev/null +++ b/.chloggen/nodejs-metrics.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: 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 specific 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] + +# (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/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index af486e4502..5f59e17a50 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -52,6 +52,7 @@ body: - area:log - area:messaging - area:network + - area:nodejs - area:oci - area:opentracing - area:os diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 3d00899d2d..c77cf6d159 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -45,6 +45,7 @@ body: - area:log - area:messaging - area:network + - area:nodejs - area:oci - area:opentracing - area:os diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 3985923373..9e67b0e7cd 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -54,6 +54,7 @@ body: - area:log - area:messaging - area:network + - area:nodejs - area:oci - area:opentracing - area:os diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 9a7fcaf3ad..06101801fa 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) +- [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..8bd4154e57 --- /dev/null +++ b/docs/runtime/nodejs-metrics.md @@ -0,0 +1,128 @@ + + +# Semantic Conventions for Node.js Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Node.js metrics in OpenTelemetry. + + + + + +- [Experimental](#experimental) + - [Metric: `nodejs.active_handles.count`](#metric-nodejsactive_handlescount) + - [Metric: `nodejs.active_requests.count`](#metric-nodejsactive_requestscount) + - [Metric: `nodejs.eventloop.lag`](#metric-nodejseventlooplag) + - [Metric: `nodejs.gc.duration`](#metric-nodejsgcduration) + - [Metric: `nodejs.memory.size`](#metric-nodejsmemorysize) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Node.js metrics captured under `nodejs.` + +### Metric: `nodejs.active_handles.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.active_handles.count` | UpDownCounter | `{handles}` | Number of active handles. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `nodejs.version` | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `nodejs.active_requests.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.active_requests.count` | UpDownCounter | `{requests}` | Number of active requests. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `nodejs.version` | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `nodejs.eventloop.lag` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.lag` | Histogram | `s` | Event loop lag. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `nodejs.version` | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `nodejs.gc.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.gc.duration` | Histogram | `s` | Garbage collection duration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `nodejs.gc.name` | string | Name of the garbage collector. | `G1 Young Generation`; `G1 Old Generation` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nodejs.version` | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `nodejs.memory.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.memory.size` | UpDownCounter | `By` | Memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `nodejs.memory.state` | string | The state of memory. | `total`; `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nodejs.memory.type` | string | The type of memory. | `heap`; `external` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nodejs.version` | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`nodejs.memory.state` MUST be one of the following: + +| Value | Description | Stability | +|---|---|---| +| `total` | Total memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `used` | Used memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`nodejs.memory.type` MUST be one of the following: + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `external` | External memory | ![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/nodejs-metrics.yaml b/model/metrics/nodejs-metrics.yaml new file mode 100644 index 0000000000..08a8d5c3f3 --- /dev/null +++ b/model/metrics/nodejs-metrics.yaml @@ -0,0 +1,87 @@ +groups: + - id: metric.nodejs.active_handles.count + type: metric + metric_name: nodejs.active_handles.count + brief: "Number of active handles." + extends: attributes.nodejs.version + instrument: updowncounter + unit: "{handles}" + stability: experimental + + - id: metric.nodejs.active_requests.count + type: metric + metric_name: nodejs.active_requests.count + brief: "Number of active requests." + extends: attributes.nodejs.version + instrument: updowncounter + unit: "{requests}" + stability: experimental + + - id: metric.nodejs.eventloop.lag + type: metric + metric_name: nodejs.eventloop.lag + brief: "Event loop lag." + extends: attributes.nodejs.version + instrument: histogram + unit: "s" + stability: experimental + + - id: metric.nodejs.gc.duration + type: metric + metric_name: nodejs.gc.duration + brief: "Garbage collection duration." + extends: attributes.nodejs.version + instrument: histogram + unit: "s" + stability: experimental + prefix: nodejs.gc + attributes: + - id: name + stability: experimental + type: string + requirement_level: recommended + brief: Name of the garbage collector. + examples: ["G1 Young Generation", "G1 Old Generation"] + + - id: metric.nodejs.memory.size + type: metric + metric_name: nodejs.memory.size + brief: "Memory size." + extends: attributes.nodejs.version + instrument: updowncounter + unit: "By" + stability: experimental + prefix: nodejs.memory + attributes: + - id: type + stability: experimental + type: + allow_custom_values: false + members: + - id: heap + value: 'heap' + brief: 'Heap memory.' + stability: experimental + - id: external + value: 'external' + brief: 'External memory' + stability: experimental + requirement_level: recommended + brief: The type of memory. + examples: ["heap", "external"] + - id: state + stability: experimental + type: + allow_custom_values: false + members: + - id: total + value: 'total' + brief: 'Total memory.' + stability: experimental + - id: used + value: 'used' + brief: 'Used memory' + stability: experimental + requirement_level: recommended + brief: The state of memory. + examples: ["total", "used"] diff --git a/model/registry/nodejs.yaml b/model/registry/nodejs.yaml new file mode 100644 index 0000000000..5bd6f2ca25 --- /dev/null +++ b/model/registry/nodejs.yaml @@ -0,0 +1,12 @@ +groups: + - id: attributes.nodejs.version + type: attribute_group + brief: "Describes Node.js version attribute." + prefix: nodejs + attributes: + - id: version + stability: experimental + type: string + requirement_level: recommended + brief: Node.js version. + examples: ["v22.0.0", "v21.7.3"]