@sentry/opentelemetry

Official Sentry SDK for OpenTelemetry

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

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

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.18.0

Important Changes

• ref: Deprecate enableTracing (12897)

The enableTracing option has been deprecated and will be removed in the next major version. We recommend removing it in favor of the tracesSampleRate and tracesSampler options. If you want to enable performance monitoring, please set the tracesSampleRate to a sample rate of your choice, or provide a sampling function as tracesSampler option instead. If you want to disable performance monitoring, remove the tracesSampler and tracesSampleRate options.

Other Changes

• feat(node): Expose exclude and include options for ESM loader (#12910)
• feat(browser): Add user agent to INP standalone span attributes (#12896)
• feat(nextjs): Add experimental_captureRequestError for onRequestError hook (#12885)
• feat(replay): Bump rrweb to 2.25.0 (#12478)
• feat(tracing): Add long animation frame tracing (#12646)
• fix: Cleanup hooks when they are not used anymore (#12852)
• fix(angular): Guard ErrorEvent check in ErrorHandler to avoid throwing in Node environments (#12892)
• fix(inp): Ensure INP spans have correct transaction (#12871)
• fix(nestjs): Do not make SentryTraced() decorated functions async (#12879)
• fix(nextjs): Support automatic instrumentation for app directory with custom page extensions (#12858)
• fix(node): Ensure correct URL is passed to ignoreIncomingRequests callback (#12929)
• fix(otel): Do not add otel.kind: INTERNAL attribute (#12841)
• fix(solidstart): Set proper sentry origin for solid router integration when used in solidstart sdk (#12919)
• fix(sveltekit): Add Vite peer dep for proper type resolution (#12926)
• fix(tracing): Ensure you can pass null as parentSpan in startSpan* (#12928)
• ref(core): Small bundle size improvement (#12830)

Work in this release was contributed by @GitSquared, @ziyadkhalil and @mcous. Thank you for your contributions!