@sentry/opentelemetry

Official Sentry SDK for OpenTelemetry

This package allows you to send your OpenTelemetry trace data to Sentry via OpenTelemetry SpanProcessors.

If you are using @sentry/node, OpenTelemetry support is included out of the box. This package is only necessary if you are setting up OpenTelemetry support for Sentry yourself.

Installation

npm install @sentry/opentelemetry

# Or yarn
yarn add @sentry/opentelemetry

Note that @sentry/opentelemetry depends on the following peer dependencies:

• @opentelemetry/api version 1.0.0 or greater
• @opentelemetry/core version 1.0.0 or greater
• @opentelemetry/semantic-conventions version 1.0.0 or greater
• @opentelemetry/sdk-trace-base version 1.0.0 or greater, or a package that implements that, like @opentelemetry/sdk-node.

Usage

This package exposes a few building blocks you can add to your OpenTelemetry setup in order to capture OpenTelemetry traces to Sentry.

This is how you can use this in your app:

1. Initialize Sentry, e.g. @sentry/node!
2. Call setupEventContextTrace(client)
3. Add SentrySampler as sampler
4. Add SentrySpanProcessor as span processor
5. Add a context manager wrapped via wrapContextManagerClass
6. Add SentryPropagator as propagator
7. Setup OTEL-powered async context strategy for Sentry via setOpenTelemetryContextAsyncContextStrategy()

For example, you could set this up as follows:

import * as Sentry from '@sentry/node';
import {
  SentryPropagator,
  SentrySampler,
  SentrySpanProcessor,
  setupEventContextTrace,
  wrapContextManagerClass,
  setOpenTelemetryContextAsyncContextStrategy,
} from '@sentry/opentelemetry';
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';

function setupSentry() {
  Sentry.init({
    dsn: 'xxx',
  });

  const client = Sentry.getClient();
  setupEventContextTrace(client);

  const provider = new BasicTracerProvider({
    sampler: new SentrySampler(client),
  });
  provider.addSpanProcessor(new SentrySpanProcessor());

  const SentryContextManager = wrapContextManagerClass(AsyncLocalStorageContextManager);

  // Initialize the provider
  provider.register({
    propagator: new SentryPropagator(),
    contextManager: new SentryContextManager(),
  });

  setOpenTelemetryContextAsyncContextStrategy();
}

A full setup example can be found in node-experimental.

Links

• Official SDK Docs

Changelog

8.36.0

Important Changes

• feat(nextjs/vercel-edge/cloudflare): Switch to OTEL for performance monitoring (#13889)

With this release, the Sentry Next.js, and Cloudflare SDKs will now capture performance data based on OpenTelemetry. Some exceptions apply in cases where Next.js captures inaccurate data itself.

NOTE: You may experience minor differences in transaction names in Sentry. Most importantly transactions for serverside pages router invocations will now be named GET /[param]/my/route instead of /[param]/my/route. This means that those transactions are now better aligned with the OpenTelemetry semantic conventions.

Other Changes

• deps: Bump bundler plugins and CLI to 2.22.6 and 2.37.0 respectively (#14050)
• feat(deps): bump @opentelemetry/instrumentation-aws-sdk from 0.44.0 to 0.45.0 (#14099)
• feat(deps): bump @opentelemetry/instrumentation-connect from 0.39.0 to 0.40.0 (#14101)
• feat(deps): bump @opentelemetry/instrumentation-express from 0.43.0 to 0.44.0 (#14102)
• feat(deps): bump @opentelemetry/instrumentation-fs from 0.15.0 to 0.16.0 (#14098)
• feat(deps): bump @opentelemetry/instrumentation-kafkajs from 0.3.0 to 0.4.0 (#14100)
• feat(nextjs): Add method and url to route handler request data (#14084)
• feat(node): Add breadcrumbs for child_process and worker_thread (#13896)
• fix(core): Ensure standalone spans are not sent if SDK is disabled (#14088)
• fix(nextjs): Await flush in api handlers (#14023)
• fix(nextjs): Don't leak webpack types into exports (#14116)
• fix(nextjs): Fix matching logic for file convention type for root level components (#14038)
• fix(nextjs): Respect directives in value injection loader (#14083)
• fix(nuxt): Only wrap .mjs entry files in rollup (#14060)
• fix(nuxt): Re-export all exported bindings (#14086)
• fix(nuxt): Server-side setup in readme (#14049)
• fix(profiling-node): Always warn when running on incompatible major version of Node.js (#14043)
• fix(replay): Fix onError callback (#14002)
• perf(otel): Only calculate current timestamp once (#14094)
• test(browser-integration): Add sentry DSN route handler by default (#14095)