add heap memory and eventloop utilization

open-telemetry · May 3, 2024 · b2ca8e0 · b2ca8e0
1 parent f994f89
commit b2ca8e0
Show file tree

Hide file tree

Showing 4 changed files with 171 additions and 44 deletions.
diff --git a/docs/attributes-registry/nodejs.md b/docs/attributes-registry/nodejs.md
@@ -12,22 +12,24 @@ Describes Node.js related attributes.
 
 | Attribute                   | Type   | Description                         | Examples                        | Stability                                                        |
 | --------------------------- | ------ | ----------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
-| `nodejs.eventloop.lag.type` | string | The type of the event loop latency. | `min`; `max`; `avg`             | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nodejs.eventloop.lag.type` | string | The type of the event loop latency. | `min`; `max`; `mean`            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `nodejs.gc.type`            | string | The type of garbage collection.     | `major`; `minor`; `incremental` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nodejs.heap.size.state`    | string | The size of heap memory.            | `total`; `used`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nodejs.heap.space.state`   | string | The space of heap memory.           | `total`; `used`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `nodejs.memory.state`       | string | The state of memory.                | `total`; `used`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `nodejs.memory.type`        | string | The type of memory.                 | `heap`; `external`              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `nodejs.version`            | string | Node.js version.                    | `v22.0.0`; `v21.7.3`            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `nodejs.eventloop.lag.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                                                        |
-| ----- | --------------------------------- | ---------------------------------------------------------------- |
-| `min` | Event loop minimum latency.       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `max` | Event loop maximum latency.       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `avg` | Event loop average latency.       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `p50` | Event loop 50 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `p90` | Event loop 90 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `p99` | Event loop 99 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Value    | Description                            | Stability                                                        |
+| -------- | -------------------------------------- | ---------------------------------------------------------------- |
+| `min`    | Event loop minimum latency.            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `max`    | Event loop maximum latency.            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `mean`   | Event loop mean latency.               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `stddev` | Event loop standard deviation latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `p50`    | Event loop 50 percentile latency.      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `p90`    | Event loop 90 percentile latency.      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `p99`    | Event loop 99 percentile latency.      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `nodejs.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.
 
@@ -38,16 +40,23 @@ Describes Node.js related attributes.
 | `incremental` | Incremental (Incremental Marking).       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `weakcb`      | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
+`nodejs.heap.size.state` 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                                                        |
+| ------- | ----------------------- | ---------------------------------------------------------------- |
+| `total` | Total heap memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used`  | Used heap memory size.  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`nodejs.heap.space.state` 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                                                        |
+| ------- | ------------------------ | ---------------------------------------------------------------- |
+| `total` | Total heap memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used`  | Used heap memory space.  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
 `nodejs.memory.state` 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                                                        |
 | ------- | ------------- | ---------------------------------------------------------------- |
 | `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` 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                                                        |
-| ---------- | --------------- | ---------------------------------------------------------------- |
-| `heap`     | Heap memory.    | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `external` | External memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used`  | Used memory.  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md
@@ -16,8 +16,11 @@ This document describes semantic conventions for Node.js metrics in OpenTelemetr
   - [Metric: `nodejs.active_handles.count`](#metric-nodejsactive_handlescount)
   - [Metric: `nodejs.active_libuv_requests.count`](#metric-nodejsactive_libuv_requestscount)
   - [Metric: `nodejs.eventloop.lag`](#metric-nodejseventlooplag)
+  - [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization)
   - [Metric: `nodejs.gc.duration`](#metric-nodejsgcduration)
   - [Metric: `nodejs.memory.size`](#metric-nodejsmemorysize)
+  - [Metric: `nodejs.heap.size`](#metric-nodejsheapsize)
+  - [Metric: `nodejs.heap.space`](#metric-nodejsheapspace)
 
 <!-- tocstop -->
 
@@ -81,12 +84,30 @@ This metric is [recommended][MetricRecommended].
 |---|---|---|
 | `min` | Event loop minimum latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `max` | Event loop maximum latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `avg` | Event loop average latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `mean` | Event loop mean latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `stddev` | Event loop standard deviation latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `p50` | Event loop 50 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `p90` | Event loop 90 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `p99` | Event loop 99 percentile latency. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
+
+### Metric: `nodejs.eventloop.utilization`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.nodejs.eventloop.utilization(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `nodejs.eventloop.utilization` | Gauge | `s` | Event loop utilization. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
+<!-- semconv metric.nodejs.eventloop.utilization(full) -->
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`nodejs.version`](/docs/attributes-registry/nodejs.md) | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
 ### Metric: `nodejs.gc.duration`
 
 This metric is [recommended][MetricRecommended].
@@ -120,29 +141,69 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.nodejs.memory.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `nodejs.memory.size` | UpDownCounter | `By` | Memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `nodejs.memory.size` | UpDownCounter | `By` | External memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
 <!-- semconv metric.nodejs.memory.size(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`nodejs.memory.state`](/docs/attributes-registry/nodejs.md) | string | The state of memory. | `total`; `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`nodejs.memory.type`](/docs/attributes-registry/nodejs.md) | string | The type of memory. | `heap`; `external` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`nodejs.version`](/docs/attributes-registry/nodejs.md) | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `nodejs.memory.state` 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 |
 |---|---|---|
 | `total` | Total memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `used` | Used memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used` | Used memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
+### Metric: `nodejs.heap.size`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.nodejs.heap.size(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `nodejs.heap.size` | UpDownCounter | `By` | Heap size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
+<!-- semconv metric.nodejs.heap.size(full) -->
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`nodejs.heap.size.state`](/docs/attributes-registry/nodejs.md) | string | The size of heap memory. | `total`; `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`nodejs.version`](/docs/attributes-registry/nodejs.md) | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`nodejs.heap.size.state` 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 |
+|---|---|---|
+| `total` | Total heap memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used` | Used heap memory size. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
+### Metric: `nodejs.heap.space`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.nodejs.heap.space(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `nodejs.heap.space` | UpDownCounter | `By` | Heap space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- endsemconv -->
+
+<!-- semconv metric.nodejs.heap.space(full) -->
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`nodejs.heap.space.state`](/docs/attributes-registry/nodejs.md) | string | The space of heap memory. | `total`; `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`nodejs.version`](/docs/attributes-registry/nodejs.md) | string | Node.js version. | `v22.0.0`; `v21.7.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-`nodejs.memory.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.
+`nodejs.heap.space.state` 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 |
 |---|---|---|
-| `heap` | Heap memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `external` | External memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `total` | Total heap memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `used` | Used heap memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md

diff --git a/model/metrics/nodejs-metrics.yaml b/model/metrics/nodejs-metrics.yaml
@@ -35,6 +35,18 @@ groups:
       - ref: nodejs.eventloop.lag.type
         requirement_level: recommended
 
+  - id: metric.nodejs.eventloop.utilization
+    type: metric
+    metric_name: nodejs.eventloop.utilization
+    brief: "Event loop utilization."
+    instrument: gauge
+    unit: "s"
+    stability: experimental
+    prefix: nodejs.eventloop.utilization
+    attributes:
+      - ref: nodejs.version
+        requirement_level: recommended
+
   - id: metric.nodejs.gc.duration
     type: metric
     metric_name: nodejs.gc.duration
@@ -52,15 +64,41 @@ groups:
   - id: metric.nodejs.memory.size
     type: metric
     metric_name: nodejs.memory.size
-    brief: "Memory size."
+    brief: "External memory size."
     instrument: updowncounter
     unit: "By"
     stability: experimental
     prefix: nodejs.memory
     attributes:
       - ref: nodejs.version
         requirement_level: recommended
-      - ref: nodejs.memory.type
-        requirement_level: recommended
       - ref: nodejs.memory.state
         requirement_level: recommended
+
+  - id: metric.nodejs.heap.size
+    type: metric
+    metric_name: nodejs.heap.size
+    brief: "Heap size."
+    instrument: updowncounter
+    unit: "By"
+    stability: experimental
+    prefix: nodejs.heap.size
+    attributes:
+      - ref: nodejs.version
+        requirement_level: recommended
+      - ref: nodejs.heap.size.state
+        requirement_level: recommended
+
+  - id: metric.nodejs.heap.space
+    type: metric
+    metric_name: nodejs.heap.space
+    brief: "Heap space."
+    instrument: updowncounter
+    unit: "By"
+    stability: experimental
+    prefix: nodejs.heap.space
+    attributes:
+      - ref: nodejs.version
+        requirement_level: recommended
+      - ref: nodejs.heap.space.state
+        requirement_level: recommended
diff --git a/model/registry/nodejs.yaml b/model/registry/nodejs.yaml
@@ -22,9 +22,13 @@ groups:
               value: 'max'
               brief: 'Event loop maximum latency.'
               stability: experimental
-            - id: avg
-              value: avg
-              brief: 'Event loop average latency.'
+            - id: mean
+              value: mean
+              brief: 'Event loop mean latency.'
+              stability: experimental
+            - id: stddev
+              value: stddev
+              brief: 'Event loop standard deviation latency.'
               stability: experimental
             - id: p50
               value: 'p50'
@@ -62,33 +66,48 @@ groups:
               value: 'weakcb'
               brief: 'Weak Callbacks (Process Weak Callbacks).'
               stability: experimental
-      - id: memory.type
+      - id: memory.state
         stability: experimental
         type:
           allow_custom_values: false
           members:
-            - id: heap
-              value: 'heap'
-              brief: 'Heap memory.'
+            - id: total
+              value: 'total'
+              brief: 'Total memory.'
               stability: experimental
-            - id: external
-              value: 'external'
-              brief: 'External memory'
+            - id: used
+              value: 'used'
+              brief: 'Used memory.'
               stability: experimental
-        brief: The type of memory.
-        examples: ["heap", "external"]
-      - id: memory.state
+        brief: The state of memory.
+        examples: ["total", "used"]
+      - id: heap.size.state
         stability: experimental
         type:
           allow_custom_values: false
           members:
             - id: total
               value: 'total'
-              brief: 'Total memory.'
+              brief: 'Total heap memory size.'
               stability: experimental
             - id: used
               value: 'used'
-              brief: 'Used memory'
+              brief: 'Used heap memory size.'
               stability: experimental
-        brief: The state of memory.
+        brief: The size of heap memory.
+        examples: ["total", "used"]
+      - id: heap.space.state
+        stability: experimental
+        type:
+          allow_custom_values: false
+          members:
+            - id: total
+              value: 'total'
+              brief: 'Total heap memory space.'
+              stability: experimental
+            - id: used
+              value: 'used'
+              brief: 'Used heap memory space.'
+              stability: experimental
+        brief: The space of heap memory.
         examples: ["total", "used"]