Deprecations in 7.x

Learn about deprecations in Sentry JavaScript SDK 7.x and how to address them

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

Copied
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!

The following is a list of the most important deprecations that happened in 7.x. Please see the detailed migration docs on GitHub for a comprehensive list of all deprecations.

Deprecation introduced in 7.100.0.

In v7, integrations are classes and can be added as e.g. integrations: [new Sentry.Integrations.ContextLines()]. 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().

The following list shows how integrations should be migrated:

OldNew
new BrowserTracing()browserTracingIntegration()
new InboundFilters()inboundFiltersIntegration()
new FunctionToString()functionToStringIntegration()
new LinkedErrors()linkedErrorsIntegration()
new ModuleMetadata()moduleMetadataIntegration()
new Replay()replayIntegration()
new ReplayCanvas()replayCanvasIntegration()
new Feedback()feedbackIntegration()
new CaptureConsole()captureConsoleIntegration()
new Debug()debugIntegration()
new Dedupe()dedupeIntegration()
new ExtraErrorData()extraErrorDataIntegration()
new ReportingObserver()reportingObserverIntegration()
new RewriteFrames()rewriteFramesIntegration()
new SessionTiming()sessionTimingIntegration()
new HttpClient()httpClientIntegration()
new ContextLines()contextLinesIntegration()
new Breadcrumbs()breadcrumbsIntegration()
new GlobalHandlers()globalHandlersIntegration()
new HttpContext()httpContextIntegration()
new TryCatch()browserApiErrorsIntegration()
new BrowserProfilingIntegration()browserProfilingIntegration()

Deprecation introduced in 7.100.0.

The BrowserTracing integration, together with the custom routing instrumentations passed to it, are deprecated in v8.

Instead, you should use Sentry.browserTracingIntegration().

For react, we provide multiple integrations to cover different router integrations:

Copied
 import * as Sentry from '@sentry/react';

 Sentry.init({
   integrations: [
-    new Sentry.BrowserTracing({
-      routingInstrumentation: Sentry.reactRouterV6Instrumentation({
-        useEffect,
-        useLocation,
-        useNavigationType,
-        createRoutesFromChildren,
-        matchRoutes,
-        stripBasename,
-      }),
-    }),
+    Sentry.reactRouterV6BrowserTracingIntegration({
+      useEffect,
+      useLocation,
+      useNavigationType,
+      createRoutesFromChildren,
+      matchRoutes,
+      stripBasename,
+    }),
   ],
 });

Copied
 import * as Sentry from '@sentry/react';

 Sentry.init({
   integrations: [
-    new Sentry.BrowserTracing({
-      routingInstrumentation: Sentry.reactRouterV5Instrumentation({
-        history,
-      }),
-    }),
+    Sentry.reactRouterV5BrowserTracingIntegration({
+      history,
+    }),
   ],
 });

Copied
 import * as Sentry from '@sentry/react';

 Sentry.init({
   integrations: [
-    new Sentry.BrowserTracing({
-      routingInstrumentation: Sentry.reactRouterV3Instrumentation({
-        history,
-        routes,
-        match,
-      }),
-    }),
+    Sentry.reactRouterV3BrowserTracingIntegration({
+      history,
+      routes,
+      match,
+    }),
   ],
 });

Copied
 import * as Sentry from "@sentry/react";

 Sentry.init({
   dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
-  integrations: [new Sentry.BrowserTracing()],
+  integrations: [Sentry.browserTracingIntegration()],
 });

Deprecation introduced in 7.94.0.

This deprecates getIntegrationById() and getIntegration() on the client. Instead, use getIntegrationByName(). You can optionally pass an integration generic to make it easier to work with.

Copied
const replay = getClient().getIntegrationByName<Replay>("Replay");

Deprecation introduced in 7.110.0.

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

Scopes have existed before in the SDK but we are now expanding on them because we have found them powerful enough to fully cover the Hub API.

If you are using the Hub right now, see the following table on how to migrate to the new API:

