@sentry/node-core

Official Sentry SDK for Node-Core

[!CAUTION] This package is in alpha state and may be subject to breaking changes.

Unlike the @sentry/node SDK, this SDK comes with no OpenTelemetry auto-instrumentation out of the box. It requires the following OpenTelemetry dependencies and supports both v1 and v2 of OpenTelemetry:

• @opentelemetry/api
• @opentelemetry/context-async-hooks
• @opentelemetry/core
• @opentelemetry/instrumentation
• @opentelemetry/resources
• @opentelemetry/sdk-trace-base
• @opentelemetry/semantic-conventions.

Installation

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

# Or yarn
yarn add @sentry/node-core @sentry/opentelemetry @opentelemetry/api @opentelemetry/core @opentelemetry/context-async-hooks @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/sdk-trace-base @opentelemetry/semantic-conventions

Usage

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 have to set up OpenTelemetry, if you prefer not to, consider using the @sentry/node SDK instead. Without setting up OpenTelemetry, you only get basic error tracking out of the box without proper scope isolation.

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

You need to require or import the instrument.js file before importing any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application:

// Import this first!
import './instrument';

// Now import other modules
import http from 'http';

// Your application code goes here

ESM Support

When running your application in ESM mode, you should use the Node.js --import command line option to ensure that Sentry is loaded before the application code is evaluated.

Adjust the Node.js call for your application to use the --import parameter and point it at instrument.js, which contains your Sentry.init() code:

# Note: This is only available for Node v18.19.0 onwards.
node --import ./instrument.mjs app.mjs

If it is not possible for you to pass the --import flag to the Node.js binary, you can alternatively use the NODE_OPTIONS environment variable as follows:

NODE_OPTIONS="--import ./instrument.mjs" npm run start

Links

• Official SDK Docs

Changelog

9.36.0

Important Changes

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

This release adds a new SDK @sentry/node-core which ships without any OpenTelemetry instrumententation out of the box. All OpenTelemetry dependencies are peer dependencies and OpenTelemetry has to be set up manually.

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 an automatic setup
• You're new to OpenTelemetry
• You want sensible defaults
• You prefer convenience over control

• feat(node): Deprecate ANR integration (#16832)

The ANR integration has been deprecated and will be removed in future versions. Use eventLoopBlockIntegration from @sentry/node-native instead.

• feat(replay): Add _experiments.ignoreMutations option (#16816)

This replay option allows to configure a selector list of elements to not capture mutations for.

Sentry.replayIntegration({
  _experiments: {
    ignoreMutations: ['.dragging'],
  },
});

Other changes

• feat(deps): bump @prisma/instrumentation from 6.10.1 to 6.11.1 (#16833)
• feat(nextjs): Add flag for suppressing router transition warning (#16823)
• feat(nextjs): Automatically skip middleware requests for tunnel route (#16812)
• feat(replay): Export compression worker from @sentry/replay-internal (#16794)
• fix(browser): Avoid 4xx response for succesful diagnoseSdkConnectivity request (#16840)
• fix(browser): Guard against undefined nextHopProtocol (#16806)
• fix(cloudflare): calculate retries not attempts (#16834)
• fix(nuxt): Parametrize routes on the server-side (#16785)
• fix(vue): Make pageload span handling more reliable (#16799)

Work in this release was contributed by @Spice-King and @stayallive. Thank you for your contributions!