Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/sentry-migration-deep-dive/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill sentry-migration-deep-dive. Copyright stays with the author (MIT).

Sentry Migration Deep Dive

Overview

Replace an existing error tracking tool (Rollbar, Bugsnag, New Relic, Raygun, Airbrake) with Sentry using a phased migration that runs both tools in parallel before cutover. This skill covers concept mapping between providers, SDK swap patterns, alert rule migration, team training, and rollback strategy.

Current State

!npm list 2>/dev/null | command grep -iE "sentry|rollbar|bugsnag|raygun|airbrake|honeybadger|newrelic" || echo 'No error tracking packages found'

Prerequisites

• Admin access to the current error tracking tool (API keys, alert rule access)
• Sentry project created with DSN available in environment variables
• Source maps or debug symbols configured for stack trace resolution
• Parallel run timeline agreed with team (2-4 weeks recommended)
• Inventory of current alert rules, integrations, and custom filters

Instructions

Step 1: Map Concepts Between Providers

Build a translation table mapping the current tool's terminology and API surface to Sentry equivalents. Scan the codebase for all calls to the existing SDK.

Use Grep to find all references: grep -rn "rollbar\|Bugsnag\|newrelic\|noticeError" --include="*.ts" --include="*.js" src/

Step 2: Install Sentry in Parallel

Install the Sentry SDK alongside the existing tool. Route errors to both destinations during the transition period to validate parity before removing the old tool.

// instrument.ts -- load BEFORE any other import
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.npm_package_version,  // auto-read from package.json
  tracesSampleRate: 0.1,                     // start low, tune after baseline
  sendDefaultPii: false,
});

// dual-reporter.ts -- send to BOTH tools during parallel run
import * as Sentry from '@sentry/node';

// Keep existing tool import (e.g., Rollbar, Bugsnag)
import Rollbar from 'rollbar';
const rollbar = new Rollbar({ accessToken: process.env.ROLLBAR_TOKEN });

export function captureError(error: Error, context?: Record<string, unknown>) {
  // Sentry (new)
  Sentry.withScope((scope) => {
    if (context) scope.setContext('migration', context);
    Sentry.captureException(error);
  });

  // Old tool (keep running until parity verified)
  rollbar.error(error, context);
}

export function setUserContext(user: { id: string; email?: string }) {
  Sentry.setUser(user);
  rollbar.configure({ payload: { person: { id: user.id, email: user.email } } });
}

Step 3: Migrate Alert Rules, Validate Parity, and Cut Over

1. Export alert rules from the old tool. Map each alert to a Sentry equivalent:

   • "New error in production" becomes a Sentry Issue Alert with filter environment:production and action "Send Slack notification".
   • "Error rate > 100/min" becomes a Sentry Metric Alert with threshold 100 events per minute and PagerDuty action.
   • Rate-based alerts use Sentry Metric Alerts; occurrence-based alerts use Sentry Issue Alerts.

2. Validate parity during the parallel run window:

   # Compare error counts -- Sentry API
   curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
     "https://sentry.io/api/0/projects/$SENTRY_ORG/$SENTRY_PROJECT/stats/" | jq '.[] | .total'
   
   # Compare with old tool API (Rollbar example)
   curl -s -H "X-Rollbar-Access-Token: $ROLLBAR_TOKEN" \
     "https://api.rollbar.com/api/1/reports/top_recent_items" | jq '.result | length'

   • Error count should be within 10% between tools.
   • Stack traces must resolve correctly (verify source maps uploaded to Sentry).
   • Breadcrumbs, user context, and tags must appear in Sentry event detail.

3. Remove the old SDK after parity is confirmed:

   npm uninstall rollbar @bugsnag/node @bugsnag/plugin-express newrelic || echo "Some packages not found (expected if only one tool was installed)"

   Search for leftover references and remove them:

   grep -rn "rollbar\|bugsnag\|newrelic\|raygun\|airbrake" \
     --include="*.ts" --include="*.js" --include="*.env*" \
     --exclude-dir=node_modules . || echo "No remaining references found"

4. Schedule team training: walk through the Sentry dashboard (Issues, Performance, Releases views), show how to assign issues, and demonstrate the alert configuration UI.

5. Rollback strategy: keep the old tool's npm package in devDependencies and its configuration file in a migration-backup/ directory for 30 days after cutover. If Sentry surfaces fewer errors than expected, re-enable dual reporting and investigate.

Output

• Concept mapping table translating old API calls to Sentry equivalents
• Dual-reporting wrapper sending errors to both tools during parallel run
• Sentry SDK initialized with environment, release, and sampling configuration
• Alert rules migrated from old tool to Sentry Issue and Metric Alerts
• Parity validation confirming error count, stack traces, and context match
• Old SDK removed and all references cleaned from codebase

Error Handling

Examples

Migrate Express app from Rollbar to Sentry:

// BEFORE: rollbar error handler middleware
import Rollbar from 'rollbar';
const rollbar = new Rollbar({ accessToken: process.env.ROLLBAR_TOKEN });
app.use(rollbar.errorHandler());

// AFTER: Sentry error handler middleware
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: process.env.SENTRY_DSN });
Sentry.setupExpressErrorHandler(app);

Migrate React error boundary from Bugsnag to Sentry:

// BEFORE: Bugsnag React initialization + error boundary
import Bugsnag from '@bugsnag/js';
import BugsnagPluginReact from '@bugsnag/plugin-react';
Bugsnag.start({ plugins: [new BugsnagPluginReact()] });
const ErrorBoundary = Bugsnag.getPlugin('react')!.createErrorBoundary(React);
// Usage: wrap root component with ErrorBoundary

// AFTER: Sentry React initialization + error boundary
import * as Sentry from '@sentry/react';
Sentry.init({ dsn: process.env.SENTRY_DSN });
// Usage: wrap root component with Sentry.ErrorBoundary (accepts fallback prop)
// See @sentry/react docs for ErrorBoundary component API

Post-migration verification script:

import * as Sentry from '@sentry/node';

async function verifyMigration() {
  const eventId = Sentry.captureException(new Error('Migration verification test'));
  console.log('Error captured:', eventId ? 'PASS' : 'FAIL');

  Sentry.captureMessage('Migration complete', 'info');

  const flushed = await Sentry.flush(5000);
  console.log('Events delivered:', flushed ? 'PASS' : 'FAIL');
}

verifyMigration();

Resources

• Sentry SDK Documentation
• Sentry Migration Guide
• Sentry vs Rollbar comparison
• Sentry vs Bugsnag comparison
• Source Maps Upload CLI
• Sentry Alert Configuration

Next Steps

After migration, proceed to sentry-performance-tracing to configure distributed tracing, or sentry-prod-checklist to verify production readiness.