sentry-sdk-upgrade

すべてのスキル > ワークフロー > SDK のアップグレード

Sentry JavaScript SDK のアップグレード

AI による移行ガイドを利用して、Sentry JavaScript SDK をメジャーバージョン間でアップグレードします。

このスキルを使う場合

• ユーザーが「Sentry をアップグレードして」または「Sentry SDK を移行して」と依頼した場合
• 非推奨の Sentry API や、バージョン更新後の破壊的変更についてユーザーが言及した場合
• v7 から v8、v8 から v9、またはその他のメジャーバージョンへの移行を希望している場合
• @sentry/* パッケージのバージョンを更新した後にエラーが発生した場合
• Sentry の移行ガイドや変更履歴についてユーザーが質問した場合

フェーズ 1：検出

現在の Sentry SDK のバージョン、対象バージョン、フレームワークを特定します。

1.1 package.json を読み取る

cat package.json | grep -E '"@sentry/' | head -20

以下を抽出します。

• すべての @sentry/* パッケージと現在のバージョン
• 現在のメジャーバージョン（例：7.x、8.x、9.x）

1.2 フレームワークを検出する

フレームワークを示す依存関係が package.json にあるか確認します。

依存関係	フレームワーク	Sentry パッケージ
next	Next.js	@sentry/nextjs
nuxt または @nuxt/kit	Nuxt	@sentry/nuxt
@sveltejs/kit	SvelteKit	@sentry/sveltekit
@remix-run/node	Remix	@sentry/remix
react（Next/Remix なし）	React SPA	@sentry/react
@angular/core	Angular	@sentry/angular
vue（Nuxt なし）	Vue	@sentry/vue
express	Express	@sentry/node
@nestjs/core	NestJS	@sentry/nestjs
@solidjs/start	SolidStart	@sentry/solidstart
astro	Astro	@sentry/astro
bun の型またはランタイム	Bun	@sentry/bun
@cloudflare/workers-types	Cloudflare	@sentry/cloudflare
上記のいずれにも該当しない（Node.js）	Node.js	@sentry/node

1.3 Sentry の設定ファイルを見つける

grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -l

find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next | grep -v .nuxt

1.4 非推奨パターンを検出する

必要な移行手順を特定するため、以下のパターンを検索します。

# v7 patterns (need v7→v8 migration)
grep -rn "from '@sentry/hub'\|from '@sentry/tracing'\|from '@sentry/integrations'\|from '@sentry/serverless'\|from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l
grep -rn "new BrowserTracing\|new Replay\|startTransaction\|configureScope\|Handlers\.requestHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

# v8 patterns (need v8→v9 migration)
grep -rn "from '@sentry/utils'\|from '@sentry/types'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l
grep -rn "getCurrentHub\|enableTracing\|captureUserFeedback\|@WithSentry\|autoSessionTracking" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

1.5 対象バージョンを決定する

ユーザーが対象バージョンを指定していない場合は、最新のメジャーバージョン（執筆時点では v9）を推奨します。ユーザーがすでにパッケージのバージョンを更新していて、コードに問題がある場合は、package.json から対象バージョンを特定します。

フェーズ 2：推奨

検出した状態に基づいて、移行の概要を提示します。

2.1 移行経路を算出する

• 1 段階：例：v8 から v9
• 複数段階：例：v7 から v9（まず v7→v8 の変更を適用し、次に v8→v9 の変更を適用）

複数段階の移行では、コードの変更を段階的に適用しますが、パッケージのバージョンは最終的な対象に一度に更新します。

2.2 破壊的変更の概要を提示する

該当するバージョン固有のリファレンスを読み込みます。

• v7→v8：references/v7-to-v8.md
• v8→v9：references/v8-to-v9.md
• v9→v10：references/v9-to-v10.md

必要な変更を複雑さ別に分類し、具体的な概要を提示します。

自動修正可能（そのまま適用）：

• パッケージのインポート名の変更（例：@sentry/utils から @sentry/core）
• 単純なメソッド名の変更（例：@WithSentry から @SentryExceptionCaptured）
• 設定オプションの置き換え（例：enableTracing から tracesSampleRate）

AI による支援が必要（説明して提案）：

• 変数への保存パターンを伴う Hub の削除
• パフォーマンス API の移行（トランザクションからスパンへ）
• 複雑な設定の再構成（Vue のトレーシングオプション、Next.js の設定マージ）
• サンプラーの transactionContext のフラット化

手動レビューが必要（ユーザーに提示）：

• 代替手段のない削除済み API
• 動作の変更（サンプリング、ソースマップのデフォルト値）
• カスタムトランスポートの変更

2.3 対象範囲を確認する

ユーザーに以下を確認します。

• 移行経路（例：「v8 から v9」）
• すべての変更を適用するか、特定のカテゴリのみ適用するか
• 注：v8→v9 には npx @sentry/wizard -i upgrade という CLI の代替手段がありますが、すべてのパターンに対応できるとは限りません

フェーズ 3：ガイド

ファイルごとに変更を進めます。

3.1 Sentry のインポートを含む各ファイルを処理する

Phase 1.3 で特定した各ファイルについて、次の手順を実行します。

1. ファイルを読み、現在の Sentry の使用状況を把握します
2. 自動修正可能な変更を直接適用します。
   • パッケージのインポート名の変更
   • メソッド／関数名の変更
   • 単純な設定オプションの置き換え
3. AI を利用した変更については、何を変更する必要があるかとその理由を説明してから、具体的な編集案を提示します
4. 判断が難しい変更については、コードを示してユーザーに確認します

3.2 カテゴリ別に変更を適用する

次の順序で変更を進めます。

Step 1: パッケージのインポートを更新する

削除または名前が変更されたパッケージのインポートを置き換えます。対応関係の完全な一覧については、バージョン固有の移行ファイルを参照してください。

Step 2: API 名を変更する

メソッド名と関数名を機械的に変更します。

Step 3: 設定を変更する

Sentry.init() のオプションとビルド設定を更新します。

Step 4: 複雑なパターンを移行する

コンテキストの理解が必要なパターンに対応します。

• 変数に保存された Hub の使用
• トランザクションベースのパフォーマンスコード
• カスタムインテグレーションクラス
• フレームワーク固有のラッパー

Step 5: package.json のバージョンを更新する

すべての @sentry/* パッケージを対象バージョンに更新します。すべてのパッケージのメジャーバージョンをそろえる必要があります。

# Detect package manager
if [ -f "yarn.lock" ]; then
  echo "yarn"
elif [ -f "pnpm-lock.yaml" ]; then
  echo "pnpm"
else
  echo "npm"
fi

検出したパッケージマネージャーを使用して、更新した依存関係をインストールします。

Step 6: ビルドを検証する

# Check for type errors
npx tsc --noEmit 2>&1 | head -50

# Run build
npm run build 2>&1 | tail -20

残っている型エラーやビルドの失敗を修正します。

3.3 フレームワーク固有の手順

フレームワーク固有の設定ファイルの場所と検証手順については、references/upgrade-patterns.md を参照してください。

Next.js：instrumentation.ts、next.config.ts のラッパー、クライアントとサーバーの両方の設定を確認します。 Nuxt：Nuxt モジュールの設定と両方のプラグインファイルを確認します。 SvelteKit：フックファイルと Vite の設定を確認します。 Express/Node：初期化の順序が適切であることを確認します。 NestJS：デコレーターとフィルターの名前変更を確認します。

Phase 4: クロスリンク

4.1 検証する

• すべての @sentry/* パッケージのバージョンがそろっている
• 削除されたパッケージに起因するインポートエラーがない
• TypeScript のコンパイルが成功する
• ビルドが成功する
• テストが成功する（存在する場合）

テストエラーを追加することを提案します。

// Add temporarily to verify Sentry is working after upgrade
setTimeout(() => {
  throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);

4.2 対象バージョンの新機能

新しいバージョンで利用でき、ユーザーが有効にしたい可能性のある機能について説明します。

v8 の新機能：OpenTelemetry ベースの Node トレーシング、自動データベース／HTTP インストルメンテーション、関数型インテグレーション、新しいスパン API

v9 の新機能：構造化ログ（Sentry.logger.*）、ソースマップ処理の改善、簡素化された設定

4.3 関連リソース

• 公式移行ガイド（v7→v8）
• 公式移行ガイド（v8→v9）
• Sentry JavaScript SDK の変更履歴

ユーザーがアップグレードを必要とする他の Sentry SDK（Python、Ruby、Go など）を利用している場合、このスキルの対象は JavaScript SDK のみであることを伝えてください。