Official Sentry SDK for OpenTelemetry
![npm dt](https://img.shields.io/npm/dt/@sentry/opentelemetry.svg)
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.16.0
Important Changes
- feat(nextjs): Use spans generated by Next.js for App Router (#12729)
Previously, the @sentry/nextjs
SDK automatically recorded spans in the form of transactions for each of your top-level
server components (pages, layouts, ...). This approach had a few drawbacks, the main ones being that traces didn't have
a root span, and more importantly, if you had data stream to the client, its duration was not captured because the
server component spans had finished before the data could finish streaming.
With this release, we will capture the duration of App Router requests in their entirety as a single transaction with
server component spans being descendants of that transaction. This means you will get more data that is also more
accurate. Note that this does not apply to the Edge runtime. For the Edge runtime, the SDK will emit transactions as it
has before.
Generally speaking, this change means that you will see less transactions and more spans in Sentry. You will no
longer receive server component transactions like Page Server Component (/path/to/route)
(unless using the Edge
runtime), and you will instead receive transactions for your App Router SSR requests that look like
GET /path/to/route
.
If you are on Sentry SaaS, this may have an effect on your quota consumption: Less transactions, more spans.
- - feat(nestjs): Add nest cron monitoring support (#12781)
The @sentry/nestjs
SDK now includes a @SentryCron
decorator that can be used to augment the native NestJS @Cron
decorator to send check-ins to Sentry before and after each cron job run:
import { Cron } from '@nestjs/schedule';
import { SentryCron, MonitorConfig } from '@sentry/nestjs';
import type { MonitorConfig } from '@sentry/types';
const monitorConfig: MonitorConfig = {
schedule: {
type: 'crontab',
value: '* * * * *',
},
checkinMargin: 2, // In minutes. Optional.
maxRuntime: 10, // In minutes. Optional.
timezone: 'America/Los_Angeles', // Optional.
};
export class MyCronService {
@Cron('* * * * *')
@SentryCron('my-monitor-slug', monitorConfig)
handleCron() {
// Your cron job logic here
}
}
Other Changes
- feat(node): Allow to pass instrumentation config to
httpIntegration
(#12761) - feat(nuxt): Add server error hook (#12796)
- feat(nuxt): Inject sentry config with Nuxt
addPluginTemplate
(#12760) - fix: Apply stack frame metadata before event processors (#12799)
- fix(feedback): Add missing
h
import in ScreenshotEditor
(#12784) - fix(node): Ensure
autoSessionTracking
is enabled by default (#12790) - ref(feedback): Let CropCorner inherit the existing h prop (#12814)
- ref(otel): Ensure we never swallow args for ContextManager (#12798)