【ITニュース解説】Sentry Source Maps for a Self-Hosted Next.js Standalone Build

ウェブアプリケーションを開発し、本番環境で動かすとき、予期せぬエラーは必ず発生する。その際、エラーが発生したことを知るだけでなく、それが「なぜ」「どこで」起きたのかを正確に把握することが、問題を解決するために非常に重要になる。しかし、本番環境にデプロイされるコードは、通常、ファイルサイズを小さくしたり処理速度を速めたりするために「ミニファイ（Minify）」という処理が施される。この処理によって、元々分かりやすかったコードは「chunk-a1b2c3.js:1:48213」のように、人間にはほとんど意味不明な文字列になってしまう。これでは、何が壊れたのか、どこで壊れたのか、なぜ壊れたのかを突き止めることは不可能に近い。

ここで登場するのが「Source Map（ソースマップ）」と「Sentry（セントリー）」だ。Source Mapは、ミニファイされたコードを元の開発段階のコード（例えばlib/foo.ts:42のようなファイル名と行番号）に「逆変換」するための情報を持つファイルだ。そしてSentryは、ウェブアプリケーションで発生したエラーを自動的に収集し、管理するためのサービスである。Source MapをSentryにアップロードすることで、ミニファイされたエラーメッセージも、Sentry上で元の開発コードの正確な場所として表示され、開発者はすぐに問題の原因箇所を特定できるようになる。

しかし、Next.jsのようなフレームワークを使ってアプリケーションを構築し、それを自分で管理するサーバーにデプロイする場合（「自己ホスト型」と呼ぶ）、このSource Mapの扱いに特有の課題が出てくる。Vercelのようなクラウドサービスを利用している場合は、Sentryとの連携が自動で行われ、Source Mapのアップロードも任せられることが多い。だが、自分でサーバーを用意し、Next.jsの「Standaloneビルド」を使ってデプロイする場合、これらの自動化された仕組みは存在しない。開発者自身がSource Mapの生成、Sentryへのアップロード、そして非常に重要なセキュリティ対策として、本番環境のビルド成果物からSource Mapを削除する、という一連の処理を全て手動で設定する必要がある。Source Mapは元のコードを復元できる情報なので、もしこれがブラウザからアクセスできる場所に公開されてしまうと、アプリケーションの内部ロジックが外部に漏れてしまう危険性があるからだ。

具体的に、Next.jsのStandaloneビルド環境でSentryとSource Mapを適切に設定する方法を見ていこう。まず、Sentryの公式SDKである@sentry/nextjsをプロジェクトに導入する。Next.jsアプリケーションは、サーバーサイド（Node.js環境）とエッジ環境（Edge Runtime）という異なる実行環境で動作する部分があるため、それぞれでSentryの初期化が必要となる。

この初期化は、プロジェクトのルートに配置するinstrumentation.tsというファイルで行う。このファイルでは、process.env.NEXT_RUNTIMEという環境変数を使って、Node.js環境とEdge Runtime環境のどちらで実行されているかを判断し、それぞれに合わせたSentryの設定ファイルを動的に読み込む。これにより、不要なコードが各環境のバンドルに含まれるのを防ぐことができる。

instrumentation.tsには、onRequestErrorという特別なエクスポートも設定する。これはNext.jsフレームワークが提供する機能で、リクエスト処理中に発生したエラーを捕捉するフックとなる。このフックにSentryのエラーキャプチャ関数を連携させることで、Next.jsが内部的に処理するようなリクエスト関連のエラーも確実にSentryに送ることができる。この設定を忘れると、Sentryのエラー数が少なすぎて、何か見落としているのではないかと疑う原因になる。

Sentryの初期化設定ファイル（sentry.server.config.tsやsentry.edge.config.tsなど）では、Sentryにイベントを送るためのDSN（Data Source Name）を設定する。このDSNにはSentryのプロジェクトが作成されたリージョン（例: .ingest.de.sentry.ioはドイツ、EUリージョン）が含まれており、プロジェクトの実際のリージョンと一致している必要がある。もしDSNのリージョンがプロジェクトのリージョンと異なると、エラーイベントはSentryに送信されず、原因不明のままイベントが消失してしまうので注意が必要だ。

さらに、Sentryのサンプリングレート（tracesSampleRate）を設定する。本番環境では全てのイベントを送ると費用がかさむため、例えば10%だけを収集するように設定し、開発環境では全てを収集するようにする。また、includeLocalVariables: trueを設定すると、エラー発生時のローカル変数の値もSentryに記録されるため、「undefinedのプロパティxを読み取れません」といった抽象的なエラーも、どの変数がundefinedだったのかを具体的に特定できるようになる。ただし、sendDefaultPii: true（個人を特定できる情報を含める）のような設定は、プライバシーポリシーと照らし合わせて慎重に判断する必要がある。