Old Hub APINew Scope API
new Hub()withScope(), withIsolationScope() or new Scope()
hub.isOlderThan()REMOVED - Was used to compare Hub instances, which are gonna be removed
hub.bindClient()A combination of scope.setClient() and client.init()
hub.pushScope()Sentry.withScope()
hub.popScope()Sentry.withScope()
hub.withScope()Sentry.withScope()
getClient()Sentry.getClient()
getScope()Sentry.getCurrentScope() to get the currently active scope
getIsolationScope()Sentry.getIsolationScope()
getStack()REMOVED - The stack used to hold scopes. Scopes are used directly now
getStackTop()REMOVED - The stack used to hold scopes. Scopes are used directly now
captureException()Sentry.captureException()
captureMessage()Sentry.captureMessage()
captureEvent()Sentry.captureEvent()
addBreadcrumb()Sentry.addBreadcrumb()
setUser()Sentry.setUser()
setTags()Sentry.setTags()
setExtras()Sentry.setExtras()
setTag()Sentry.setTag()
setExtra()Sentry.setExtra()
setContext()Sentry.setContext()
configureScope()REMOVED - Scopes are now the unit of concurrency
run()Sentry.withScope() or Sentry.withIsolationScope()
getIntegration()client.getIntegration()
startTransaction()Sentry.startSpan(), Sentry.startInactiveSpan() or Sentry.startSpanManual()
traceHeaders()REMOVED - The closest equivalent is now spanToTraceHeader(getActiveSpan())
captureSession()Sentry.captureSession()
startSession()Sentry.startSession()
endSession()Sentry.endSession()
shouldSendDefaultPii()REMOVED - The closest equivalent is Sentry.getClient().getOptions().sendDefaultPii

The Hub constructor is also deprecated and will be removed in the next major version. If you are creating Hubs for multi-client use like so:

Copied
// OLD
const hub = new Hub();
hub.bindClient(client);
makeMain(hub);

instead initialize the client as follows:

Copied
// NEW
Sentry.withIsolationScope(() => {
  Sentry.setCurrentClient(client);
  client.init();
});

If you are using the Hub to capture events like so:

Copied
// OLD
const client = new Client();
const hub = new Hub(client);
hub.captureException();

instead capture isolated events as follows:

Copied
// NEW
const client = new Client();
const scope = new Scope();
scope.setClient(client);
scope.captureException();

Deprecation introduced in 7.85.0.

Instead of using addGlobalEventProcessor, you should use addEventProcessor which does not add the event processor globally, but to the current client.

For the vast majority of cases, the behavior of these should be the same. Only in the case where you have multiple clients will this differ - but you'll likely want to add event processors per-client then anyhow, not globally.

In v8, we will remove the global event processors overall, as that allows us to avoid keeping global state that is not necessary.

Deprecation introduced in 7.89.0.

Instead of updating the scope in a callback via configureScope(), you should access it via getCurrentScope() and configure it directly:

Copied
Sentry.getCurrentScope().setTag("xx", "yy");

Deprecation introduced in 7.89.0.

Instead of manually pushing/popping a scope, you should use Sentry.withScope(callback: (scope: Scope)) instead.

Deprecation introduced in 7.93.0.

In v8, the API to start a new span will be reduced from the currently available options. Going forward, only these arguments will be passable to startSpan(), startSpanManual() and startInactiveSpan():

  • name
  • attributes
  • origin
  • op
  • startTime
  • scope

Deprecation introduced in 7.93.0.

In v8, the old performance API startTransaction() (and hub.startTransaction()), as well as span.startChild(), will be removed. Instead, use the new performance APIs:

  • startSpan()
  • startSpanManual()
  • startInactiveSpan()

Deprecation introduced in 7.100.0.

Instead of an transactionContext being passed to the tracesSampler callback, the callback will directly receive name and attributes going forward. You can use these to make your sampling decisions, while transactionContext will be removed in 8.x. 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).

Deprecation introduced in 7.93.0.

Instead, you can get the currently active span via Sentry.getActiveSpan(). Setting a span on the scope happens automatically when you use the new performance APIs startSpan() and startSpanManual().

Deprecation introduced in 7.93.0.

Instead, either set this as attributes or tags, or use an event processor to set event.transaction.

Deprecation introduced in 7.93.0.

Instead, you should not rely on the active transaction, but just use startSpan() APIs, which handle this for you.

Help improve this content
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").