From 3f83c6688ce1834a5734489b76452f6edcd689ac Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 27 Mar 2026 14:51:49 +0100 Subject: [PATCH] docs(node): Add nodeRuntimeMetricsIntegration documentation Document the new nodeRuntimeMetricsIntegration for collecting Node.js runtime health metrics (memory, CPU, event loop, uptime). Ref: getsentry/sentry-javascript#19923 Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integrations/noderuntimemetrics.mdx | 105 ++++++++++++++++++ .../integrations/javascript.astro.mdx | 1 + .../integrations/javascript.aws-lambda.mdx | 1 + .../integrations/javascript.connect.mdx | 1 + .../integrations/javascript.fastify.mdx | 1 + .../integrations/javascript.gcp-functions.mdx | 1 + .../integrations/javascript.hapi.mdx | 1 + .../integrations/javascript.nestjs.mdx | 1 + .../integrations/javascript.nextjs.mdx | 1 + .../integrations/javascript.node.mdx | 1 + .../integrations/javascript.nuxt.mdx | 1 + .../integrations/javascript.remix.mdx | 1 + .../integrations/javascript.solidstart.mdx | 1 + .../integrations/javascript.sveltekit.mdx | 1 + 14 files changed, 118 insertions(+) create mode 100644 docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx diff --git a/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx new file mode 100644 index 0000000000000..f12bf886b3f6d --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx @@ -0,0 +1,105 @@ +--- +title: NodeRuntimeMetrics +description: "Collect Node.js runtime health metrics such as memory usage, CPU utilization, and event loop delay." +supported: + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.electron + - javascript.nextjs + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.remix + - javascript.react-router + - javascript.astro + - javascript.tanstackstart-react +--- + + + +This integration only works in the Node.js runtime. + + + +_Import name: `Sentry.nodeRuntimeMetricsIntegration`_ + +The `nodeRuntimeMetricsIntegration` periodically collects Node.js runtime health metrics and sends them to Sentry. Metrics include memory usage, CPU utilization, event loop delay, and process uptime. + +```javascript +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [Sentry.nodeRuntimeMetricsIntegration()], +}); +``` + +## Default Metrics + +The following metrics are emitted every 30 seconds by default: + +| Metric | Type | Unit | Description | +|---|---|---|---| +| `node.runtime.mem.rss` | gauge | byte | Resident Set Size — actual process memory footprint | +| `node.runtime.mem.heap_used` | gauge | byte | V8 heap currently in use | +| `node.runtime.mem.heap_total` | gauge | byte | Total V8 heap allocated | +| `node.runtime.cpu.utilization` | gauge | ratio | CPU time / wall-clock time ratio | +| `node.runtime.event_loop.delay.p50` | gauge | second | Median event loop delay | +| `node.runtime.event_loop.delay.p99` | gauge | second | 99th percentile event loop delay | +| `node.runtime.event_loop.utilization` | gauge | ratio | Fraction of time the event loop was active | +| `node.runtime.process.uptime` | counter | second | Cumulative process uptime | + +## Options + +### `collect` + +_Type: `object`_ + +Configure which metrics to collect. You can enable opt-in metrics or disable default ones. + +**Opt-in metrics (off by default):** + +```javascript +Sentry.nodeRuntimeMetricsIntegration({ + collect: { + cpuTime: true, // node.runtime.cpu.user + node.runtime.cpu.system + memExternal: true, // node.runtime.mem.external + node.runtime.mem.array_buffers + eventLoopDelayMin: true, + eventLoopDelayMax: true, + eventLoopDelayMean: true, + eventLoopDelayP90: true, + }, +}); +``` + +**Disabling default metrics:** + +```javascript +Sentry.nodeRuntimeMetricsIntegration({ + collect: { + uptime: false, + eventLoopDelayP50: false, + }, +}); +``` + +### `collectionIntervalMs` + +_Type: `number`_ + +The interval in milliseconds between metric collections. Defaults to `30000` (30 seconds). + +```javascript +Sentry.nodeRuntimeMetricsIntegration({ + collectionIntervalMs: 60_000, +}); +``` diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx index d092355d77965..12331c55264bf 100644 --- a/platform-includes/configuration/integrations/javascript.astro.mdx +++ b/platform-includes/configuration/integrations/javascript.astro.mdx @@ -79,6 +79,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | | [`openAIIntegration`](./openai) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx index 50c51276936f7..43549ac1fd359 100644 --- a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx +++ b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx @@ -35,6 +35,7 @@ | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | | | ✓ | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`mongoIntegration`](./mongo) | | | ✓ | | | [`mongooseIntegration`](./mongoose) | | | ✓ | | | [`mysqlIntegration`](./mysql) | | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.connect.mdx b/platform-includes/configuration/integrations/javascript.connect.mdx index a661f03e69679..5130cacfe200a 100644 --- a/platform-includes/configuration/integrations/javascript.connect.mdx +++ b/platform-includes/configuration/integrations/javascript.connect.mdx @@ -43,6 +43,7 @@ | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`prismaIntegration`](./prisma) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.fastify.mdx b/platform-includes/configuration/integrations/javascript.fastify.mdx index b6d2c4bb95714..97c7747f27be2 100644 --- a/platform-includes/configuration/integrations/javascript.fastify.mdx +++ b/platform-includes/configuration/integrations/javascript.fastify.mdx @@ -43,6 +43,7 @@ | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx index b9139a178002d..788529746414b 100644 --- a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx +++ b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx @@ -36,6 +36,7 @@ | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | | | ✓ | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`mongoIntegration`](./mongo) | | | ✓ | | | [`mongooseIntegration`](./mongoose) | | | ✓ | | | [`mysqlIntegration`](./mysql) | | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.hapi.mdx b/platform-includes/configuration/integrations/javascript.hapi.mdx index 9834971803b8b..a611f5615e63a 100644 --- a/platform-includes/configuration/integrations/javascript.hapi.mdx +++ b/platform-includes/configuration/integrations/javascript.hapi.mdx @@ -43,6 +43,7 @@ | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.nestjs.mdx b/platform-includes/configuration/integrations/javascript.nestjs.mdx index a5c1b75a58844..f6acadef831d6 100644 --- a/platform-includes/configuration/integrations/javascript.nestjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nestjs.mdx @@ -39,6 +39,7 @@ | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx index 770e78cf7536a..4496f327bdcfe 100644 --- a/platform-includes/configuration/integrations/javascript.nextjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nextjs.mdx @@ -84,6 +84,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | | [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.node.mdx b/platform-includes/configuration/integrations/javascript.node.mdx index 6bfa9808310ef..5d830035236da 100644 --- a/platform-includes/configuration/integrations/javascript.node.mdx +++ b/platform-includes/configuration/integrations/javascript.node.mdx @@ -31,6 +31,7 @@ | [`nativeNodeFetchIntegration`](./nodefetch) | ✓ | | ✓ | ✓ | | [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | | [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | | [`postgresIntegration`](./postgres) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx index aca7498b91dea..66b3c288a8843 100644 --- a/platform-includes/configuration/integrations/javascript.nuxt.mdx +++ b/platform-includes/configuration/integrations/javascript.nuxt.mdx @@ -78,6 +78,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | | [`openAIIntegration`](./openai) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx index 308e58070eac0..f9b4aa7edc304 100644 --- a/platform-includes/configuration/integrations/javascript.remix.mdx +++ b/platform-includes/configuration/integrations/javascript.remix.mdx @@ -78,6 +78,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | | [`openAIIntegration`](./openai) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx index 83b4a82ecdeaf..6ff9af91977c8 100644 --- a/platform-includes/configuration/integrations/javascript.solidstart.mdx +++ b/platform-includes/configuration/integrations/javascript.solidstart.mdx @@ -78,6 +78,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | | [`openAIIntegration`](./openai) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx index 6826dcff63b19..24faf49f0dd2d 100644 --- a/platform-includes/configuration/integrations/javascript.sveltekit.mdx +++ b/platform-includes/configuration/integrations/javascript.sveltekit.mdx @@ -77,6 +77,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`fsIntegration`](./fs) | | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`localVariablesIntegration`](./localvariables) | | ✓ | | | +| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ |