playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / sentry-upgrade-migration

sentry-upgrade-migration skill

/plugins/saas-packs/sentry-pack/skills/sentry-upgrade-migration

This skill guides upgrading the Sentry SDK and migrating between versions, ensuring breaking changes are resolved and verification steps are completed.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill sentry-upgrade-migration

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.8 KB
---
name: sentry-upgrade-migration
description: |
  Execute upgrade Sentry SDK and migrate between versions.
  Use when upgrading Sentry SDK, handling breaking changes,
  or migrating from legacy versions.
  Trigger with phrases like "upgrade sentry", "sentry migration",
  "update sentry sdk", "sentry breaking changes".
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Sentry Upgrade Migration

## Prerequisites

- Current Sentry SDK version identified
- Target version changelog reviewed
- Non-production environment for testing
- Test suite for error capture and performance monitoring

## Instructions

1. Check current SDK version with npm list or pip show
2. Review release notes and changelog for target version
3. Back up current Sentry configuration file
4. Update package to target version in non-production first
5. Run tests to identify breaking changes
6. Update deprecated APIs following migration guide patterns
7. Verify error capture works with test error
8. Verify performance monitoring works with test transaction
9. Deploy to staging and monitor for issues
10. Deploy to production after staging validation

## Output
- SDK upgraded to target version
- Breaking changes resolved
- Code updated for new APIs
- Error capture verified working

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Sentry JavaScript Changelog](https://github.com/getsentry/sentry-javascript/blob/master/CHANGELOG.md)
- [Sentry Python Changelog](https://github.com/getsentry/sentry-python/blob/master/CHANGELOG.md)
- [Migration Guides](https://docs.sentry.io/platforms/javascript/migration/)

Overview

This skill automates and guides the upgrade and migration of the Sentry SDK across versions. It helps you identify breaking changes, apply required code updates, and validate error and performance telemetry in safe environments. Use it to reduce risk when moving from legacy Sentry releases to current SDKs.

How this skill works

The skill inspects the current Sentry SDK version and compares it to the target release, surfacing relevant changelog and migration notes. It provides a step-by-step migration checklist: backing up config, updating packages in non-production, running tests, applying API changes, and validating error capture and transactions. It also recommends rollout steps for staging and production and points to platform-specific changelogs and migration guides.

When to use it

  • Upgrading the Sentry SDK to a newer major or minor version
  • Preparing for or resolving breaking changes reported by Sentry changelogs
  • Migrating from legacy Sentry implementations to the current SDK patterns
  • Validating error and performance monitoring after codebase changes
  • Rolling out Sentry updates through non-production, staging, and production environments

Best practices

  • Identify the current SDK version with package tools (npm list, pip show) before planning
  • Review target version release notes and migration guides thoroughly
  • Perform upgrades first in a non-production environment and keep a backup of configuration
  • Run your full test suite and add smoke tests for error capture and a sample transaction
  • Apply deprecations and API replacements incrementally and verify each change
  • Monitor staging closely for telemetry regressions before production rollout

Example use cases

  • Upgrade sentry-python from 0.x to 1.x and replace deprecated init arguments and API calls
  • Migrate a JavaScript app from an older sentry-javascript major release, updating config and SDK initialization
  • Validate that a new Sentry release preserves performance transactions by running synthetic transactions in staging
  • Automate a checklist that confirms error events are received after upgrade and no new crashes are introduced

FAQ

What should I check before starting an upgrade?

Confirm the current SDK version, read the target changelog and migration guide, back up configuration, and ensure tests run in a non-production environment.

How do I verify the upgrade worked?

Run unit and integration tests, send a test error and a test transaction, confirm events appear in Sentry, and monitor staging telemetry for anomalies.