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
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:
- Initialize Sentry, e.g.
@sentry/node
! - Call
setupEventContextTrace(client)
- Add
SentrySampler
as sampler - Add
SentrySpanProcessor
as span processor - Add a context manager wrapped via
wrapContextManagerClass
- Add
SentryPropagator
as propagator - 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);
provider.register({
propagator: new SentryPropagator(),
contextManager: new SentryContextManager(),
});
setOpenTelemetryContextAsyncContextStrategy();
}
A full setup example can be found in
node-experimental.
Links
8.3.0
Important Changes
- Better Node Framework Span Data
This release improves data quality of spans emitted by Express, Fastify, Connect, Koa, Nest.js and Hapi.
-
feat(node): Ensure connect spans have better data (#12130)
-
feat(node): Ensure express spans have better data (#12107)
-
feat(node): Ensure fastify spans have better data (#12106)
-
feat(node): Ensure hapi spans have better data (#12140)
-
feat(node): Ensure koa spans have better data (#12108)
-
feat(node): Ensure Nest.js spans have better data (#12139)
-
feat(deps): Bump @opentelemetry/instrumentation-express from 0.38.0 to 0.39.0 (#12079)
-
feat(node): No-code init via --import=@sentry/node/init
(#11999)
When using Sentry in ESM mode, you can now use Sentry without manually calling init like this:
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 node --import=@sentry/node/init app.mjs
When using CommonJS, you can do:
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 node --require=@sentry/node/init app.js
Other Changes
- chore: Align and update MIT license dates (#12143)
- chore: Resolve or postpone a random assortment of TODOs (#11977)
- doc(migration): Add entry for runWithAsyncContext (#12153)
- docs: Add migration docs to point out that default import does not work (#12100)
- docs(sveltekit): process.env.SENTRY_AUTH_TOKEN (#12118)
- feat(browser): Ensure
browserProfilingIntegration
is published to CDN (#12158) - feat(google-cloud): Expose ESM build (#12149)
- feat(nextjs): Ignore Prisma critical dependency warnings (#12144)
- feat(node): Add app.free_memory info to events (#12150)
- feat(node): Do not create GraphQL resolver spans by default (#12097)
- feat(node): Use
node:
prefix for node built-ins (#11895) - feat(replay): Use unwrapped
setTimeout
to avoid e.g. angular change detection (#11924) - fix(core): Add dsn to span envelope header (#12096)
- fix(feedback): Improve feedback border color in dark-mode, and prevent auto-dark mode when a theme is picked (#12126)
- fix(feedback): Set optionOverrides to be optional in TS definition (#12125)
- fix(nextjs): Don't put
undefined
values in props (#12131) - fix(nextjs): Fix legacy configuration method detection for emitting warning (#12136)
- fix(node): Ensure fetch/http breadcrumbs are created correctly (#12137)
- fix(node): Update
@prisma/instrumentation
from 5.13.0 to 5.14.0 (#12081) - ref(node): Add log for running in ESM/CommonJS mode (#12134)
- ref(node): Handle failing hook registration gracefully (#12135)
- ref(node): Only show instrumentation warning when tracing is enabled (#12141)
Work in this release contributed by @pboling. Thank you for your contribution!