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

andreiborza · 2025-06-26T09:40:03Z

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

Installation

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

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:

// 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();

github-actions · 2025-06-26T10:02:16Z

size-limit report 📦

8000

Path	Size	% Change	Change
@sentry/browser	23.99 kB	-	-
@sentry/browser - with treeshaking flags	23.76 kB	-	-
@sentry/browser (incl. Tracing)	39.59 kB	-	-
@sentry/browser (incl. Tracing, Replay)	77.69 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	70.78 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	82.45 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	94.57 kB	-	-
@sentry/browser (incl. Feedback)	40.75 kB	-	-
@sentry/browser (incl. sendFeedback)	28.7 kB	-	-
@sentry/browser (incl. FeedbackAsync)	33.59 kB	-	-
@sentry/react	25.76 kB	-	-
@sentry/react (incl. Tracing)	41.58 kB	-	-
@sentry/vue	28.37 kB	-	-
@sentry/vue (incl. Tracing)	41.4 kB	-	-
@sentry/svelte	24.01 kB	-	-
CDN Bundle	25.5 kB	-	-
CDN Bundle (incl. Tracing)	39.6 kB	-	-
CDN Bundle (incl. Tracing, Replay)	75.5 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	80.96 kB	-	-
CDN Bundle - uncompressed	74.5 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	117.63 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	231.68 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	244.5 kB	-	-
@sentry/nextjs (client)	43.22 kB	-	-
@sentry/sveltekit (client)	40.04 kB	-	-
@sentry/node	161.84 kB	-0.12%	-180 B 🔽
@sentry/node - without tracing	98.8 kB	+0.17%	+160 B 🔺
@sentry/aws-serverless	124.62 kB	+0.18%	+223 B 🔺

View base workflow run

andreiborza · 2025-07-03T07:22:43Z

dev-packages/node-core-integration-tests/suites/anr/stop-and-start.js

+
+setTimeout(() => {
+  process.exit();
+}, 20000);


@timfish I had to increase the timeout here to get these to pass. Could you have a look why that might be?

I'm wondering if the OTel init outside of Sentry.init has something to do with this.

Seems unlikely this has anything to do with otel because the anr events are sent from another thread without the full SDK running. I wouldn't worry too much about this change!

timfish · 2025-07-03T13:14:20Z

Can you use @sentry/node-core without any otel dependencies and if so, what features will not work?

packages/node-core/LICENSE

AbhiPrasad · 2025-07-02T22:39:49Z

packages/node-core/README.md

+
+## Usage
+
+Sentry should be initialized as early in your app as possible. It is essential that you call `Sentry.init` before you


Should we emphasize that OTEL setup is required? What happens if users don't set up OTEL?

I updated the README. If users don't setup OTel they basically get only basic error logging, no scope isolation.

follow up: Maybe we can get to a place where we can have basic scope isolation for errors without otel 🤔 but that's a bigger topic 😅

AbhiPrasad · 2025-07-03T13:54:40Z

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

why isn't this file also just moved from @sentry/node?

The one in @sentry/node uses @opentelemetry/instrumentation-http, while the one in node-core does not.

AbhiPrasad · 2025-07-03T13:59:05Z

packages/node/src/sdk/index.ts

-  ];
+  const nodeCoreIntegrations = getNodeCoreDefaultIntegrations();
+
+  // Filter out the node-core HTTP and NodeFetch integrations and replace them with Node SDK's composite versions


I wonder if we'll have issues where people import node-core and use those integrations with the node sdk. Maybe we need a way to detect those scenarios?

Could be an issue, but most people won't use @sentry/node-core. Same as most people don't use @sentry/core. Not sure we need to guard against this at this point?

Do you have some specific approach in mind?

we already have a similar thing for e.g. browserTracingIntegration where many SDKs export a different implementation of this than the browser one 🤔 so I think this should be fine...?

Co-authored-by: Abhijeet Prasad <aprasad@sentry.io>

…/v2 interop

andreiborza force-pushed the ab/node-core branch from cf84c54 to 9fd7337 Compare June 26, 2025 09:53

andreiborza force-pushed the ab/node-core branch 4 times, most recently from 610c5cc to 8b31e19 Compare June 27, 2025 13:34

This comment was marked as outdated.

Sign in to view

andreiborza force-pushed the ab/node-core branch 5 times, most recently from 3d127cf to b97edd4 Compare July 2, 2025 21:32

andreiborza marked this pull request as ready for review July 2, 2025 21:59

andreiborza requested review from timfish, mydea, AbhiPrasad and chargome July 2, 2025 22:00

andreiborza commented Jul 3, 2025

View reviewed changes

AbhiPrasad reviewed Jul 3, 2025

View reviewed changes

This comment was marked as outdated.

Sign in to view

andreiborza added 7 commits July 4, 2025 01:03

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

44e9bc4

Create node-core SDK and base node SDK on it

2b139bb

Add node-core integration tests

6e2cba1

Add node-core to Verdaccio config

73d6a22

Add node-core e2e test app with OTel v1 deps

c21c76d

Add node-core e2e test app with OTel v2 deps

d47f24d

Add node-core to .craft.yml

7ba1b45

andreiborza and others added 5 commits July 4, 2025 01:03

Update packages/node-core/LICENSE

ed22c68

Co-authored-by: Abhijeet Prasad <aprasad@sentry.io>

Export isWrapped from @opentelemetry/instrumentation to ensure v1…

bf6a450

…/v2 interop

Use SDK_VERSION for http and fetch instrumentation version

98a37f1

Bump @opentelemetry/instrumentation version to latest

3fd78a6

Export setupOpenTelemetryLoggerfrom node-core and use in node

9254023

andreiborza force-pushed the ab/node-core branch from 7fbca88 to 9254023 Compare July 3, 2025 23:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!


		## Usage

		Sentry should be initialized as early in your app as possible. It is essential that you call `Sentry.init` before you

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

Uh oh!

When to Use Each

Example setup

Uh oh!

Uh oh!

size-limit report 📦

Uh oh!

This comment was marked as outdated.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!