# Migrate from 7.x to 8.x | Sentry for Cloud Functions for Firebase

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.

## [Migration Codemod](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#migration-codemod)

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`](https://www.npmjs.com/package/@sentry/migr8) codemod to automatically update your SDK usage. `@sentry/migr8` requires Node 18+.

```bash
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](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v7-deprecations.md). Despite having `@sentry/migr8`, we still recommend reading the migration guide, since `@sentry/migr8` does not cover all of the changes needed to migrate.

## [Upgrading to `8.x`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#upgrading-to-8x)

`8.x` simplifies Sentry Node SDK initialization and leverages Node.js OpenTelemetry instrumentation for tracing.

There are more specific migration guides for the following platforms:

* [Express](https://docs.sentry.io/platforms/javascript/guides/express/migration/v7-to-v8.md)
* [Koa](https://docs.sentry.io/platforms/javascript/guides/koa/migration/v7-to-v8.md)
* [Connect](https://docs.sentry.io/platforms/javascript/guides/connect/migration/v7-to-v8.md)
* [Fastify](https://docs.sentry.io/platforms/javascript/guides/fastify/migration/v7-to-v8.md)

We recommend you read through all the [Important Changes](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#important-changes) as they affect all SDK users. The [Other Changes](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#other-changes) linked below only affect users who have more customized instrumentation. There is also a [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#troubleshooting) section for common issues.

We also have a [detailed migration guide](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md#upgrading-from-7x-to-8x) on GitHub, which has a comprehensive list of all changes alongside the source code of the SDK.

## [Important Changes](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#important-changes)

### [Supported versions](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#supported-versions)

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

### [Updated SDK initialization](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#updated-sdk-initialization)

With 8.x, @sentry/node has been completely overhauled. It is now powered by [OpenTelemetry](https://opentelemetry.io/) 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.

To migrate your Node.js app to Sentry Node SDK `8.x`, you need to make the following changes:

1. Create an external file called `instrument.js` and move your `Sentry.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`

```javascript
const Sentry = require("@sentry/node");

Sentry.init({
  // ...
});
```

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

`instrument.js`

```javascript
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  tracesSampleRate: 1.0,
});
```

We now support the following integrations out of the box with 0 configuration:

* `httpIntegration`: Automatically instruments Node `http` and `https` standard libraries
* `nativeNodeFetchIntegration`: Automatically instruments top level fetch and undici
* `expressIntegration`: Automatically instruments Express.js
* `fastifyIntegration`: Automatically instruments Fastify
* `hapiIntegration`: Automatically instruments Hapi
* `graphqlIntegration`: Automatically instruments GraphQL
* `mongoIntegration`: Automatically instruments MongoDB
* `mongooseIntegration`: Automatically instruments Mongoose
* `mysqlIntegration`: Automatically instruments MySQL
* `mysql2Integration`: Automatically instruments MySQL2
* `nestIntegration`: Automatically instruments Nest.js
* `postgresIntegration`: Automatically instruments PostgreSQL
* `connectIntegration`: Automatically instruments Connect

3. Require `instrument.js` before any other module in your application

`app.js`

```javascript
// Require this first!
require("./instrument");

// Now require other modules
const http = require("http");

// Your application code goes here
```

##### 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](https://docs.sentry.io/platforms/javascript/guides/firebase/install/esm.md). If you are unsure how you are running your application, see [Installation Methods](https://docs.sentry.io/platforms/javascript/guides/firebase/install.md) for more information.

### [Ensure Request Isolation](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#ensure-request-isolation)

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

```javascript
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.

### [New Tracing APIs](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#new-tracing-apis)

The Custom Instrumentation API for Tracing has been revamped in `8.x`. New methods have been introduced, and `startTransaction` and `span.startChild` has been removed. See the [new Tracing APIs docs](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v8-new-performance-api.md) for more information.

## [Other Changes](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#other-changes)

### [Customizing OpenTelemetry](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#customizing-opentelemetry)

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`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v8-opentelemetry.md)

### [Revamped Application Not Responding Detection](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#revamped-application-not-responding-detection)

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](https://docs.sentry.io/platforms/javascript/guides/node/configuration/application-not-responding.md)

```JavaScript
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [

    Sentry.anrIntegration({ captureStackTrace: true })

  ],
});
```

### [Behaviour in combination with `onUncaughtException` handlers in Node.js](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#behaviour-in-combination-with-onuncaughtexception-handlers-in-nodejs)

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.

### [Removal of `deepReadDirSync` method](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-deepreaddirsync-method)

The `deepReadDirSync` method has been removed as an export from the SDK. There is no replacement API.

### [Removal of `Sentry.Handlers.trpcMiddleware()` in favor of `Sentry.trpcMiddleware()`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-sentryhandlerstrpcmiddleware-in-favor-of-sentrytrpcmiddleware)

The Sentry tRPC middleware got moved from `Sentry.Handlers.trpcMiddleware()` to `Sentry.trpcMiddleware()`.

#### [Removal of Client-Side health check transaction filters](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-client-side-health-check-transaction-filters)

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.

### [Deprecation of `Hub` and `getCurrentHub()`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#deprecation-of-hub-and-getcurrenthub)

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](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v7-deprecations.md#deprecate-hub) for details on how to replace existing usage of the Hub APIs.

### [Removal of class-based integrations](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-class-based-integrations)

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](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v7-deprecations.md#deprecate-class-based-integrations).

### [Removal of `Sentry.configureScope` method](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-sentryconfigurescope-method)

The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` to access and mutate the current scope.

```JavaScript
- Sentry.configureScope((scope) => {
-  scope.setTag("key", "value");
- });
+ Sentry.getCurrentScope().setTag("key", "value");
```

### [`tracingOrigins` has been replaced by `tracePropagationTargets`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#tracingorigins-has-been-replaced-by-tracepropagationtargets)

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

```TypeScript
Sentry.init({
  dsn: "___DSN___",
  integrations: [Sentry.browserTracingIntegration()],
  tracePropagationTargets: ["localhost", "example.com"],
});
```

### [Simplification of Metrics Configuration](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#simplification-of-metrics-configuration)

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.

```TypeScript
// v7 - Server (Node/Deno/Bun)
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  _experiments: {
    metricsAggregator: true,
  },
});

// v7 - Browser
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.metricsAggregatorIntegration()],
});

Sentry.metrics.increment("my_metric");
```

In `8.x` no additional configuration is needed to use metrics APIs.

```ts
// v8
Sentry.init({
  dsn: "___PUBLIC_DSN___",
});

Sentry.metrics.increment("my_metric");
```

### [Removal of Severity Enum](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-severity-enum)

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.

```JavaScript
- import { Severity } from '@sentry/types';
+ import { SeverityLevel } from '@sentry/types';

- const level = Severity.error;
+ const level: SeverityLevel = "error";
```

#### [Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-spanstatusfromhttpcode-in-favour-of-getspanstatusfromhttpcode)

In `8.x`, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`.

```JavaScript
- const spanStatus = spanStatusfromHttpCode(200);
+ const spanStatus = getSpanStatusFromHttpCode(200);
```

### [`framesToPop` applies to parsed frames](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#framestopop-applies-to-parsed-frames)

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.

### [Removal of `Span` class export from SDK packages](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-span-class-export-from-sdk-packages)

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.

### [Removal of `void` from transport return types](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-void-from-transport-return-types)

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.

```TypeScript
// v7
 interface Transport {
-  send(event: Event): Promise<void | TransportMakeRequestResponse>;
+  send(event: Event): Promise<TransportMakeRequestResponse>;
 }
```

### [`extraErrorDataIntegration` changes](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#extraerrordataintegration-changes)

The `extraErrorDataIntegration` integration now looks at [`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by default.

### [`transactionContext` no longer passed to `tracesSampler`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#transactioncontext-no-longer-passed-to-tracessampler)

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()` always returns a client](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#getclient-always-returns-a-client)

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

### [Removal of `addGlobalEventProcessor` in favour of `addEventProcessor`](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-addglobaleventprocessor-in-favour-of-addeventprocessor)

In `8.x`, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`.

```JavaScript
- Sentry.addGlobalEventProcessor((event) => {
+ Sentry.getGlobalScope().addEventProcessor((event) => {
   delete event.extra;
   return event;
 });
```

### [Removal of `@sentry/integrations` package](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#removal-of-sentryintegrations-package)

`@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.

## [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#troubleshooting)

### [Conflicting Dependency Versions with Bundler Plugins](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8.md#conflicting-dependency-versions-with-bundler-plugins)

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, which 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.

## Pages in this section

- [New Tracing APIs](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v8-new-performance-api.md)
- [Deprecations in 7.x](https://docs.sentry.io/platforms/javascript/guides/firebase/migration/v7-to-v8/v7-deprecations.md)
