Migrating from v8 to v10 - Sentry JavaScript SDK

Version 10 focuses on upgrading OpenTelemetry dependencies to v2 with minimal breaking changes. This is a smaller upgrade compared to v7 to v8.

Prerequisites

Review the v10 changelog
Compatible with Sentry self-hosted 24.4.2 or higher
Test in a non-production environment first

Version Support Changes

Version 10 has updated runtime requirements:Node.js:

Minimum: Node 18.0.0
ESM-only SDKs (Astro, Nuxt, SvelteKit): Node 18.19.1+

Browsers:

Chrome 80+
Edge 80+
Safari 14+, iOS Safari 14.4+
Firefox 74+
Samsung Internet 13.0+

TypeScript:

Minimum: TypeScript 5.0.4

Deno:

Minimum: Deno 2.0.0

Installation

npm install @sentry/browser@^10.0.0
# or
yarn add @sentry/browser@^10.0.0

Major Changes from v9

1. Removed APIs

Hub API Completely Removed

The Hub API was deprecated in v8 and is now fully removed in v9+. Before (v8):

const hub = Sentry.getCurrentHub();
const client = hub.getClient();

After (v9+):

const client = Sentry.getClient();

Metrics API Removed

The metrics beta has ended. All metrics APIs have been removed.

// These are removed in v9:
Sentry.metrics.increment('counter');
Sentry.metrics.gauge('gauge', 100);
Sentry.metrics.distribution('distribution', 100);
Sentry.metrics.set('set', 'value');

Debug Integration Removed

Before (v8):

import { debugIntegration } from '@sentry/browser';

Sentry.init({
  integrations: [debugIntegration()],
});

After (v9+): Use beforeSend hook to log events:

Sentry.init({
  beforeSend(event) {
    console.log('Sending event:', event);
    return event;
  },
});

2. OpenTelemetry v2 (v10)

Version 10 upgrades OpenTelemetry dependencies from v1 to v2. Node.js Impact: All OpenTelemetry instrumentations have been updated. If you use custom OpenTelemetry instrumentations, you may need to update them:

import * as Sentry from '@sentry/node';
import { GenericPoolInstrumentation } from '@opentelemetry/instrumentation-generic-pool';

Sentry.init({
  dsn: '__DSN__',
  openTelemetryInstrumentations: [
    new GenericPoolInstrumentation(), // Ensure this is v2 compatible
  ],
});

3. Behavior Changes

beforeSendSpan Changes (v9)

You can no longer drop spans by returning null from beforeSendSpan. Before (v8):

Sentry.init({
  beforeSendSpan(span) {
    if (span.description?.includes('/health')) {
      return null; // Drop the span
    }
    return span;
  },
});

After (v9+):

Sentry.init({
  beforeSendSpan(span) {
    // Can only modify, not drop
    if (span.description?.includes('token=')) {
      span.description = span.description.split('?')[0];
    }
    return span;
  },
  
  // Use integrations to prevent span creation
  integrations: [
    Sentry.httpIntegration({
      tracing: {
        shouldCreateSpanForRequest: (url) => {
          return !url.includes('/health');
        },
      },
    }),
  ],
});

First Input Delay (FID) Removed (v10)

FID web vital has been removed as it’s deprecated by Google.

// v9 and earlier captured FID
// v10 captures INP (Interaction to Next Paint) instead

Sentry.init({
  integrations: [Sentry.browserTracingIntegration()],
  // INP is now automatically captured instead of FID
});

IP Address Collection (v10.4+)

IP address inference now respects sendDefaultPii: Before (v10.0-10.3):

Sentry.init({
  dsn: '__DSN__',
  // IP addresses were always inferred
});

After (v10.4+):

Sentry.init({
  dsn: '__DSN__',
  sendDefaultPii: true, // Now required to infer IP addresses
});

4. AWS Lambda Layer Changes

Version 10 Layer:

arn:aws:lambda:us-east-1:123456789012:layer:SentryNodeServerlessSDKv10:1

Version 9 Layer (for updates/fixes):

arn:aws:lambda:us-east-1:123456789012:layer:SentryNodeServerlessSDKv9:1

Framework-Specific Changes

Next.js

Source Maps (v9)

Client-side source maps are now automatically deleted after upload: Before (v8):

module.exports = withSentryConfig(nextConfig, {
  // Source maps left in deployment
});

After (v9+):

module.exports = withSentryConfig(nextConfig, {
  // Source maps automatically deleted
  // Opt out if needed:
  sourcemaps: {
    deleteSourcemapsAfterUpload: false,
  },
});

Build ID as Release (v9)

Next.js Build ID is no longer used as the release name:

module.exports = withSentryConfig(nextConfig, {
  // Explicitly set release name
  release: {
    name: process.env.RELEASE_VERSION,
  },
});

SvelteKit (v9)

Remix v1.x is no longer supported. Upgrade to v2+.

React (v9)

Error Boundary Types

Error types are now unknown instead of Error: Before (v8):

<ErrorBoundary
  onError={(error: Error) => {
    console.log(error.message); // Error type
  }}
>

After (v9+):

<ErrorBoundary
  onError={(error: unknown) => {
    if (error instanceof Error) {
      console.log(error.message);
    }
  }}
>

Node.js (v9)

processThreadBreadcrumbIntegration Renamed

Before (v8):

import { processThreadBreadcrumbIntegration } from '@sentry/node';

Sentry.init({
  integrations: [processThreadBreadcrumbIntegration()],
});

After (v9+):

import { childProcessIntegration } from '@sentry/node';

Sentry.init({
  integrations: [childProcessIntegration()],
});

Prisma v6 (v9)

Prisma integration now supports v6 by default:

import { prismaIntegration } from '@sentry/node';

Sentry.init({
  integrations: [prismaIntegration()],
  // No longer needs previewFeatures = ["tracing"] in schema
});

For Prisma v5:

import { PrismaInstrumentation } from '@prisma/instrumentation';
import { prismaIntegration } from '@sentry/node';

Sentry.init({
  integrations: [
    prismaIntegration({
      prismaInstrumentation: new PrismaInstrumentation(),
    }),
  ],
});

Step-by-Step Migration

From v8 to v9

1. Update Dependencies:

npm install @sentry/browser@^9.0.0

2. Remove Hub API Usage:

// Before
const hub = Sentry.getCurrentHub();
const client = hub.getClient();

// After
const client = Sentry.getClient();

3. Update beforeSendSpan:

// Before
beforeSendSpan(span) {
  if (shouldDrop) return null;
  return span;
}

// After
beforeSendSpan(span) {
  // Modify only, use integrations to prevent creation
  return span;
}

4. Remove Metrics: Remove all Sentry.metrics.* calls. 5. Test:

Error capturing
Performance monitoring
Custom instrumentation

From v9 to v10

1. Update Dependencies:

npm install @sentry/browser@^10.0.0

2. Update TypeScript (if needed):

npm install typescript@^5.0.4

3. Update Node.js (if needed): Ensure you’re running Node 18.0.0 or higher. 4. Update OpenTelemetry Instrumentations: If you use custom instrumentations, update to v2-compatible versions. 5. Handle IP Address Changes:

Sentry.init({
  dsn: '__DSN__',
  sendDefaultPii: true, // If you need IP addresses
});

6. Test:

All functionality still works
OpenTelemetry instrumentations work
Web vitals are captured (INP instead of FID)

Migration Checklist

v8 to v9

Update all @sentry/* packages to v9
Remove all Hub API usage
Remove metrics API calls
Update beforeSendSpan logic
Update React error boundary types
Rename processThreadBreadcrumbIntegration to childProcessIntegration
Test error capturing
Test performance monitoring

v9 to v10

Verify Node.js version ≥ 18.0.0
Verify TypeScript version ≥ 5.0.4
Update all @sentry/* packages to v10
Update OpenTelemetry instrumentations to v2
Set sendDefaultPii if you need IP addresses
Update AWS Lambda layer ARN (if using)
Test OpenTelemetry instrumentations
Verify web vitals capture (INP vs FID)

Common Issues

Type errors after upgrading

Issue: TypeScript errors about incompatible typesSolution: Upgrade TypeScript to 5.0.4 or higher:

npm install typescript@^5.0.4

OpenTelemetry instrumentation not working

Issue: Custom OpenTelemetry instrumentations stopped working in v10Solution: Update instrumentations to v2-compatible versions:

npm install @opentelemetry/instrumentation-http@latest

Missing IP addresses in events

Issue: User IP addresses no longer captured (v10.4+)Solution: Enable sendDefaultPii:

Sentry.init({
  sendDefaultPii: true,
});

Hub API errors

Issue: getCurrentHub is not a functionSolution: Replace with new API:

// Before
const hub = Sentry.getCurrentHub();

// After
const client = Sentry.getClient();
const scope = Sentry.getCurrentScope();

Quick Reference: API Changes

v8 API	v9+ API
`getCurrentHub()`	`getClient()`, `getCurrentScope()`
`configureScope()`	`getCurrentScope().method()`
`Hub.getClient()`	`getClient()`
`beforeSendSpan` returns `null`	Use integration `shouldCreateSpan*`
`metrics.increment()`	Removed
`debugIntegration()`	Use `beforeSend` hook
`processThreadBreadcrumbIntegration`	`childProcessIntegration`

Getting Help

If you encounter issues:

Check the v9 migration guide
Check the v10 migration guide
Search GitHub issues
Ask in Discord

Next Steps

General Upgrading Guide

Best practices for upgrading Sentry

Custom Integrations

Build custom integrations

Configuration

Best Practices

Migration

Advanced

​Prerequisites

​Version Support Changes

​Installation

​Major Changes from v9

​1. Removed APIs

​Hub API Completely Removed

​Metrics API Removed

​Debug Integration Removed

​2. OpenTelemetry v2 (v10)

​3. Behavior Changes

​beforeSendSpan Changes (v9)

​First Input Delay (FID) Removed (v10)

​IP Address Collection (v10.4+)

​4. AWS Lambda Layer Changes

​Framework-Specific Changes

​Next.js

​Source Maps (v9)

​Build ID as Release (v9)

​SvelteKit (v9)

​React (v9)

​Error Boundary Types

​Node.js (v9)

​processThreadBreadcrumbIntegration Renamed

​Prisma v6 (v9)

​Step-by-Step Migration

​From v8 to v9

​From v9 to v10

​Migration Checklist

​v8 to v9

​v9 to v10

​Common Issues

​Quick Reference: API Changes

​Getting Help

​Next Steps

General Upgrading Guide

Custom Integrations

Build docs developers (and LLMs) love

Prerequisites

Version Support Changes

Installation

Major Changes from v9

1. Removed APIs

Hub API Completely Removed

Metrics API Removed

Debug Integration Removed

2. OpenTelemetry v2 (v10)

3. Behavior Changes

beforeSendSpan Changes (v9)

First Input Delay (FID) Removed (v10)

IP Address Collection (v10.4+)

4. AWS Lambda Layer Changes

Framework-Specific Changes

Next.js

Source Maps (v9)

Build ID as Release (v9)

SvelteKit (v9)

React (v9)

Error Boundary Types

Node.js (v9)

processThreadBreadcrumbIntegration Renamed

Prisma v6 (v9)

Step-by-Step Migration

From v8 to v9

From v9 to v10

Migration Checklist

v8 to v9

v9 to v10

Common Issues

Quick Reference: API Changes

Getting Help

Next Steps