すべての変数と関数名を含むソースコードが含まれていないスタック・トレースは、開発者が問題の根本原因を分析することを困難にさせます。
Sentry には、根本原因分析において開発者を支援する重要な機能があります。
Sentry では、ソースマップをアップロードすることができます。
これにより、元のソースコードにマップバックすることができ、コード内の問題の原因をより簡単に理解することができます。しかし、Sentyにソースマップをアップロードすることは困難です。
このガイドでは、ソースマップのアップロードを試みたもののエラーが表示されてしまう場合の対処方法をご説明します。
最も一般的なアップロードの問題を解決するために、再確認すべき事項やベストプラクティスについて詳しくご紹介します。
まだソースマップをアップロードしていない場合は、以下の1行のコードからプロセスを開始しましょう。
npx @sentry/wizard@latest -i sourcemaps
Sentryのソースマップの使い方
スタックトレースにオリジナルのソースコードを表示するには、Sentry はイベントペイロード内のスタックトレースを、そのリリースまたはビルド用にアップロードされたソースマップと照合する必要があります。
そのために、Sentry は「Debug IDs」と「release + abs_path」に基づく2つの照合方法を提供します。上記のコマンドでウィザードを実行すると、どの方法があなたのアプリに有効かを判断するのに役立ちます。
ウィザードを実行してアップロードした後、どの方法を使用しているかを確認することができます。
設定 > プロジェクト > [プロジェクト名] > ソースマップページから、アップロードしたファイルにアクセスすることで確認できます。バンドルを開き、ファイル名の下に Debug ID があるか確認します。
デバッグIDが表示されていれば、現在デバッグIDが設定されているということになります。
デバッグIDが表示されない場合は、リリース+abs_pathマッチングに設定されているということになります。
Sentryでは、より簡単にセットアップするために、Debug IDの使用を推奨しています。
release + abs_pathマッチングを使用している場合でも心配ありません。このアップロードプロセスのデバッグ方法についてもご説明します。
デバッグIDアップロードエラーの修正
デバッグIDは、ソースマップをアップロードするための推奨される方法です。これは release + abs_path アプローチの欠点を無くしたものです。Debug IDのサポートを追加することで、リリースを作成する必要がなくなります。Sentry はパス（信頼性に欠ける可能性がある）に依存するのではなく、Debug ID で圧縮されたソースとソースマップのペアを一意に識別しバインドします。これにより、Sentry はパスを確認することなく、最小化されたソースと対応するソース マップを識別することができます。
以下は、デバッグIDを使用したソースマップ・アップロード・エラーをデバッグするためのトラブルシューティング・チェックリストです。
1. SDKバージョンをアップグレードする： SDKがデバッグIDを使用できることを確認してください。issueの詳細ページの下部に、イベントが送信されたSDKが表示されます。
- 『JavaScript SDKのバージョン ≥ 7.56.0』である必要があります。
- デバッグ ID はまだすべての JavaScript SDK でサポートされていません。Next.jsやSvelteKitなど、レガシーなバンドルプラグインを使用しているSDKには互換性がありません。React Native もまだサポートされていません。
2. Debug ID インジェクション ツールを確認する： 開発途中の成果物にDebug ID を注入できることを確認してください。Sentry にアップロードするために使用しているツールが必要であるためです。デバッグ ID を注入できるのは、『sentry-cli >2.17.0』または『JavaScript Bundler Plugins >2.0.0』だけです。Github Actions release プラグインや Netlify プラグインなどの他ツールは Debug ID を挿入できません。
- sentry-cliを使用している場合、ソースマップウィザードがpackage.jsonにinjectコマンドとuploadコマンドを正しく追加しているか再確認してください。
- アップロードコマンドを実行するには、orgスラッグ、プロジェクト、認証トークンが必要です。ファイルが正しくアップロードされているか、ログを再確認してください。
3. イベントペイロード内のデバッグIDをチェックする： イベントペイロードの一部として、Debug ID が Sentry に送信されていることを確認します。これを行うには、イベントの JSON ファイル内の debug_meta キーを検索します。
- 一般的にスタック・トレースには、各ファイルに固有のIDがあります。
- debug_idは、一致するソースマップ・デバッグIDが見つかったかどうかに関係なく、JSONに記載されます。
- イベントの JSON に debug_meta キーがない場合、注入後のソース・ファイルをデプロイしていない可能性があります。イベントに ID が存在するためには、アプリをデプロイする前に Debug ID を注入する必要があります。
4. 一致するデバッグIDファイルを確認： イベントが送信される前に、一致するデバッグ ID ファイルがアップロードされていることを確認します。JSONからdebug_idをコピーし、アップロードされたアーティファクトで検索することで確認してください。
- JavaScriptバンドラープラグインを使用している場合、ファイル名はデバッグIDに置き換えられます。
- プロジェクトのソースマップページでデバッグIDを検索すると、特定のデバッグIDを持つバンドルが返されます。
5. イベントの前にソースマップをアップロードする： issueは一度処理されると、再度処理されることはありません。もし処理後にソースマップをアップロードした場合、スタック・トレースが更新された古いイベントが表示されることはないためご注意ください。
Release + abs_pathのアップロードエラーの修正
release + abs_pathを使用してソースマップをアップロードしている場合、ソースマップアップロードエラーの原因になっている可能性のある一般的な設定ミスのチェックリストを以下に示します。
1. リリースとdist： イベントペイロードのreleaseとdistの値が、アップロードされたものと一致しているかどうかを確認しましょう。これらの値の不一致は、ソースマップが適用されない最も起きやすい原因です。イベントのreleaseとdistの値が、アップロードされた成果物のreleaseとdistの値と一致していることを確認してください。
- イベントのJSONファイル、問題の詳細ページの上部、またはプロジェクトのソースマップページにあるreleaseタグとdistタグを確認してください。
issueの詳細ページ
ソースマップのページ
2. ファイルパスの一致を確認する： スタックトレースの abs_path がアップロードされたソースマップのパスと一致していることを確認してください。パスの不一致は、ソースマップが正常に動作しない原因として頻出します。
- これを確認するには、JSONファイルを開いてください。以下の例では、~は任意のプロトコルとホスト名に一致します。この場合『http://localhost:3000/』と一致するということになります。
パスがSentryにアップロードされたものと一致しているかどうかを確認するには、プロジェクトのソースマップページに移動し、最新のアーティファクトを選択します。『ARTIFACT』列の下にパスが表示されます。
一致
Assetsフォルダがない
3. 正しいソースマップのURLを確認する： ソースファイルがマップファイルを正しく指していることを確認しましょう。スタックトレースがソースファイルと一致するだけでなく、ソースファイルからマップファイルへ正しく参照づける必要があります。ソースファイルを開き、 //# sourceMappingUrl のコメントがマップファイルを正しく指していることを確認してください。上の例では、コメントは次のようになります
//#sourceMappingURL=index-5e0ef25e.js.map. 4. イベントの前にソースマップをアップロードする： 一度処理されたissueは、再度処理されません。つまり、新しくアップロードされたソースマップで古いイベントを再処理することはないということです。ご注意ください。
一般的なトラブルシューティング
ソースマップをDebug IDでアップロードする場合でも、release + abs_pathでアップロードする場合でも、以下の点に注意してください。
- 行番号と列番号だけがマッピングされ、フレームのみが存在し、表示するコードがない場合、マップファイルにそのフレームのsourcesContentがないことを意味します。
多くの場合、このようなことが起こるのは、そのコードのセクションがアプリの外部からのものである場合です。このようなフレームを除外するために Stack Trace Rules を設定することで解決できます。Sentry はこのようなフレームをグループ化の対象から除外するようになります。 - すべてのフレームが、すでにあなたのアプリから正しい行番号と列番号とファイル名を表示しているにも関わらず、コードでマッピングされていない場合、Sentryに送信されたイベントはすでに他の何かによって解決されている可能性があります。他のツールでスタックトレースを解決した場合、Sentryはそれが解決されたことを検知できません。これを行うツールの例として、source-map-supportがあります。
- Sentryが間違ったコードにマッピングしていると思われる場合は、Sentryにアップロードする前にローカルでマップが解決していることを確認してください。source-map-cli などのツールを使ってマップをテストできます。
まとめ
ソースマップの統合エラーのデバッグには多くの労力を要しますが、JavaScriptプロジェクトで読み取り可能なスタックトレースを持つことは導入する価値があります。ソースマップを使えるようにすることは、デバッグの効率とエラーの根本的な原因を理解するためのゲームチェンジャーになります。ソースコードを可視化することで、一見解決が不可解に見えるプロダクションエラーが、修正すべき簡単なバグに様変わりします。
プロジェクトはそれぞれ異なるため、ソースマップのアップロードエラーを万事解決する魔法のような方法はありません。Debug IDを使用している場合でも、release + abs_pathを使用している場合でも、上記のチェックリストの通りに従うことで、アップロードエラーを解決できる可能性は十分にあります。しかし、その他のソースマップの謎に遭遇した場合は、遠慮なくhttp://sentry@ichizoku.io. までご連絡ください。
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談はこちらのフォームからお気軽にお問い合わせください。
