Improved OpenTelemetry & Node Support in JavaScript v8 SDK

As first announced during Sentry Launch Week, we have been working on shipping a major release of our JavaScript SDKs. This update makes getting started with Sentry JavaScript SDKs (even more) straightforward. This release broadens the number of frameworks and libraries where we provide automatic instrumentation, meaning you can access telemetry data in Sentry on day one, without configuration. But if you do want to customize your Sentry setup, with expanded support for OpenTelemetry (OTel), we reduced the required custom configuration from 85 lines of code to less than 10.

Tracing powered by OpenTelemetry

OpenTelemetry as a standard and maintainer provides powerful tools, but it is on us to use those tools and the data collected to provide you with insights. The new trace view in Sentry, for example, is just one of the latest feature improvements which will now also benefit from V8’s improved Node.js support. Incorporating OTel into our Node SDK also will collect more detailed span data than in previous versions. Take a look below at the span details recorded in Sentry’s very own Changelog built with Next.js and Prisma 4.

Auto instrumentation for more Node frameworks and libraries

OTel’s Node SDK in particular supports many more Node frameworks for automatic performance instrumentation than Sentry’s previous Node SDK. By replacing parts of our Node SDK with OTel, we’ve expanded support for the Node.js frameworks and libraries Sentry supports by default. This means if your Node project has any of the frameworks or libraries below, the Sentry Node SDK will automatically detect and configure them.

Frameworks

• Express (improved)
• Connect (improved)
• Nest.js (new)
• Koa (improved)
• Fastify (new)
• Hapi (new)

Libraries

• pg (Postgres)
• pg-native (Postgres)
• mongodb (Mongo)
• mongoose (Mongo)
• mysql2 (MySQL)
• mysql (MySQL)
• graphql (GraphQL)
• apollo-server-core (Apollo)
• @nestjs/graphql (Apollo)
• Prisma ORM (v4)

For example, we have supported Express for a long time, and there have been varying degrees of support for the other frameworks as well. However, with the latest major release, we provide support through one SDK (our Node SDK) to automatically detect which frameworks you are using, and collect telemetry data to send to Sentry. We recommend creating a separate file sentry.js that you import first thing in your app:

instrument.js:

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

server.js:

require(‘./instrument.js’); // import instrument.js first
const Fastify = require("fastify");
const app = new Fastify();

Sentry.setupFastifyErrorHandler(app);

After that, all of your error and performance data is captured and connected to your traces in Sentry.

Simple Tracing API

Knowing exactly which spans to create is not always obvious, and to put it simply, that’s not your job, it’s ours. For browser and Node.js frameworks alike, our goal is to deliver the best auto-instrumentation possible. This means that when you add Sentry to your applications, you can get meaningful data and insights with little to no configuration.

However, there are cases where more nuanced applications require custom instrumentation. In these situations, we want to ensure you have the tools available to track those paths through your stack, and that those tools are easy to understand. So while we looked to provide better support to the Node ecosystem with this latest major, we also overhauled and simplified our Tracing API.

The new API focuses on spans, a simple unit of measure that you start and stop, and then chain together with other meaningful events in your application. As shown in the interactive demo above, the spans within a trace tell where operations start, stop, succeed, or fail. See the example below for how to customize spans sent to Sentry.

const result = Sentry.startSpan({ name: "Important Function" }, () => {
  return expensiveFunction();
});

const result2 = await Sentry.startSpan(
  { name: "Important Function" },
  async () => {
    const res = await Sentry.startSpan({ name: "Child Span" }, () => {
      return expensiveAsyncFunction();
    });

    return updateRes(res);
  }
);

const result3 = Sentry.startSpan({ name: "Important Function" }, (span) => {
  // You can access the span to add attributes or set specific status.
  // The span may be undefined if the span was not sampled or if performance monitoring is disabled.
  span?.setAttribute("foo", "bar");
  return expensiveFunction();
});

const result4 = Sentry.startSpan(
  {
    name: "Important Function",
    // You can also pass attributes directly to `startSpan`:
    attributes: {
      foo: "bar",
      count: 1,
    },
  },
  () => {
    return expensiveFunction();
  }
);

These APIs are now also friendlier if you are already familiar with OpenTelemetry. Learn more about the new API here.

Ready to upgrade?

JavaScript v8 makes setting up Sentry in your app simpler, while also improving the level of detail you get from our tracing data. Ultimately, it will make digging into your data and debugging issues easier. If you want to learn more about changes specific to the JavaScript framework you’re using, check out our migration docs here. You’ll find links to migration documentation and tools, along with more detailed insights into what we changed and added with the latest major release.

While software bugs are Sentry’s thing, we still write them. If you come across any problems while upgrading your SDK, please open a GitHub Issue or reach out on Discord.