All Skills > Workflow > SDK Upgrade

Sentry JavaScript SDK アップグレード

AI ガイド付きマイグレーションで Sentry JavaScript SDK をメジャーバージョン間でアップグレードします。

このスキルを呼び出すタイミング

• ユーザーが「Sentry をアップグレードする」または「Sentry SDK を移行する」と依頼した
• ユーザーが非推奨の Sentry API またはバージョンバンプ後の重大な変更について言及した
• ユーザーが v7 から v8 へ、v8 から v9 へ、またはメジャーバージョン間のジャンプを行いたい
• ユーザーが @sentry/* パッケージバージョンを更新後にエラーが発生した
• ユーザーが Sentry マイグレーションガイドまたはchangelog について質問した

フェーズ 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 types または runtime	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 パターン (v7→v8 マイグレーションが必要)
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 パターン (v8→v9 マイグレーションが必要)
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 マイグレーションパスを計算

• シングルホップ: 例えば 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 設定マージング)
• Sampler transactionContext フラット化

手動レビュー (ユーザーにフラグ):

• 同等の機能がない削除された API
• 動作の変更 (サンプリング、ソースマップのデフォルト)
• カスタムトランスポートの変更

2.3 スコープを確認

ユーザーに以下を尋ねます:

• マイグレーションパスを確認する (例: "v8 から v9")
• すべての変更を進めるか、特定のカテゴリのみを進めるかを確認する
• 注記: npx @sentry/wizard -i upgrade は v8→v9 の CLI 代替手段として存在しますが、すべてのパターンを処理しない可能性があります

フェーズ 3: ガイド

ファイルごとに変更をステップスルーします。

3.1 Sentry インポートを持つ各ファイルを処理

フェーズ 1.3 で識別されたファイルごとに:

1. ファイルを読む - 現在の Sentry 使用法を理解する
2. 自動修正可能な変更を適用する - 直接適用:
   • パッケージのインポート名変更
   • メソッド/関数名の変更
   • シンプルな設定オプションの交換
3. AI アシスト変更の場合 - 何が変わる必要があり、なぜか説明してから、具体的な編集を提案する
4. 不確実な変更の場合 - コードを表示し、ユーザーに確認を求める

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

この順序で変更をすべて処理します:

ステップ 1: パッケージインポートの更新

削除/名前変更されたパッケージインポートを置換します。完全なマッピングについてはバージョン固有のマイグレーションファイルを参照してください。

ステップ 2: API 名変更

メカニカルなメソッドと関数の名前変更を適用します。

ステップ 3: 設定変更

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

ステップ 4: 複雑なパターンマイグレーション

コンテキストの理解が必要なパターンを処理します:

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

ステップ 5: package.json バージョンを更新

すべての @sentry/* パッケージをターゲットバージョンに更新します。すべてのパッケージが同じメジャーバージョンである必要があります。

# パッケージマネージャーを検出
if [ -f "yarn.lock" ]; then
  echo "yarn"
elif [ -f "pnpm-lock.yaml" ]; then
  echo "pnpm"
else
  echo "npm"
fi

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

ステップ 6: ビルドを検証

# 型エラーをチェック
npx tsc --noEmit 2>&1 | head -50

# ビルドを実行
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: デコレーターとフィルターの名前変更をチェックします。

フェーズ 4: クロスリンク

4.1 検証

• すべての @sentry/* パッケージが同じバージョン
• 削除されたパッケージからのインポートエラーなし
• TypeScript コンパイルが成功
• ビルドが成功
• テストが成功 (存在する場合)

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

// アップグレード後に Sentry が機能していることを確認するために一時的に追加 - 削除して問題ありません
setTimeout(() => {
  throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);

4.2 ターゲットバージョンの新機能

ユーザーが有効にしたい可能性のある新バージョンの機能について言及します:

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

v9 の新機能: 構造化ログ (Sentry.logger.*)、改善されたソースマップ処理、簡略化された設定

4.3 関連リソース

• Official Migration Guide (v7→v8)
• Official Migration Guide (v8→v9)
• Sentry JavaScript SDK Changelog

ユーザーが他の Sentry SDK (Python、Ruby、Go など) もアップグレードする必要がある場合、このスキルは JavaScript SDK のみをカバーしていることに注意してください。