Skip to content

feat: expose V8 heap size limit as default metric (nodejs_heap_size_limit_bytes)#745

Open
szymonskirgajllo wants to merge 1 commit into
siimon:masterfrom
szymonskirgajllo:master
Open

feat: expose V8 heap size limit as default metric (nodejs_heap_size_limit_bytes)#745
szymonskirgajllo wants to merge 1 commit into
siimon:masterfrom
szymonskirgajllo:master

Conversation

@szymonskirgajllo

Copy link
Copy Markdown

Motivation
Node’s heap grows over time up to a configured maximum. Metrics such as heapUsed or heapTotal from process.memoryUsage() reflect current allocation, not how close the process is to its hard ceiling. Alerts based only on “heap is large” or on heapUsed / heapTotal often track elastic growth rather than risk of hitting the V8 limit and OOM.

When operators set an explicit heap cap (e.g. V8’s --max-heap-size, or related flags), they need a stable denominator in Prometheus: the maximum JavaScript heap size the runtime will allow. Comparing used heap to that limit supports alerts such as “≥90% of the configured heap is in use,” which align with capacity planning and OOM risk, not with normal heap expansion.

What this PR does

  • Adds default gauge nodejs_heap_size_limit_bytes, sourced from v8.getHeapStatistics().heap_size_limit, alongside the existing heap metrics in heapSizeAndUsed (same labels as nodejs_heap_size_* / external memory).
  • Omits this metric when getHeapStatistics is unavailable or throws ERR_NOT_IMPLEMENTED (e.g. some non-Node runtimes); metricNames stays consistent with what is actually registered.\
  • Treats a missing getHeapStatistics implementation like unsupported (safe with partial v8 mocks in tests).
  • Extends tests (including isolated v8 behaviour) and updates the default-metrics example / changelog.

Example alerting (Prometheus)
nodejs_heap_size_used_bytes / nodejs_heap_size_limit_bytes > 0.9

Tune thresholds and for: to your SLOs. Ensure the process is started with a known heap cap so the limit metric matches your intent.

Notes

  • heap_size_limit is read from V8 on each collection (same pattern as before for clarity).
  • Limit is process-level; it is not per heap space (those remain in the existing space metrics).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant