feat(node-core): Add node-core SDK (#16745)

This PR adds a new `@sentry/node-core` SDK and refactors `@sentry/node`
to build on it. It provides the core functionality of the Node SDK with
a few key differences

- it ships without any OpenTelemetry core dependencies
- it ships without any OpenTelemetry instrumentation
(`@opentelemetry/instrumentation-X`)
- it does not automatically set up OpenTelemetry
- it widens the OpenTelemetry dependencies version ranges and marks them
as peer dependencies, allowing setup with OpenTelemetry v1 and v2
- preserves all existing `@sentry/node` APIs (minus the OpenTelemetry
instrumentations)

### When to Use Each

This SDK is **not** intended to be used by most users directly
(similarly to `@sentry/core`). It provides core functionality and makes
it possible to be used in setups where OpenTelemetry dependencies that
do not match those we set up in the more opinionated `@sentry/node` SDK.

 Use `@sentry/node-core` when:
  - You already have OpenTelemetry set up
  - You need custom OpenTelemetry configuration
- You want minimal dependencies
  - You need fine-grained control over instrumentation

Use `@sentry/node` when:
- You want automatic setup
  - You're new to OpenTelemetry
  - You want sensible defaults
  - You prefer convenience over control

### Example setup

1. Installation
```bash
npm install @sentry/node-core \
    @opentelemetry/api \
    @opentelemetry/context-async-hooks \
    @opentelemetry/core \
    @opentelemetry/instrumentation \
    @opentelemetry/resources \
    @opentelemetry/sdk-trace-base \
    @opentelemetry/semantic-conventions
```

2. Setup
Sentry should be initialized as early in your app as possible. It is
essential that you call `Sentry.init` before you
require any other modules in your application, otherwise any
auto-instrumentation will **not** work.
You also need to set up OpenTelemetry, if you prefer not to, consider
using the `@sentry/node` SDK instead.

You need to create a file named `instrument.js` that imports and
initializes Sentry:

```js
// CJS Syntax
const { trace, propagation, context } = require('@opentelemetry/api');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const Sentry = require('@sentry/node-core');
const { SentrySpanProcessor, SentryPropagator, SentrySampler } = require('@sentry/opentelemetry');
// ESM Syntax
import { context, propagation, trace } from '@opentelemetry/api';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core';
import { SentrySpanProcessor, SentryPropagator, SentrySampler } from '@sentry/opentelemetry';

const sentryClient = Sentry.init({
  dsn: '__DSN__',
  // ...
});

if (sentryClient) {
  // Note: This could be BasicTracerProvider or any other provider depending on how you want to use the
  // OpenTelemetry SDK
  const provider = new NodeTracerProvider({
    // Ensure the correct subset of traces is sent to Sentry
    // This also ensures trace propagation works as expected
    sampler: new SentrySampler(sentryClient),
    spanProcessors: [
      // Ensure spans are correctly linked & sent to Sentry
      new SentrySpanProcessor(),
      // Add additional processors here
    ],
  });

  trace.setGlobalTracerProvider(provider);
  propagation.setGlobalPropagator(new SentryPropagator());
  context.setGlobalContextManager(new Sentry.SentryContextManager());
}

// Set up the OpenTelemetry logger to use Sentry's logger
Sentry.setupOpenTelemetryLogger();

// validate your setup
Sentry.validateOpenTelemetrySetup();
```

---------

Co-authored-by: Abhijeet Prasad <[email protected]>

Author: andreiborza

.craft.yml

@@ -12,8 +12,6 @@ targets:
   - name: npm
     id: '@sentry/core'
     includeNames: /^sentry-core-\d.*\.tgz$/
-  # This SDK does not exist yet on `develop` but we need an entry
-  # here to be able to publish a pre-release
   - name: npm
     id: '@sentry/node-core'
     includeNames: /^sentry-node-core-\d.*\.tgz$/

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/.gitignore

@@ -0,0 +1 @@
+dist

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/.npmrc

@@ -0,0 +1,2 @@
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "node-core-express-app",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/app.js",
+    "test": "playwright test",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm test"
+  },
+  "dependencies": {
+    "@sentry/node-core": "latest || *",
+    "@sentry/opentelemetry": "latest || *",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^1.30.1",
+    "@opentelemetry/core": "^1.30.1",
+    "@opentelemetry/instrumentation": "^0.57.1",
+    "@opentelemetry/instrumentation-http": "^0.57.1",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-trace-node": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^18.19.1",
+    "express": "^4.21.2",
+    "typescript": "~5.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.50.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils"
+  },
+  "resolutions": {
+    "@types/qs": "6.9.17"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/playwright.config.mjs

@@ -0,0 +1,7 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: `pnpm start`,
+});
+
+export default config;

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/src/app.ts

@@ -0,0 +1,57 @@
+// Import this first!
+import './instrument';
+
+// Now import other modules
+import * as Sentry from '@sentry/node-core';
+import express from 'express';
+
+const app = express();
+const port = 3030;
+
+app.get('/test-transaction', function (req, res) {
+  Sentry.withActiveSpan(null, async () => {
+    Sentry.startSpan({ name: 'test-transaction', op: 'e2e-test' }, () => {
+      Sentry.startSpan({ name: 'test-span' }, () => undefined);
+    });
+
+    await Sentry.flush();
+
+    res.send({
+      transactionIds: global.transactionIds || [],
+    });
+  });
+});
+
+app.get('/test-exception/:id', function (req, _res) {
+  try {
+    throw new Error(`This is an exception with id ${req.params.id}`);
+  } catch (e) {
+    Sentry.captureException(e);
+    throw e;
+  }
+});
+
+app.get('/test-local-variables-caught', function (req, res) {
+  const randomVariableToRecord = Math.random();
+
+  let exceptionId: string;
+  try {
+    throw new Error('Local Variable Error');
+  } catch (e) {
+    exceptionId = Sentry.captureException(e);
+  }
+
+  res.send({ exceptionId, randomVariableToRecord });
+});
+
+// @ts-ignore
+app.use(function onError(err, req, res, next) {
+  // The error id is attached to `res.sentry` to be returned
+  // and optionally displayed to the user for support.
+  res.statusCode = 500;
+  res.end(res.sentry + '\n');
+});
+
+app.listen(port, () => {
+  console.log(`Example app listening on port ${port}`);
+});

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/src/instrument.ts

@@ -0,0 +1,46 @@
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import * as Sentry from '@sentry/node-core';
+import { SentrySpanProcessor, SentryPropagator, SentrySampler } from '@sentry/opentelemetry';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+
+declare global {
+  namespace globalThis {
+    var transactionIds: string[];
+  }
+}
+
+const sentryClient = Sentry.init({
+  environment: 'qa', // dynamic sampling bias to keep transactions
+  dsn: process.env.E2E_TEST_DSN,
+  includeLocalVariables: true,
+  debug: !!process.env.DEBUG,
+  tunnel: `http://localhost:3031/`, // proxy server
+  tracesSampleRate: 1,
+  openTelemetryInstrumentations: [new HttpInstrumentation()],
+});
+
+const provider = new NodeTracerProvider({
+  sampler: sentryClient ? new SentrySampler(sentryClient) : undefined,
+  spanProcessors: [new SentrySpanProcessor()],
+});
+
+provider.register({
+  propagator: new SentryPropagator(),
+  contextManager: new Sentry.SentryContextManager(),
+});
+
+Sentry.validateOpenTelemetrySetup();
+
+Sentry.addEventProcessor(event => {
+  global.transactionIds = global.transactionIds || [];
+
+  if (event.type === 'transaction') {
+    const eventId = event.event_id;
+
+    if (eventId) {
+      global.transactionIds.push(eventId);
+    }
+  }
+
+  return event;
+});

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import { startEventProxyServer } from '@sentry-internal/test-utils';
+
+startEventProxyServer({
+  port: 3031,
+  proxyServerName: 'node-core-express-otel-v1',
+});

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/tests/errors.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from '@playwright/test';
+import { waitForError } from '@sentry-internal/test-utils';
+
+test('Sends correct error event', async ({ baseURL }) => {
+  const errorEventPromise = waitForError('node-core-express-otel-v1', event => {
+    return !event.type && event.exception?.values?.[0]?.value === 'This is an exception with id 123';
+  });
+
+  await fetch(`${baseURL}/test-exception/123`);
+
+  const errorEvent = await errorEventPromise;
+
+  expect(errorEvent.exception?.values).toHaveLength(1);
+  expect(errorEvent.exception?.values?.[0]?.value).toBe('This is an exception with id 123');
+
+  expect(errorEvent.request).toEqual({
+    method: 'GET',
+    cookies: {},
+    headers: expect.any(Object),
+    url: 'http://localhost:3030/test-exception/123',
+  });
+
+  expect(errorEvent.transaction).toEqual('GET /test-exception/123');
+
+  expect(errorEvent.contexts?.trace).toEqual({
+    trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+    span_id: expect.stringMatching(/[a-f0-9]{16}/),
+  });
+});
+
+test('Should record caught exceptions with local variable', async ({ baseURL }) => {
+  const errorEventPromise = waitForError('node-core-express-otel-v1', event => {
+    return event.transaction === 'GET /test-local-variables-caught';
+  });
+
+  await fetch(`${baseURL}/test-local-variables-caught`);
+
+  const errorEvent = await errorEventPromise;
+
+  const frames = errorEvent.exception?.values?.[0].stacktrace?.frames;
+  expect(frames?.[frames.length - 1].vars?.randomVariableToRecord).toBeDefined();
+});

