Migrate from 7.x to 8.x
Learn about migrating from Sentry JavaScript SDK 7.x to 8.x
The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This version is breaking because we removed deprecated APIs, restructured npm package contents, and introduced new dependencies on OpenTelemetry.
Before updating to 8.x
of the SDK, we recommend upgrading to the latest version of 7.x
. To fix most of the deprecations on 7.x
, you can use the @sentry/migr8
codemod to automatically update your SDK usage. @sentry/migr8
requires Node 18+.
npx @sentry/migr8@latest
Our migration tool will let you select which updates to run, and automatically update your code. In some cases, we cannot automatically change code for you. These will be marked with a TODO(sentry)
comment instead. Make sure to review all code changes after running @sentry/migr8
! For more details on the deprecations, see our docs on Deprecations in 7.x. Despite having @sentry/migr8
, we still recommend reading the migration guide, since @sentry/migr8
does not cover all of the changes needed to migrate.
8.x
simplifies Sentry Node SDK initialization and leverages Node.js OpenTelemetry instrumentation for performance monitoring.
We recommend you read through all the Important Changes as they affect all SDK users. The Other Changes linked below only affect users who have more customized instrumentation. There is also a Troubleshooting section for common issues.
We also have a detailed migration guide on GitHub, which has a comprehensive list of all changes alongside the source code of the SDK.
Sentry Node SDK 8.x
supports Node 14.18.0
or higher
If you need to support older versions of Node.js, please use Sentry Node SDK 7.x
.
With 8.x, @sentry/node has been completely overhauled. It is now powered by OpenTelemetry under the hood. You do not need to know or understand what OpenTelemetry is in order to use Sentry. We set up OpenTelemetry under the hood. If you use OpenTelemetry-native APIs to start spans, Sentry will pick up everything automatically.
Here's an example of instrumentating a Connect application with Sentry Node SDK 8.x
:
require('./instrument');
const connect = require('connect');
const Sentry = require('@sentry/node');
const app = connect();
// Add routes etc. here
Sentry.setupConnectErrorHandler(app);
app.listen(3000);
To migrate your Connect app to Sentry Node SDK 8.x
, you need to make the following changes:
- Create an external file called
instrument.js
and move yourSentry.init
call to it.
Due to the way that auto instrumentation works in 8.x
of the Sentry Node SDK, it is required that you initialize Sentry before you require or import any other package. Any package that is required/imported before Sentry is initialized may not be correctly auto-instrumented.
instrument.js
const Sentry = require('@sentry/node');
Sentry.init({
// ...
});
- Remove any performance related integrations
All performance auto-instrumentation will be automatically enabled if the package is found. You do not need to add any integration yourself, and autoDiscoverNodePerformanceMonitoringIntegrations()
has also been removed. This means you can remove all custom requestHandler
and tracingMiddleware
Sentry code.
We now support the following integrations out of the box with 0 configuration:
httpIntegration
: Automatically instruments Node http and https standard librariesnativeNodeFetchIntegration
: Automatically instruments top level fetch and undicikoaIntegration
: Automatically instruments KoagraphqlIntegration
: Automatically instruments GraphQLmongoIntegration
: Automatically instruments MongoDBmongooseIntegration
: Automatically instruments MongoosemysqlIntegration
: Automatically instruments MySQLmysql2Integration
: Automatically instruments MySQL2postgresIntegration
: Automatically instruments PostgreSQLprismaIntegration
: Automatically instruments Prisma
- Require
instrument.js
before any other module in your application
+require('./instrument');
const connect = require('connect');
const Sentry = require('@sentry/node');
const app = connect();
Running with ESM
If you run your application with ESM, you need to import the Sentry Initialization file before importing any other modules. See running Sentry with ESM. If you are unsure how you are running your application, see Installation Methods for more information.
- Add Sentry error handler
Previously you had to use Sentry.Handlers.requestHandler()
, Sentry.Handlers.tracingHandler()
, and Sentry.Handlers.errorHandler()
to add Sentry instrumentation to your Connect app. In 8.x
, you only need to use Sentry.setupConnectErrorHandler(app)
, you can remove all other handlers.
require('./instrument');
const connect = require('connect');
const Sentry = require('@sentry/node');
const app = connect();
-app.use(Sentry.Handlers.requestHandler());
-app.use(Sentry.Handlers.tracingHandler());
// add routes etc. here
-app.use(Sentry.Handlers.errorHandler());
+Sentry.setupConnectErrorHandler(app);
app.listen(3000);
For any non-HTTP scenarios (e.g. websockets or a scheduled job), you'll have to manually ensure request isolation by wrapping the function with Sentry.withIsolationScope()
. Previously we recommended you use Sentry.runWithAsyncContext
for this but that has been removed in 8.x
.
const Sentry = require('@sentry/node');
function myScheduledJob() {
return Sentry.withIsolationScope(async () => {
await doSomething();
await doSomethingElse();
return {status: 'DONE'};
});
}
This way, anything happening inside of this function will be isolated, even if they run concurrently.
The Custom Instrumentation API for Performance Monitoring has been revamped in 8.x
. New methods have been introduced, and startTransaction
and span.startChild
has been removed. See the new Performance Monitoring APIs docs for more information.
If you want to customize the OpenTelemetry setup with your Node.js SDK in 8.x
, see the docs about using OpenTelemetry with 8.x
The enableAnrDetection
and Anr
class exports have been removed the SDK. Instead you can now use the Sentry.anrIntegration
to enable Application Not Responding detection
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
Sentry.anrIntegration({ captureStackTrace: true })
],
});
Previously the SDK exited the process by default, even though additional onUncaughtException
may have been registered, that would have prevented the process from exiting. You could opt out of this behaviour by setting the exitEvenIfOtherHandlersAreRegistered: false
in the onUncaughtExceptionIntegration
options. Up until now the value for this option defaulted to true
.
Going forward, the default value for exitEvenIfOtherHandlersAreRegistered
will be false
, meaning that the SDK will not exit your process when you have registered other onUncaughtException
handlers.
The deepReadDirSync
method has been removed as an export from the SDK. There is no replacement API.
The Sentry tRPC middleware got moved from Sentry.Handlers.trpcMiddleware()
to Sentry.trpcMiddleware()
.
The SDK no longer filters out health check transactions by default. Instead, they are sent to Sentry but still dropped by the Sentry backend by default. You can disable dropping them in your Sentry project settings. If you still want to drop specific transactions within the SDK you can either use the ignoreTransactions
SDK option.
The Hub
has been a very important part of the Sentry SDK API up until now. Hubs were the SDK's "unit of concurrency" to keep track of data across threads and to scope data to certain parts of your code. Because it is overly complicated and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". For now Hub
and getCurrentHub
are still available, but it will be removed in the next major version.
See Deprecate Hub for details on how to replace existing usage of the Hub APIs.
In v7, integrations are classes and can be added as e.g. integrations: [new Sentry.Replay()]
. In v8, integrations will not be classes anymore, but instead functions. Both the use as a class, as well as accessing integrations from the Integrations.XXX
hash, is deprecated in favor of using the new functional integrations. For example, new Integrations.LinkedErrors()
becomes linkedErrorsIntegration()
.
For a list of integrations and their replacements, see the 7.x
deprecation documentation.
The top level Sentry.configureScope
function has been removed. Instead, you should use the Sentry.getCurrentScope()
to access and mutate the current scope.
- Sentry.configureScope((scope) => {
- scope.setTag("key", "value");
- });
+ Sentry.getCurrentScope().setTag("key", "value");
tracingOrigins
is now removed in favor of the tracePropagationTargets
option. The tracePropagationTargets
option should be set in the Sentry.init()
options, or in your custom Client
s option if you create them.
Sentry.init({
dsn: "__DSN__",
integrations: [Sentry.browserTracingIntegration()],
tracePropagationTargets: ["localhost", "example.com"],
});
In 7.x
, you had to enable the metrics aggregator by setting the _experiments
option to { metricsAggregator: true }
. In addition for browser environments you had to add the metricsAggregatorIntegration
to the integrations
array.
// v7 - Server (Node/Deno/Bun)
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
_experiments: {
metricsAggregator: true,
},
});
// v7 - Browser
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [Sentry.metricsAggregatorIntegration()],
});
Sentry.metrics.increment("my_metric");
In 8.x
no additional configuration is needed to use metrics APIs.
// v8
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});
Sentry.metrics.increment("my_metric");
In 7.x
we deprecated the Severity
enum in favor of using the SeverityLevel
type as this helps save bundle size, and this has been removed in 8.x
. You should now use the SeverityLevel
type directly.
- import { Severity } from '@sentry/types';
+ import { SeverityLevel } from '@sentry/types';
- const level = Severity.error;
+ const level: SeverityLevel = "error";
In 8.x
, we are removing the spanStatusfromHttpCode
function in favor of getSpanStatusFromHttpCode
.
- const spanStatus = spanStatusfromHttpCode(200);
+ const spanStatus = getSpanStatusFromHttpCode(200);
Errors with framesToPop
property will have the specified number of frames removed from the top of the stack. This changes compared to the v7 where the property framesToPop
was used to remove top n lines from the stack string.
In 8.x
, we are no longer exporting the Span
class from SDK packages. Internally, this class is now called SentrySpan
, and it is no longer meant to be used by users directly.
The send
method on the Transport
interface now always requires a TransportMakeRequestResponse
to be returned in the promise. This means that the void
return type is no longer allowed.
// v7
interface Transport {
- send(event: Event): Promise<void | TransportMakeRequestResponse>;
+ send(event: Event): Promise<TransportMakeRequestResponse>;
}
The extraErrorDataIntegration
integration now looks at error.cause
by default.
Instead of an transactionContext
being passed to the tracesSampler
callback, the callback will directly receive name
and attributes
going forward. Note that the attributes
are only the attributes at span creation time, and some attributes may only be set later during the span lifecycle (and thus not be available during sampling).
getClient()
now always returns a client if Sentry.init()
was called. For cases where this may be used to check if Sentry was actually initialized, using getClient()
will thus not work anymore. Instead, you should use the new Sentry.isInitialized()
utility to check this.
In 8.x
, we are removing the addGlobalEventProcessor
function in favor of addEventProcessor
.
- Sentry.addGlobalEventProcessor((event) => {
+ Sentry.getGlobalScope().addEventProcessor((event) => {
delete event.extra;
return event;
});
@sentry/integrations
has been removed and will no longer be published. We moved pluggable integrations from their own package (@sentry/integrations
) to @sentry/node
. In addition they are now functions instead of classes.
Integrations that are now exported from @sentry/node
for server-side init:
captureConsoleIntegration
(CaptureConsole
)debugIntegration
(Debug
)extraErrorDataIntegration
(ExtraErrorData
)rewriteFramesIntegration
(RewriteFrames
)sessionTimingIntegration
(SessionTiming
)dedupeIntegration
(Dedupe
) - Note: enabled by default, not pluggable
The Transaction
integration has been removed from @sentry/integrations
. There is no replacement API.
If you are getting errors from within the Sentry SDK that it is trying to access certain functions that are not available, for example "... is not a function", it is possible that there are misaligned versions installed.
The Sentry JavaScript Bundler Plugins (@sentry/webpack-plugin
, @sentry/vite-plugin
, @sentry/esbuild-plugin
, @sentry/rollup-plugin
) used to depend on certain Sentry SDK packages on version 7 wich may clash with version 8 of the SDK.
The recommendation is to upgrade the JavaScript Bundler Plugin packages to at least version 2.14.2
which will no longer include dependencies on v7 of the Sentry JavaScript SDK.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").