feat(bun): Add bunRuntimeMetricsIntegration

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+### Important Changes
+
+- **feat(node, bun): Add runtime metrics integrations for Node.js and Bun ([#19923](https://github.com/getsentry/sentry-javascript/pull/19923), [#19979](https://github.com/getsentry/sentry-javascript/pull/19979))**
+
+  New `nodeRuntimeMetricsIntegration` and `bunRuntimeMetricsIntegration` automatically collect runtime health metrics and send them to Sentry on a configurable interval (default: 30s). Collected metrics include memory (RSS, heap used/total), CPU utilization, event loop utilization, and process uptime. Node additionally collects event loop delay percentiles (p50, p99). Extra metrics like CPU time and external memory are available as opt-in.
+
+  ```ts
+  // Node.js
+  import * as Sentry from '@sentry/node';
+
+  Sentry.init({
+    dsn: '...',
+    integrations: [Sentry.nodeRuntimeMetricsIntegration()],
+  });
+
+  // Bun
+  import * as Sentry from '@sentry/bun';
+
+  Sentry.init({
+    dsn: '...',
+    integrations: [Sentry.bunRuntimeMetricsIntegration()],
+  });
+  ```
+
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
 ## 10.46.0

dev-packages/node-integration-tests/suites/bun-runtime-metrics/scenario-all.ts

@@ -0,0 +1,27 @@
+import * as Sentry from '@sentry/node';
+import { bunRuntimeMetricsIntegration } from '@sentry/bun';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0.0',
+  environment: 'test',
+  transport: loggingTransport,
+  integrations: [
+    bunRuntimeMetricsIntegration({
+      collectionIntervalMs: 100,
+      collect: {
+        cpuTime: true,
+        memExternal: true,
+      },
+    }),
+  ],
+});
+
+async function run(): Promise<void> {
+  await new Promise<void>(resolve => setTimeout(resolve, 250));
+  await Sentry.flush();
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+run();

dev-packages/node-integration-tests/suites/bun-runtime-metrics/scenario-opt-out.ts

@@ -0,0 +1,29 @@
+import * as Sentry from '@sentry/node';
+import { bunRuntimeMetricsIntegration } from '@sentry/bun';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0.0',
+  environment: 'test',
+  transport: loggingTransport,
+  integrations: [
+    bunRuntimeMetricsIntegration({
+      collectionIntervalMs: 100,
+      collect: {
+        cpuUtilization: false,
+        cpuTime: false,
+        eventLoopUtilization: false,
+        uptime: false,
+      },
+    }),
+  ],
+});
+
+async function run(): Promise<void> {
+  await new Promise<void>(resolve => setTimeout(resolve, 250));
+  await Sentry.flush();
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+run();

dev-packages/node-integration-tests/suites/bun-runtime-metrics/scenario.ts

@@ -0,0 +1,23 @@
+import * as Sentry from '@sentry/node';
+import { bunRuntimeMetricsIntegration } from '@sentry/bun';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0.0',
+  environment: 'test',
+  transport: loggingTransport,
+  integrations: [
+    bunRuntimeMetricsIntegration({
+      collectionIntervalMs: 100,
+    }),
+  ],
+});
+
+async function run(): Promise<void> {
+  await new Promise<void>(resolve => setTimeout(resolve, 250));
+  await Sentry.flush();
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+run();

dev-packages/node-integration-tests/suites/bun-runtime-metrics/test.ts

@@ -0,0 +1,116 @@
+import { afterAll, describe, expect, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../utils/runner';
+
+const SENTRY_ATTRIBUTES = {
+  'sentry.release': { value: '1.0.0', type: 'string' },
+  'sentry.environment': { value: 'test', type: 'string' },
+  'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
+  'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+  'sentry.origin': { value: 'auto.bun.runtime_metrics', type: 'string' },
+};
+
+const gauge = (name: string, unit?: string) => ({
+  timestamp: expect.any(Number),
+  trace_id: expect.any(String),
+  name,
+  type: 'gauge',
+  ...(unit ? { unit } : {}),
+  value: expect.any(Number),
+  attributes: expect.objectContaining(SENTRY_ATTRIBUTES),
+});
+
+const counter = (name: string, unit?: string) => ({
+  timestamp: expect.any(Number),
+  trace_id: expect.any(String),
+  name,
+  type: 'counter',
+  ...(unit ? { unit } : {}),
+  value: expect.any(Number),
+  attributes: expect.objectContaining(SENTRY_ATTRIBUTES),
+});
+
+describe('bunRuntimeMetricsIntegration', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  test('emits default runtime metrics with correct shape', async () => {
+    const runner = createRunner(__dirname, 'scenario.ts')
+      .expect({
+        trace_metric: {
+          items: expect.arrayContaining([
+            gauge('bun.runtime.mem.rss', 'byte'),
+            gauge('bun.runtime.mem.heap_used', 'byte'),
+            gauge('bun.runtime.mem.heap_total', 'byte'),
+            gauge('bun.runtime.cpu.utilization'),
+            gauge('bun.runtime.event_loop.utilization'),
+            counter('bun.runtime.process.uptime', 'second'),
+          ]),
+        },
+      })
+      .start();
+
+    await runner.completed();
+  });
+
+  test('does not emit opt-in metrics by default', async () => {
+    const runner = createRunner(__dirname, 'scenario.ts')
+      .expect({
+        trace_metric: (container: { items: Array<{ name: string }> }) => {
+          const names = container.items.map(item => item.name);
+          expect(names).not.toContain('bun.runtime.cpu.user');
+          expect(names).not.toContain('bun.runtime.cpu.system');
+          expect(names).not.toContain('bun.runtime.mem.external');
+          expect(names).not.toContain('bun.runtime.mem.array_buffers');
+        },
+      })
+      .start();
+
+    await runner.completed();
+  });
+
+  test('emits all metrics when fully opted in', async () => {
+    const runner = createRunner(__dirname, 'scenario-all.ts')
+      .expect({
+        trace_metric: {
+          items: expect.arrayContaining([
+            gauge('bun.runtime.mem.rss', 'byte'),
+            gauge('bun.runtime.mem.heap_used', 'byte'),
+            gauge('bun.runtime.mem.heap_total', 'byte'),
+            gauge('bun.runtime.mem.external', 'byte'),
+            gauge('bun.runtime.mem.array_buffers', 'byte'),
+            gauge('bun.runtime.cpu.user', 'second'),
+            gauge('bun.runtime.cpu.system', 'second'),
+            gauge('bun.runtime.cpu.utilization'),
+            gauge('bun.runtime.event_loop.utilization'),
+            counter('bun.runtime.process.uptime', 'second'),
+          ]),
+        },
+      })
+      .start();
+
+    await runner.completed();
+  });
+
+  test('respects opt-out: only memory metrics remain when cpu/event loop/uptime are disabled', async () => {
+    const runner = createRunner(__dirname, 'scenario-opt-out.ts')
+      .expect({
+        trace_metric: (container: { items: Array<{ name: string }> }) => {
+          const names = container.items.map(item => item.name);
+
+          // Memory metrics should still be present
+          expect(names).toContain('bun.runtime.mem.rss');
+          expect(names).toContain('bun.runtime.mem.heap_used');
+          expect(names).toContain('bun.runtime.mem.heap_total');
+
+          // Everything else should be absent
+          expect(names).not.toContain('bun.runtime.cpu.utilization');
+          expect(names).not.toContain('bun.runtime.event_loop.utilization');
+          expect(names).not.toContain('bun.runtime.process.uptime');
+        },
+      })
+      .start();
+
+    await runner.completed();
+  });
+});

packages/bun/src/index.ts

@@ -192,4 +192,5 @@ export type { BunOptions } from './types';
 export { BunClient } from './client';
 export { getDefaultIntegrations, init } from './sdk';
 export { bunServerIntegration } from './integrations/bunserver';
+export { bunRuntimeMetricsIntegration, type BunRuntimeMetricsOptions } from './integrations/bunRuntimeMetrics';
 export { makeFetchTransport } from './transports';