chore: Add v8js.memory.heap.max metric for absolute heap size limit

Add v8js.memory.heap.max gauge metric representing the absolute maximum
heap size (heap_size_limit) from v8.getHeapStatistics(). This value is
the hard ceiling controlled by --max-old-space-size or V8 defaults.

Related issue: open-telemetry#3476
Related instrumentation PR: open-telemetry/opentelemetry-js-contrib#3405

Author: Hronom

.chloggen/add_v8js_memory_heap_max.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: v8js
+note: Add `v8js.memory.heap.max` gauge for the absolute maximum heap size from `v8.getHeapStatistics()`.
+issues: [3476]

docs/runtime/v8js-metrics.md

@@ -15,6 +15,7 @@ This document describes semantic conventions for V8 JS Engine Runtime metrics in
 - [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused)
 - [Metric: `v8js.memory.heap.space.available_size`](#metric-v8jsmemoryheapspaceavailable_size)
 - [Metric: `v8js.memory.heap.space.physical_size`](#metric-v8jsmemoryheapspacephysical_size)
+- [Metric: `v8js.memory.heap.max`](#metric-v8jsmemoryheapmax)
 
 <!-- tocstop -->
 
@@ -214,5 +215,24 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+## Metric: `v8js.memory.heap.max`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.v8js.memory.heap.max -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
+| -------- | --------------- | ----------- | -------------- | --------- | ------ |
+| `v8js.memory.heap.max` | Gauge | `By` | Maximum heap size allowed by the V8 engine. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |
+
+**[1]:** The value can be retrieved from value `heap_size_limit` of [`v8.getHeapStatistics()`](https://nodejs.org/api/v8.html#v8getheapstatistics). This represents the absolute ceiling the heap can grow to, controlled by `--max-old-space-size` or V8 defaults.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/document-status.md
 [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended

model/v8js/metrics.yaml

@@ -80,3 +80,19 @@ groups:
         requirement_level: required
     note: >
       Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+
+  - id: metric.v8js.memory.heap.max
+    type: metric
+    metric_name: v8js.memory.heap.max
+    annotations:
+      code_generation:
+        metric_value_type: int
+    brief: "Maximum heap size allowed by the V8 engine."
+    instrument: gauge
+    unit: "By"
+    stability: development
+    note: >
+      The value can be retrieved from value `heap_size_limit` of
+      [`v8.getHeapStatistics()`](https://nodejs.org/api/v8.html#v8getheapstatistics).
+      This represents the absolute ceiling the heap can grow to, controlled by
+      `--max-old-space-size` or V8 defaults.