dev-packages/e2e-tests/test-applications/node-core-express-otel-v1/tests/transactions.test.ts

@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+
+test('Sends an API route transaction', async ({ baseURL }) => {
+  const pageloadTransactionEventPromise = waitForTransaction('node-core-express-otel-v1', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      transactionEvent?.transaction === 'GET /test-transaction'
+    );
+  });
+
+  await fetch(`${baseURL}/test-transaction`);
+
+  const transactionEvent = await pageloadTransactionEventPromise;
+
+  expect(transactionEvent.contexts?.trace).toEqual({
+    data: {
+      'sentry.source': 'url',
+      'sentry.origin': 'manual',
+      'sentry.op': 'http.server',
+      'sentry.sample_rate': 1,
+      url: 'http://localhost:3030/test-transaction',
+      'otel.kind': 'SERVER',
+      'http.response.status_code': 200,
+      'http.url': 'http://localhost:3030/test-transaction',
+      'http.host': 'localhost:3030',
+      'net.host.name': 'localhost',
+      'http.method': 'GET',
+      'http.scheme': 'http',
+      'http.target': '/test-transaction',
+      'http.user_agent': 'node',
+      'http.flavor': '1.1',
+      'net.transport': 'ip_tcp',
+      'net.host.ip': expect.any(String),
+      'net.host.port': expect.any(Number),
+      'net.peer.ip': expect.any(String),
+      'net.peer.port': expect.any(Number),
+      'http.status_code': 200,
+      'http.status_text': 'OK',
+    },
+    op: 'http.server',
+    span_id: expect.stringMatching(/[a-f0-9]{16}/),
+    status: 'ok',
+    trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+    origin: 'manual',
+  });
+
+  expect(transactionEvent.contexts?.response).toEqual({
+    status_code: 200,
+  });
+
+  expect(transactionEvent).toEqual(
+    expect.objectContaining({
+      transaction: 'GET /test-transaction',
+      type: 'transaction',
+      transaction_info: {
+        source: 'url',
+      },
+    }),
+  );
+});
+
+test('Sends an API route transaction for an errored route', async ({ baseURL }) => {
+  const transactionEventPromise = waitForTransaction('node-core-express-otel-v1', transactionEvent => {
+    return (
+      transactionEvent.contexts?.trace?.op === 'http.server' &&
+      transactionEvent.transaction === 'GET /test-exception/777' &&
+      transactionEvent.request?.url === 'http://localhost:3030/test-exception/777'
+    );
+  });
+
+  await fetch(`${baseURL}/test-exception/777`);
+
+  const transactionEvent = await transactionEventPromise;
+
+  expect(transactionEvent.contexts?.trace?.op).toEqual('http.server');
+  expect(transactionEvent.transaction).toEqual('GET /test-exception/777');
+  expect(transactionEvent.contexts?.trace?.status).toEqual('internal_error');
+  expect(transactionEvent.contexts?.trace?.data?.['http.status_code']).toEqual(500);
+});