Official Sentry SDK for Node (EXPERIMENTAL)

This is a WIP, proof of concept implementation of a Node SDK that uses OpenTelemetry for performance instrumentation under the hood.

THIS MAY/WILL BREAK IN MANY UNEXPECTED WAYS. We may remove, add, change any of the integrations, add/remove any exports, etc. This package is NOT READY TO USE IN ANY FORM OF PRODUCTION ENVIRONMENT!

This SDK is considered experimental and in an alpha state. It may experience breaking changes, and may be discontinued at any time. Please reach out on GitHub if you have any feedback/concerns.

Installation

npm install @sentry/node-experimental

# Or yarn
yarn add @sentry/node-experimental

Usage

// CJS Syntax
const Sentry = require('@sentry/node-experimental');
// ESM Syntax
import * as Sentry from '@sentry/node-experimental';

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

Note that it is necessary to initialize Sentry before you import any package that may be instrumented by us.

Status of this Experiment

Currently, this SDK:

• Will capture errors (same as @sentry/node)
• Auto-instrument for performance - see below for which performance integrations are available.
• Provide some manual instrumentation APIs
• Sync OpenTelemetry Context with our Sentry Hub/Scope

Manual Instrumentation

You can manual instrument using the following APIs:

const Sentry = require('@sentry/node-experimental');

Sentry.startSpan({ description: 'outer' }, function (span) {
  span.setData(customData);
  doSomethingSlow();
  Sentry.startSpan({ description: 'inner' }, function() {
    // inner span is a child of outer span
    doSomethingVerySlow();
    // inner span is auto-ended when this callback ends
  });
  // outer span is auto-ended when this callback ends
});

You can also create spans without marking them as the active span. Note that for most scenarios, we recommend the startSpan syntax.

const Sentry = require('@sentry/node-experimental');

// This will _not_ be put on the scope/set as active, so no other spans will be attached to it
const span = Sentry.startInactiveSpan({ description: 'non-active span' });

doSomethingSlow();

span.end();

Finally you can also get the currently active span, if you need to do more with it:

const Sentry = require('@sentry/node-experimental');
const span = Sentry.getActiveSpan();

Async Context

We leverage the OpenTelemetry context forking in order to ensure isolation of parallel requests. This means that as long as you are using an OpenTelemetry instrumentation for your framework of choice (currently: Express or Fastify), you do not need to setup any requestHandler or similar.

ESM Support

Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (require) applications.

There is experimental support for running OpenTelemetry with ESM ("type": "module"):

node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js

You'll need to install @opentelemetry/instrumentation in your app to ensure this works.

See OpenTelemetry Instrumentation Docs for details on this - but note that this is a) experimental, and b) does not work with all integrations.

Available (Performance) Integrations

• Http
• Express
• Fastify
• Nest
• Mysql
• Mysql2
• GraphQL
• Mongo
• Mongoose
• Postgres
• Prisma

All of these are auto-discovered, you don't need to configure anything for performance. You still need to register middlewares etc. for error capturing. Other, non-performance integrations from @sentry/node are also available (except for Undici).

Links

• Official SDK Docs