feat(node-core): Add node-core/light

Author: andreiborza

packages/node-core/README.md

@@ -116,6 +116,116 @@ If it is not possible for you to pass the `--import` flag to the Node.js binary,
 NODE_OPTIONS="--import ./instrument.mjs" npm run start
 ```
 
+## Errors-only Lightweight Mode
+
+If you only need error monitoring without performance tracing, you can use the lightweight mode which doesn't require OpenTelemetry dependencies. This mode is ideal for:
+
+- Applications that only need error tracking
+- Reducing bundle size and runtime overhead
+- Environments where OpenTelemetry isn't needed
+
+### Installation (Light Mode)
+
+```bash
+npm install @sentry/node-core
+
+# Or yarn
+yarn add @sentry/node-core
+```
+
+### Usage (Light Mode)
+
+Import from `@sentry/node-core/light` instead of `@sentry/node-core`:
+
+```js
+// ESM
+import * as Sentry from '@sentry/node-core/light';
+
+// CJS
+const Sentry = require('@sentry/node-core/light');
+
+// Initialize Sentry BEFORE creating your HTTP server
+Sentry.init({
+  dsn: '__DSN__',
+  // ...
+});
+
+// Then create your server (Express, Fastify, etc.)
+const app = express();
+```
+
+**Important:** Initialize Sentry **before** creating your HTTP server to enable automatic request isolation.
+
+### Features in Light Mode
+
+**Included:**
+
+- Error tracking and reporting
+- Automatic request isolation (Node.js 22+)
+- Breadcrumbs
+- Context and user data
+- Local variables capture
+- Distributed tracing (via `sentry-trace` and `baggage` headers)
+
+**Not included:**
+
+- Performance monitoring (no spans/transactions)
+
+### Automatic Request Isolation
+
+Light mode includes automatic request isolation for HTTP servers (requires Node.js 22+). This ensures that context (tags, user data, breadcrumbs) set during a request doesn't leak to other concurrent requests.
+
+No manual middleware or `--import` flag is required - just initialize Sentry before creating your server:
+
+```js
+import * as Sentry from '@sentry/node-core/light';
+import express from 'express';
+
+// Initialize FIRST
+Sentry.init({ dsn: '__DSN__' });
+
+// Then create server
+const app = express();
+
+app.get('/error', (req, res) => {
+  // This data is automatically isolated per request
+  Sentry.setTag('userId', req.params.id);
+  Sentry.captureException(new Error('Something went wrong'));
+  res.status(500).send('Error');
+});
+```
+
+### Manual Request Isolation (Node.js < 22)
+
+If you're using Node.js versions below 22, automatic request isolation is not available. You'll need to manually wrap your request handlers with `withIsolationScope`:
+
+```js
+import * as Sentry from '@sentry/node-core/light';
+import express from 'express';
+
+Sentry.init({ dsn: '__DSN__' });
+
+const app = express();
+
+// Add middleware to manually isolate requests
+app.use((req, res, next) => {
+  Sentry.withIsolationScope(() => {
+    next();
+  });
+});
+
+app.get('/error', (req, res) => {
+  Sentry.setTag('userId', req.params.id);
+  Sentry.captureException(new Error('Something went wrong'));
+  res.status(500).send('Error');
+});
+```
+
+**Caveats:**
+- Manual isolation prevents scope data leakage between requests
+- However, **distributed tracing will not work correctly** - incoming `sentry-trace` and `baggage` headers won't be automatically extracted and propagated
+- For full distributed tracing support, use Node.js 22+ or the full `@sentry/node` SDK with OpenTelemetry
+
 ## Links
 
 - [Official SDK Docs](https://docs.sentry.io/quickstart/)

packages/node-core/package.json

@@ -27,6 +27,16 @@
         "default": "./build/cjs/index.js"
       }
     },
+    "./light": {
+      "import": {
+        "types": "./build/types/light/index.d.ts",
+        "default": "./build/esm/light/index.js"
+      },
+      "require": {
+        "types": "./build/types/light/index.d.ts",
+        "default": "./build/cjs/light/index.js"
+      }
+    },
     "./import": {
       "import": {
         "default": "./build/import-hook.mjs"
@@ -63,12 +73,38 @@
     "@opentelemetry/instrumentation": ">=0.57.1 <1",
     "@opentelemetry/resources": "^1.30.1 || ^2.1.0 || ^2.2.0",
     "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0 || ^2.2.0",
-    "@opentelemetry/semantic-conventions": "^1.37.0"
+    "@opentelemetry/semantic-conventions": "^1.37.0",
+    "@sentry/opentelemetry": "10.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/context-async-hooks": {
+      "optional": true
+    },
+    "@opentelemetry/core": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
+    "@sentry/opentelemetry": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@apm-js-collab/tracing-hooks": "^0.3.1",
     "@sentry/core": "10.30.0",
-    "@sentry/opentelemetry": "10.30.0",
     "import-in-the-middle": "^2"
   },
   "devDependencies": {
@@ -80,6 +116,7 @@
     "@opentelemetry/resources": "^2.2.0",
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.37.0",
+    "@sentry/opentelemetry": "10.30.0",
     "@types/node": "^18.19.1"
   },
   "scripts": {

packages/node-core/rollup.npm.config.mjs

@@ -19,7 +19,7 @@ export default [
   localVariablesWorkerConfig,
   ...makeNPMConfigVariants(
     makeBaseNPMConfig({
-      entrypoints: ['src/index.ts', 'src/init.ts'],
+      entrypoints: ['src/index.ts', 'src/init.ts', 'src/light/index.ts'],
       packageSpecificConfig: {
         output: {
           // set exports to 'named' or 'auto' so that rollup doesn't warn

packages/node-core/src/integrations/http/httpServerIntegration.ts

@@ -18,7 +18,7 @@ import {
 } from '@sentry/core';
 import { DEBUG_BUILD } from '../../debug-build';
 import type { NodeClient } from '../../sdk/client';
-import { MAX_BODY_BYTE_LENGTH } from './constants';
+import { patchRequestToCaptureBody } from '../../utils/captureRequestBody';
 
 type ServerEmit = typeof Server.prototype.emit;
 
@@ -128,6 +128,10 @@ const _httpServerIntegration = ((options: HttpServerIntegrationOptions = {}) =>
 /**
  * This integration handles request isolation, trace continuation and other core Sentry functionality around incoming http requests
  * handled via the node `http` module.
+ *
+ * This version uses OpenTelemetry for context propagation and span management.
+ *
+ * @see {@link ../../light/integrations/httpServerIntegration.ts} for the lightweight version without OpenTelemetry
  */
 export const httpServerIntegration = _httpServerIntegration as (
   options?: HttpServerIntegrationOptions,
@@ -189,7 +193,7 @@ function instrumentServer(
 
       const url = request.url || '/';
       if (maxRequestBodySize !== 'none' && !ignoreRequestBody?.(url, request)) {
-        patchRequestToCaptureBody(request, isolationScope, maxRequestBodySize);
+        patchRequestToCaptureBody(request, isolationScope, maxRequestBodySize, INTEGRATION_NAME);
       }
 
       // Update the isolation scope, isolate this request
@@ -315,122 +319,3 @@ export function recordRequestSession(
     }
   });
 }
-
-/**
- * This method patches the request object to capture the body.
- * Instead of actually consuming the streamed body ourselves, which has potential side effects,
- * we monkey patch `req.on('data')` to intercept the body chunks.
- * This way, we only read the body if the user also consumes the body, ensuring we do not change any behavior in unexpected ways.
- */
-function patchRequestToCaptureBody(
-  req: IncomingMessage,
-  isolationScope: Scope,
-  maxIncomingRequestBodySize: 'small' | 'medium' | 'always',
-): void {
-  let bodyByteLength = 0;
-  const chunks: Buffer[] = [];
-
-  DEBUG_BUILD && debug.log(INTEGRATION_NAME, 'Patching request.on');
-
-  /**
-   * We need to keep track of the original callbacks, in order to be able to remove listeners again.
-   * Since `off` depends on having the exact same function reference passed in, we need to be able to map
-   * original listeners to our wrapped ones.
-   */
-  const callbackMap = new WeakMap();
-
-  const maxBodySize =
-    maxIncomingRequestBodySize === 'small'
-      ? 1_000
-      : maxIncomingRequestBodySize === 'medium'
-        ? 10_000
-        : MAX_BODY_BYTE_LENGTH;
-
-  try {
-    // eslint-disable-next-line @typescript-eslint/unbound-method
-    req.on = new Proxy(req.on, {
-      apply: (target, thisArg, args: Parameters<typeof req.on>) => {
-        const [event, listener, ...restArgs] = args;
-
-        if (event === 'data') {
-          DEBUG_BUILD &&
-            debug.log(INTEGRATION_NAME, `Handling request.on("data") with maximum body size of ${maxBodySize}b`);
-
-          const callback = new Proxy(listener, {
-            apply: (target, thisArg, args: Parameters<typeof listener>) => {
-              try {
-                const chunk = args[0] as Buffer | string;
-                const bufferifiedChunk = Buffer.from(chunk);
-
-                if (bodyByteLength < maxBodySize) {
-                  chunks.push(bufferifiedChunk);
-                  bodyByteLength += bufferifiedChunk.byteLength;
-                } else if (DEBUG_BUILD) {
-                  debug.log(
-                    INTEGRATION_NAME,
-                    `Dropping request body chunk because maximum body length of ${maxBodySize}b is exceeded.`,
-                  );
-                }
-              } catch (err) {
-                DEBUG_BUILD && debug.error(INTEGRATION_NAME, 'Encountered error while storing body chunk.');
-              }
-
-              return Reflect.apply(target, thisArg, args);
-            },
-          });
-
-          callbackMap.set(listener, callback);
-
-          return Reflect.apply(target, thisArg, [event, callback, ...restArgs]);
-        }
-
-        return Reflect.apply(target, thisArg, args);
-      },
-    });
-
-    // Ensure we also remove callbacks correctly
-    // eslint-disable-next-line @typescript-eslint/unbound-method
-    req.off = new Proxy(req.off, {
-      apply: (target, thisArg, args: Parameters<typeof req.off>) => {
-        const [, listener] = args;
-
-        const callback = callbackMap.get(listener);
-        if (callback) {
-          callbackMap.delete(listener);
-
-          const modifiedArgs = args.slice();
-          modifiedArgs[1] = callback;
-          return Reflect.apply(target, thisArg, modifiedArgs);
-        }
-
-        return Reflect.apply(target, thisArg, args);
-      },
-    });
-
-    req.on('end', () => {
-      try {
-        const body = Buffer.concat(chunks).toString('utf-8');
-        if (body) {
-          // Using Buffer.byteLength here, because the body may contain characters that are not 1 byte long
-          const bodyByteLength = Buffer.byteLength(body, 'utf-8');
-          const truncatedBody =
-            bodyByteLength > maxBodySize
-              ? `${Buffer.from(body)
-                  .subarray(0, maxBodySize - 3)
-                  .toString('utf-8')}...`
-              : body;
-
-          isolationScope.setSDKProcessingMetadata({ normalizedRequest: { data: truncatedBody } });
-        }
-      } catch (error) {
-        if (DEBUG_BUILD) {
-          debug.error(INTEGRATION_NAME, 'Error building captured request body', error);
-        }
-      }
-    });
-  } catch (error) {
-    if (DEBUG_BUILD) {
-      debug.error(INTEGRATION_NAME, 'Error patching request to capture body', error);
-    }
-  }
-}