【Sentry SDK】アップグレードが必要な状態かもしれません

Article by: Sergiy Dybskiy

 
 

Session Replay、Structured Logs（構造化ログ）、AI Monitoring（AIモニタリング）、Automatic OpenTelemetry Tracing（自動 OpenTelemetry トレーシング）、Feature Flag Tracking（フィーチャーフラグトラッキング）。もしこれらをあなたの Sentry ダッシュボードで見かけていないなら、その理由はおそらく SDK のバージョンにあります。

@sentry/react、@sentry/nextjs、@sentry/vue、@sentry/angular、@sentry/sveltekit、あるいはその他の @sentry/* パッケージのいずれを使っていても、これらはすべて同じバージョンで管理されています。v10 はそれらすべてを指しています。

ここで重要なのは、npm のダウンロード数に基づくと、Sentry の JavaScript SDK のインストールの約半分が、いまだに v8 もしくはそれ以前にとどまっているという点です。

 

 

データ

主要な @sentry/* パッケージについて、npm のダウンロード統計を取得しました。2026年3月時点での週間インストール数は以下の通りです。

パッケージ

週間合計

v7のまま

v7 + v8 合計

@sentry/node

14.9M

4.8M (32%)

7.3M (49%)

@sentry/browser

14.5M

3.2M (22%)

7.3M (50%)

@sentry/react

9.9M

2.0M (20%)

4.9M (49%)

@sentry/nextjs

3.7M

524K (14%)

1.5M (41%)

@sentry/vue

1.1M

307K (28%)

642K (59%)

すべてのパッケージで同じ傾向が見られます。インストールの約半数が、現行バージョンよりも2つ以上前のメジャーバージョンにとどまっています。もしこれがあなたに当てはまるなら、この投稿は「何を見逃しているのか」と「どうやってその差を埋めるのか」を示す地図になります。

 

 

SDK はもはや単なるエラーキャッチャーではありません

Sentry SDK は、もともとクラッシュレポーターとして始まりました。現在では、完全なオブザーバビリティクライアントへと進化しています。エラー、パフォーマンストレース、セッションリプレイ、構造化ログ、cron モニター、ユーザーフィードバック、そして AI エージェントのモニタリングまで対応しています。これらの各機能は互いにコンテキストを補い合います。リプレイはエラーが発生する前にユーザーが何をしていたかを示し、トレースはどのマイクロサービスが遅かったかを示します。ログはアプリケーションレベルでの「なぜ」を提供します。

もし古いバージョンを使っているなら、あなたが得られるのはエラーだけです。最新バージョンであれば、そこにストーリーがあります。

 
 

見逃しているもの

Session Replay（v8+）

Session Replay は、エラーの前・最中・後にブラウザで何が起きたかを記録します。DOM、ユーザーのクリック、ナビゲーション、コンソール出力を再構成し、動画のように再生できる形にします。デフォルトでプライバシーに配慮されており、テキストや入力はマスクされ、何を取得するかはユーザー側で制御できます。

重要なポイントは、リプレイがエラーやトレースと直接リンクされることです。バグレポートを見ているとき、その再現をユーザーの操作として確認できます。ユーザーに「何が起きたか」を尋ねる必要はもうありません。返信を待つ必要もありません。「動かない」という曖昧な報告を推測する必要もありません。

@sentry/browser、@sentry/react、@sentry/vue、@sentry/angular、@sentry/svelte で利用可能です。

 

Structured Logs（v9+）

Sentry.logger.info()、Sentry.logger.error()、およびさらに4つの重大度レベルを持ち、トレースやエラーにリンクされる構造化された属性を備えています。

 
 
OpenTelemetry Tracing（v8+）

v8 では、パフォーマンスモニタリングが OpenTelemetry をベースに再構築されました。従来の考え方では、「トランザクション」と「スパン」は別々の概念として扱われ、ライフサイクルも手動で管理する必要がありました。新しいモデルでは、すべてがスパンとして扱われ、ライフサイクルは自動化されています。

コード量が減るだけでなく、インストルメンテーションとの関係性そのものも変わります。スパンのライフサイクルを自分で管理する必要はありません。何を計測したいのかを記述すれば、あとは SDK が処理します。ネストされたスパンも自動的に機能します。

Node.js、Express、Fastify、Hapi、Postgres、MongoDB、Redis、Prisma、GraphQL、MySQL、Mongoose は、いずれも手動設定なしで自動的にインストルメントされます。必要なのは Sentry.init() を呼ぶだけです。
 
 

内部で何が変わったのか

上記の機能はアップグレードの主な理由ですが、ここでは各メジャーバージョンで構造的に何が変わったのかを簡潔にまとめます。

v8：パッケージの統合

  • @sentry/tracing
  • @sentry/hub
  • @sentry/integrations
  • @sentry/replay

 

これらはすべてコア SDK に統合されました。インテグレーションは関数化され（new BrowserTracing() は browserTracingIntegration() に変更）、ツリーシェイキングが改善されています。User Feedback ウィジェット、Cron Monitoring、FID 計測が追加されました。Angular は v14 以上が必須になりました。新しいスコープモデル（getCurrentScope()、getIsolationScope()、getGlobalScope()）が導入され、Hub、getCurrentHub()、configureScope() は非推奨となり、コンソール警告が表示されます。これは v7 からアップグレードする際に最も大きな破壊的変更の要因です。

 

v9：非推奨 API の削除

  • Hub
  • getCurrentHub()
  • configureScope()

 

非推奨だったスコープ API は削除されました。@sentry/utils は @sentry/core に統合され、@sentry/types は非推奨となりました。ES2020 が基準となりました。フィーチャーフラグのトラッキングが追加され、LaunchDarkly と OpenFeature が標準でサポートされます。Node.js 18 が最小要件になりました。

 

v10：OpenTelemetry v2

内部で使用されている OpenTelemetry の依存関係が v2.x にアップグレードされました。FID 計測は廃止され、Google が Core Web Vitals で実際に使用している指標である INP（Interaction to Next Paint）に置き換えられました。@sentry/node-core には、完全な OpenTelemetry のインストルメンテーションなしで、エラー、ログ、メトリクスを扱いたいチーム向けの軽量モードが追加されました。Next.js の Turbopack サポートも追加されています。

 

クイックリファレンス：バージョン別の機能

機能

最小バージョン

対応パッケージ

ドキュメント

Cron Monitoring

v7+

node、すべてのサーバーSDK

Cronの設定

Session Replay

v8+

browser、react、vue、angular、svelte

Session Replayの設定

User Feedback Widget

v8+

browser、すべてのフロントエンドSDK

User Feedbackの設定

Structured Logs

v9+

全て

Logs の設定

Feature Flag Tracking

v9+

全て

Feature Flag を設定する

AI Monitoring（OpenAI, LangChain）

v9+

node

AI Agent Monitoringの設定

AI Monitoring（Anthropic, Vercel AI）

v10+

node

AI Agent Monitoringの設定

INP（Core Web Vitals 指標）

v10+

browser、すべてのフロントエンドSDK

—

 

まだ残っている可能性のある非推奨パッケージ

以下のいずれかが lockfile に含まれている場合、少なくとも2つ以上前のメジャーバージョンを使用しています。

  • @sentry/tracing（v8 でコア SDK に統合）
  • @sentry/hub（v8 で @sentry/core に統合）
  • @sentry/integrations（v8 でコア SDK に統合）
  • @sentry/replay（v8 で @sentry/browser に統合）
  • @sentry/types（v9 で非推奨、@sentry/core を使用）
  • @sentry/utils（v9 で非推奨、@sentry/core を使用）

 

これらのパッケージは現在も npm 上で解決されるため、インストール自体が壊れることはありません。しかし、メンテナンスは行われておらず、node_modules に不要な負担を追加します。もしこれらが含まれているなら、Sentry の設定は見直しが必要です。

 

 

セキュリティとパフォーマンス

新機能に関心がなくても、最新の状態を保つことでパッチ適用と軽量化の恩恵を受けられます。

セキュリティ

  • CVE-2023-46729：Next.js のトンネルルートの検証不足による SSRF リスク。v7.77.0 で修正されましたが、最新の v7.x を使っているユーザーのみが対象です。古い v7 に固定している場合は脆弱なままになります。
  • IP アドレス推測はデフォルトで無効化されました。v9 以降（v10.4.0 で完全適用）では、sendDefaultPii: true を設定しない限り、SDK はユーザーの IP アドレス推測を Sentry バックエンドに指示しません。デフォルトでプライバシー配慮となります。
  • fetchProxyScriptNonce は v9 で削除されました。SvelteKit のオプションは CSP 回避に関するセキュリティ懸念により廃止されています。
  • 推移的依存関係（fast-xml-parser、rollup、tar、nuxt）の CVE 修正は、最新のメジャーバージョン系にのみ適用されます。v7 に固定している場合、これらの修正は適用されません。

 

パフォーマンス

  • @sentry/browser のベースバンドル：gzip 圧縮で 26KB（v10）。ツリーシェイキングのフラグにより約 24.5KB まで削減可能。
  • v8 で ES5 ポリフィルが削除され、v9 で ES2020 が基準となりました。これにより、ネイティブ対応している環境ではトランスパイル後の出力が小さくなります。
  • v8 でレガシーパッケージ6つが削除、v9 でさらに2つが非推奨となりました。依存関係がシンプルになり、node_modules 内の重複も減少します。
  • ツリーシェイキング改善によりReplay バンドルは約20KB削減（v7.73.0+）。

 

 

AI アシスタントに任せる

Sentry のアップグレードや設定を手作業で行う必要はありません。Sentry は「エージェントスキル」を公開しています。これは、AI コーディングアシスタントに対して、プロジェクト内で Sentry を扱う方法を教えるための指示セットです。Claude Code、Cursor、GitHub Copilot、OpenAI Codex などで利用できます。

最新のスキルである sentry-sdk-upgrade は移行作業全体を処理できます。

以下4つのフェーズで構成されています。

Detect（package.json を読み取り、Sentry 設定を検出し、非推奨パターンを検索）
→ Recommend（変更内容を自動修正可能、AI支援、手動確認に分類）
→ Guide（ファイルごとに説明付きで変更を適用）
→ Cross-Link（ビルドが通ることを検証し、有効化できる新機能を提案）

v7→v8、v8→v9、v9→v10 の移行に対応しています。

以下のコマンド1つでスキルをインストールできます。

 

では、アシスタントに作業を任せてください。
 

依頼内容

実行される内容

「Sentry SDK を v10 にアップグレードして」

現在のバージョンを検出し、非推奨 API をスキャンし、ファイルごとにコードを移行

「React アプリに Sentry を追加して」

エラーバウンダリとルーティングを含めて @sentry/react をセットアップ

「Sentry のロギングを有効にして」

Sentry.init() に Structured Logs を設定

「OpenAI の呼び出しをモニタリングして」

openAIIntegration() を追加し、トークンのトラッキングを有効化

「パフォーマンスモニタリングを追加して」

使用しているフレームワークに適したインテグレーションでトレーシングを設定

「最近の Sentry エラーを修正して」

Sentry から issue を取得し、修正を適用

アップグレードスキルは特に v7→v8 の移行で有用です。この移行では API の変更数が多いものの、その多くは機械的なリネームです。アップグレード後に、Session Replay、Logs、AI Monitoring といった新機能の設定も、アシスタントが代わりに行うことができます。設定を自分で調べる必要はありません。スキルはバージョン管理されており、dotagents を使ってリポジトリにコミットできるため、チーム全員が同じ設定を利用できます。

 

 

でもアップグレードは大変

作業量について正直に整理したうえで、ツールについて説明します。

v7 から v8 への移行が最も大きな変更です。パフォーマンスモニタリング API は OpenTelemetry ベースに書き直されました。トレーシングの概念も変わり（トランザクションはスパンへ）、Node.js の自動インストルメンテーションでは import の順序が重要になり、6つのパッケージが統合されました。一般的なアプリで数時間、カスタムインストルメンテーションを含む複雑な構成ではさらに時間がかかります。

v8 から v9 は中程度です。Hub、getCurrentHub()、configureScope() などの非推奨 API が削除されました。v8 で表示されていた非推奨警告に対応済みであれば、移行は比較的スムーズです。主な条件は Node.js 18 以上です。

v9 から v10 は実際にはかなり容易です。破壊的変更は8件で、主に内部的なものです。CHANGELOG にも「最小限の破壊的変更」と記載されています。内部で OpenTelemetry v2 に更新され、FID は削除（INP に置き換え）、いくつかの内部 API が整理されました。

各移行では事前に警告が表示されます。API は削除される前に、1つのメジャーバージョン分にわたってコンソール警告付きで非推奨化されるため、突然使えなくなることはありません。

sentry-sdk-upgrade のエージェントスキルを使えば、これらの多くを自動化できます。grep によって非推奨パターンを検出し、機械的なリネームを自動で適用し、複雑な変更については説明付きで進めてくれます。特に v7→v8 の移行では、多数のインテグレーションコンストラクタやスコープ API を手作業でリネームする必要がありますが、このスキルが煩雑な部分を処理するため、カスタムインストルメンテーションの書き直しといった本質的に難しい部分に集中できます。

各破壊的変更について、Before / After のコード付き移行ガイド

 

 

実践的なアップグレード手順

  1. まずは現状を確認します。

  2. AI アシスタントにこれを任せるか、移行ガイドを確認してください。Sentry のエージェントスキルをインストールしている場合は、「Sentry SDK を v10 にアップグレードして」とアシスタントに伝えれば、バージョンを検出し、非推奨 API をスキャンし、ファイルごとに移行を進めてくれます。そうでない場合は、docs.sentry.io にある該当バージョンの移行ガイド（v7→v8、v8→v9、v9→v10）を確認してください。

  3. もし2つ以上前のメジャーバージョンを使用している場合は、1つずつ順番にアップグレードしてください。v7 から v10 へ1つの PR でまとめて移行すると、原因の分かりにくいエラーが発生しやすくなります。まず v7→v8、検証、その後 v8→v9、と段階的に進めます。

  4. 最初はコア SDK のアップグレードから始め、その後で新機能を段階的に有効化します。まずは基本のアップグレードを安定させ、その後 Session Replay、次に Logs と追加していきます。それぞれは独立した init() オプションまたはインテグレーションなので、すべてを一度に導入する必要はありません。あるいはエージェントスキルをインストールし、AI コーディングアシスタントに設定を任せることもできます。

  5. 移行中は debug: true を使用してください。

これにより、設定の問題、ドロップされたイベント、インテグレーションの問題が即座に明らかになります。

 

 

ギャップを埋める

SDK チームは毎週リリースを行っています。リリースを見送るたびに、現在の状態と利用可能な機能との距離は広がっていきます。@sentry/node の週間インストールのうち 480 万がいまだに v7 にとどまっていることからも、これは小さな問題ではないことが分かります。そのため私たちは、移行ガイドやエージェントスキルに大きく投資してきました。中でも sentry-sdk-upgrade スキルは、移行作業そのものを代行できるように設計されており、前に進むための道筋を明確にしています。

1つのバージョンアップから始めてください。移行ガイドを読み、そのギャップを埋めましょう。

 

 

SDK アップグレード FAQ

 
■ 自分が使っている Sentry SDK のバージョンはどう確認できますか？

プロジェクト内で次のコマンドを実行してください。

npm ls @sentry/react @sentry/nextjs @sentry/vue @sentry/angular @sentry/sveltekit @sentry/node 2>/dev/null | grep @sentry
 
出力には、各パッケージのインストールされているバージョンが表示されます。

 

■ @sentry/* パッケージはすべて同時にアップグレードする必要がありますか？

はい。すべての @sentry/* JavaScript パッケージは同じバージョンで管理されているため、@sentry/react が v8、@sentry/node が v7 のようにバージョンを混在させると問題が発生します。まとめてアップグレードしてください。

 

■ アップグレード時に Sentry.init() の設定を変更する必要がありますか？

場合によります。init() のシグネチャ自体はバージョン間で概ね安定していますが、一部のオプションは名称変更または削除されています。特に大きな変更は v8（パフォーマンスモニタリング関連のオプションが大きく変更）と v9（非推奨の init オプションが削除）です。移行ガイドには、すべての破壊的変更について Before / After の例が含まれています。

 

■ アップグレードすると、既存のエラーデータやダッシュボードに影響はありますか？

いいえ。SDK のアップグレードは、すでに Sentry に送信されたデータには影響しません。既存の Issue、イベント、ダッシュボードはそのまま維持されます。

 

■ 基本的なエラートラッキングしか使っていない場合でも、アップグレードする価値はありますか？

はい、理由は2つあります。1つ目はセキュリティです。推移的依存関係のセキュリティ修正は、最新のメジャーバージョン系にしか適用されません。古いバージョンを使っている場合、それらの修正は適用されません。2つ目はパフォーマンスです。新しいバージョンのほうが軽量です。v10 のブラウザ向けベースバンドルは gzip 圧縮で 26KB であり、v8 では ES5 ポリフィルが削除されています。同じエラートラッキングでも、より小さなサイズで利用できます。

 

 

Original Page: You’re probably overdue for a Sentry SDK upgrade

 

 



IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談は「お問い合わせ」からお気軽にお問い合わせください。

 

シェアする

Recent Posts

;

Follow us:

X-twitter

Follow us:

X-twitter