リクエストの処理中に発生するエラーだけでなく、アプリケーションのプロセス全体に影響を与えるような深刻なエラーも捕捉する必要がある。例えば、バックグラウンドで実行される処理で発生した未捕捉の例外（uncaughtException）や、awaitされなかったPromiseの拒否（unhandledRejection）などだ。これらはリクエストフローとは関係なくNode.jsプロセスをクラッシュさせる可能性がある。これらを捕捉するために、Node.js環境専用のinstrumentation.node.tsファイルを作成し、process.onイベントリスナーを使ってSentryにエラーを報告するよう設定する。このファイルはNode.js環境特有の機能を使うため、instrumentation.tsでNode.js環境の場合のみ読み込まれるようにする。

次に、Source Mapのアップロードと削除を行うビルドステップの設定が重要だ。Next.jsの設定ファイル（next.config.ts）を@sentry/nextjsが提供するwithSentryConfigでラップする。このwithSentryConfigは、Next.jsのビルドプロセスにSentryのプラグインを組み込む。このプラグインは、next buildコマンドの実行中にSource Mapを生成し、設定で指定されたSentryの組織とプロジェクトにアップロードし、さらに、ブラウザに公開されるクライアント側のビルド成果物からSource Mapファイルを安全に削除するという三つの重要な処理を自動的に実行する。これにより、Sentryでは可読性の高いエラーログが得られる一方で、アプリケーションがSource Mapを外部に漏洩する心配がなくなる。

Source MapをSentryにアップロードするには、SENTRY_AUTH_TOKENという認証情報が必要になる。これはSentryプロジェクトへの書き込み権限を持つ非常に重要な情報であり、ソースコードリポジトリには決してコミットせず、CI/CD環境のシークレット変数として安全に管理する必要がある。

また、tunnelRoute: "/monitoring"のような設定は、Sentryへのイベント送信をアプリケーション自身のドメイン経由で行うためのものだ。アドブロッカーや厳格なコンテンツセキュリティポリシー（CSP）が、Sentryの直接の通信をブロックしてしまうことがあるため、アプリケーションのドメインをトンネルとして利用することで、イベントが確実にSentryに届くようにできる。

Standaloneビルドの場合、Source Mapのアップロードと削除のタイミングは非常に重要だ。next buildが実行されるビルド環境でSENTRY_AUTH_TOKENが利用可能でなければならない。そして、このビルドステップでSource Mapのアップロードと成果物からの削除が完了した後、そのクリーンなビルド成果物だけがコンテナにコピーされ、デプロイされるべきである。ビルドとデプロイのプロセスにおいて、この順序が守られることが、Source MapのセキュリティとSentryでの可読性を両立させる鍵となる。

設定が全て完了したら、それが本当に意図通りに機能しているか検証することが不可欠だ。簡単な方法として、デプロイされたアプリケーションに一時的なAPIエンドポイント（例: /api/debug-sentry）を追加し、そのエンドポイントがアクセスされると意図的にエラーを発生させるようにする。そして、そのエンドポイントにアクセスし、Sentryでエラーイベントが次のような状態になっているかを確認する。

まず、エラーイベントがSentryに到達しているかを確認する。もし到達していなければ、前述のDSNのリージョンが一致しているか、instrumentation.tsの設定が正しいかを確認する。次に、エラーのスタックトレースがミニファイされた「chunk-a1b2c3.js」のような表示ではなく、「app/api/debug-sentry/route.ts」のように元のファイル名と行番号で表示されているかを確認する。もしミニファイされたままであれば、Source Mapのアップロードが失敗している可能性が高いので、SENTRY_AUTH_TOKENの確認やCI/CDのログでアップロードエラーを探す必要がある。さらに、SentryのリリースIDがデプロイされたコードとSource Mapで一致しているかを確認する。これが異なると、「Source Mapは見つかったが、対応するリリースがない」というメッセージが表示され、スタックトレースが正しく解決されない場合がある。

最後に、ブラウザの開発者ツールを開き、ネットワークタブで/_next/staticパスから.mapファイルが配信されていないことを確認する。もし.mapファイルが見つかるようであれば、Source Mapの削除ステップが機能していない可能性があり、これは通常、Source Mapのアップロードが失敗した結果であるため、アップロードの問題を解決すれば削除も正しく行われるようになるだろう。

この一連の設定は、自己ホスト型のNext.js Standaloneビルド環境において、サーバーサイドとクライアントサイドのエラーをSentryで可読性高く監視するための基本的な基盤となる。しかし、これは始まりに過ぎない。実際のトラフィックが増えるにつれて、より高度なサンプリング戦略、セッションリプレイ機能、パフォーマンスプロファイリング、リリース情報の自動連携など、さらに多くの監視機能をSentryに統合していくことで、より堅牢なシステム運用が可能になる。

自己ホスト環境で、本番環境のエラーを正確にデバッグできる体制を整えるのは手間がかかる作業だが、一度正しく設定してしまえば、将来発生するであろう数多くの問題を迅速に解決するための強力な武器となる。Sentry、Source Map、ログ収集、トレーシングといった要素を適切に組み合わせることで、アプリケーションの安定性と信頼性を大きく向上させることができるのだ。