Sentry Upgrade Migration

# JavaScript: list all Sentry packages and their versions
npm ls 2>/dev/null | command grep "@sentry/"

# Python: check installed version
pip show sentry-sdk 2>/dev/null

# Verify all @sentry/* packages are the same major version (critical!)
# Mixed versions cause runtime crashes
npm ls @sentry/core @sentry/node @sentry/browser @sentry/utils 2>/dev/null

# Detect v7 Hub usage (removed in v8)
command grep -rn "getCurrentHub\|configureScope\|hub\.capture" src/ --include="*.ts" --include="*.js"

# Detect v7 Transaction API (replaced in v8)
command grep -rn "startTransaction\|\.startChild\|\.finish()" src/ --include="*.ts" --include="*.js"

# Detect class-based integrations (replaced in v8)
command grep -rn "new Sentry\.\|new BrowserTracing\|new Integrations\." src/ --include="*.ts" --include="*.js"

# Detect @sentry/tracing imports (package removed in v8)
command grep -rn "from '@sentry/tracing'" src/ --include="*.ts" --include="*.js"

# Python: detect v1 scope API (replaced in v2)
command grep -rn "configure_scope\|push_scope" src/ --include="*.py"

# First upgrade to latest v7 to get deprecation warnings
npm install @sentry/node@7

# Run the official migr8 codemod — rewrites deprecated APIs automatically
npx @sentry/migr8@latest
# Handles: Hub removal, integration class→function, import path changes
# Does NOT handle: Transaction→startSpan, ESM init pattern, custom transports

# Now upgrade to v8
npm install @sentry/node@8

// v7 (OLD) — manual transaction lifecycle
const transaction = Sentry.startTransaction({ name: 'process', op: 'task' });
const span = transaction.startChild({ op: 'db.query', description: 'SELECT users' });
// ... do work
span.finish();
transaction.finish();

// v8 (NEW) — callback-based, auto-finishes on return
await Sentry.startSpan({ name: 'process', op: 'task' }, async () => {
  await Sentry.startSpan({ name: 'SELECT users', op: 'db.query' }, async () => {
    // ... do work
  }); // span auto-finishes when callback returns
}); // root span auto-finishes when callback returns

// v7 (OLD)
const hub = Sentry.getCurrentHub();
hub.configureScope((scope) => {
  scope.setTag('region', 'us-east-1');
});
const transaction = hub.startTransaction({ name: 'my-tx' });

// v8 (NEW)
Sentry.withScope((scope) => {
  scope.setTag('region', 'us-east-1');
});
Sentry.startSpan({ name: 'my-tx', op: 'custom' }, (span) => {
  // work within span
});

// v7 (OLD)
import * as Sentry from '@sentry/node';
Sentry.init({
  integrations: [new Sentry.Integrations.Http({ tracing: true })],
});

// v8 (NEW) — most integrations are auto-enabled
Sentry.init({
  integrations: [
    Sentry.httpIntegration({ tracing: true }),
  ],
});

// v7 (OLD)
import { BrowserTracing } from '@sentry/tracing';
Sentry.init({
  integrations: [new BrowserTracing()],
});

// v8 (NEW) — built into @sentry/browser and @sentry/node
Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration(),
  ],
});

// v7 (OLD) — init at top of entry file
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' });
// ... app code

// v8 (NEW) — must be in separate file, loaded via --import
// instrument.mjs (separate file)
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' });

// Run with: node --import ./instrument.mjs app.mjs
// Or in package.json: "start": "node --import ./instrument.mjs app.mjs"

// v7 (OLD) — send could return void
makeRequest(request) {
  sendToBackend(request);
}

// v8 (NEW) — must return TransportMakeRequestResponse
makeRequest(request) {
  sendToBackend(request);
  return { statusCode: 200 };
}

# v1 (OLD) — configure_scope / push_scope
import sentry_sdk

with sentry_sdk.configure_scope() as scope:
    scope.set_tag("key", "value")

with sentry_sdk.push_scope() as scope:
    scope.set_extra("debug_info", data)
    sentry_sdk.capture_message("scoped message")

# v2 (NEW) — get_current_scope / new_scope
import sentry_sdk

scope = sentry_sdk.get_current_scope()
scope.set_tag("key", "value")

with sentry_sdk.new_scope() as scope:
    scope.set_extra("debug_info", data)
    sentry_sdk.capture_message("scoped message")

# Upgrade Python SDK
pip install --upgrade sentry-sdk

# Verify version
python -c "import sentry_sdk; print(sentry_sdk.VERSION)"

# All @sentry/* packages MUST be the same major version
# Mixed versions cause "Cannot read properties of undefined" runtime errors
npm install @sentry/node@8 @sentry/browser@8 @sentry/react@8 @sentry/profiling-node@8

# Remove deprecated packages
npm uninstall @sentry/tracing @sentry/hub 2>/dev/null

# Update bundler plugins (must be v2.14.2+ for SDK v8 compatibility)
npm install @sentry/webpack-plugin@latest @sentry/vite-plugin@latest 2>/dev/null

// test-migration.mjs — run after upgrading
import * as Sentry from '@sentry/node';

async function verifyUpgrade() {
  console.log('SDK Version:', Sentry.SDK_VERSION);

  // 1. Test error capture
  try {
    throw new Error('Migration verification error');
  } catch (e) {
    const eventId = Sentry.captureException(e);
    console.log('Error captured:', eventId ? 'PASS' : 'FAIL');
  }

  // 2. Test scoped context (v8 API)
  Sentry.withScope((scope) => {
    scope.setTag('test', 'migration-verify');
    scope.setUser({ id: 'test-user' });
    Sentry.captureMessage('Scoped context test');
  });
  console.log('Scoped context: PASS');

  // 3. Test performance span (v8 API — replaces startTransaction)
  await Sentry.startSpan(
    { name: 'migration-verify', op: 'test' },
    async (span) => {
      await Sentry.startSpan(
        { name: 'child-operation', op: 'test.child' },
        async () => {
          await new Promise((r) => setTimeout(r, 50));
        }
      );
      console.log('Span created:', span ? 'PASS' : 'FAIL');
    }
  );

  // 4. Test breadcrumbs
  Sentry.addBreadcrumb({
    category: 'test',
    message: 'Migration breadcrumb',
    level: 'info',
  });
  console.log('Breadcrumb: PASS');

  // 5. Flush and verify delivery
  const flushed = await Sentry.flush(5000);
  console.log('Flush:', flushed ? 'PASS' : 'FAIL');
}

verifyUpgrade();