SourceMap 設定¶
Sourcemap(ソースコードマッピング)は、本番環境の圧縮コードを元のソースコードにマッピングするために使用されます。RUM はこのソースファイル情報のマッピングをサポートしており、対応するソースマップファイルを zip 圧縮してアップロードすることで、報告された error メジャーメントデータを自動的に変換できます。
Zip パッケージングの説明¶
js ファイルを webpack で難読化・圧縮して生成された .map ファイルを zip 圧縮してパッケージングする場合、解凍後のファイルパスが error_stack 内の URL のパスと一致している必要があります。次のような error_stack を例とします。
ReferenceError
at a.hideDetail @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:1037
at a.showDetail @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:986
at <anonymous> @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:1174
変換対象のパスは /static/js/app.7fb548e3d065d1f48f74.js であり、対応する sourcemap のパスは /static/js/app.7fb548e3d065d1f48f74.js.map です。この場合、圧縮パッケージを解凍した後のディレクトリ構造は次のようになります。
変換後の error_stack_source:
Web のパッケージング方法と基本的に同じです。
Android には現在 2 種類の sourcemap ファイルがあります。1 つは Java バイトコードが R8/Proguard によって圧縮・難読化されて生成される mapping ファイル、もう 1 つは C/C++ ネイティブコードのコンパイル時にシンボルテーブルとデバッグ情報が除去されていない(unstripped).so ファイルです。Android アプリにこの 2 種類の sourcemap ファイルの両方が含まれる場合は、パッケージング時に両方のファイルを zip パッケージに含める必要があります。zip パッケージを解凍した後のディレクトリ構造は次のようになります。
sourcemap.zip
├── mapping.txt
├── armeabi-v7a/
│ ├── libgameengine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── arm64-v8a/
│ ├── libgameengine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── x86/
│ ├── libgameengine.so
│ ├── libothercode.so
│ └── libvideocodec.so
└── x86_64/
├── libgameengine.so
├── libothercode.so
└── libvideocodec.so
デフォルトでは、mapping ファイルは <プロジェクトフォルダー>/<Module>/build/outputs/mapping/<build-type>/ に配置され、.so ファイルは CMake を使用してプロジェクトをコンパイルする場合は <プロジェクトフォルダー>/<Module>/build/intermediates/cmake/debug/obj/、NDK でコンパイルする場合は <プロジェクトフォルダー>/<Module>/build/intermediates/ndk/debug/obj/(debug コンパイル)または <プロジェクトフォルダー>/<Module>/build/intermediates/ndk/release/obj/(release コンパイル)に配置されます。
変換の効果は次のとおりです。
変換前の error_stack:
java.lang.ArithmeticException: divide by zero
at prof.wang.activity.TeamInvitationActivity.o0(Unknown Source:1)
at prof.wang.activity.TeamInvitationActivity.k0(Unknown Source:0)
at j9.f7.run(Unknown Source:0)
at java.lang.Thread.run(Thread.java:1012)
変換後の error_stack_source:
変換前の error_stack:
backtrace:
#00 pc 00000000000057fc /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_4+12)
#01 pc 00000000000058a4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_3+8)
#02 pc 00000000000058b4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_2+12)
#03 pc 00000000000058c4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_1+12)
#04 pc 0000000000005938 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_crash+112)
...
変換後の error_stack_source:
backtrace:
Abort message: 'abort message for ftNative internal testing'
#00 0x00000000000057fc /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_4+12)
xc_test_call_4
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:65:9
#01 0x00000000000058a4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_3+8)
xc_test_call_3
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:73:13
#02 0x00000000000058b4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_2+12)
xc_test_call_2
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:79:13
#03 0x00000000000058c4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_1+12)
xc_test_call_1
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:85:13
#04 0x0000000000005938 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_crash+112)
xc_test_crash
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:126:9
...
iOS プラットフォームの sourcemap ファイルは、.dSYM という接尾辞が付いたデバッグ情報を含むシンボルテーブルファイルです。通常、プロジェクトのコンパイル後、.app ファイルと同じディレクトリに配置されます。次のようになります。
$ ls -l Build/Products/Debug-iphonesimulator/
total 0
drwxr-xr-x 6 zy staff 192 8 9 15:27 Fishing.app
drwxr-xr-x 3 zy staff 96 8 9 14:02 Fishing.app.dSYM
drwxr-xr-x 15 zy staff 480 8 9 15:27 Fishing.doccarchive
drwxr-xr-x 6 zy staff 192 8 9 13:55 Fishing.swiftmodule
XCode の Release コンパイルではデフォルトで .dSYM ファイルが生成されますが、Debug コンパイルではデフォルトでは生成されないため、XCode で次のように設定する必要があります。
Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File
zip パッケージを作成する際は、該当する .dSYM ファイルを zip パッケージに含めます。プロジェクトに複数の .dSYM ファイルがある場合は、それらをすべて zip パッケージにまとめる必要があります。zip パッケージを解凍した後のディレクトリ構造は次のようになります(.dSYM ファイルは本質的にディレクトリであり、macOS の実行可能プログラム .app ファイルと同様です)。
React Native の sourcemap には、ネイティブ iOS、Android、および js 部分が含まれ、合計 3 種類のソースマップがあります。
ネイティブ iOS および Android の sourcemap の取得方法は、対応するパッケージングの説明の取得方法を参照してください。
js 部分の sourcemap の取得方法は次のとおりです。
Android のソースマップはデフォルトで有効です。ソースマップファイルは android/app/build/generated/sourcemaps/react/release/index.android.bundle.map にあります。
iOS でソースマップの生成を有効にするには、追加の設定が必要です。Xcode を開き、build phase の「Bundle React Native code and images」を編集します。その他のエクスポート項目の上に、必要な出力パスを持つ SOURCEMAP_FILE エントリを追加します。
With Hermes,React Native <0.71
set -e
# output source maps
export SOURCEMAP_FILE="./main.jsbundle.map";
# React Native 0.70,you need to set USE_HERMES to true if Hermes is used, otherwise the source maps won't be generated.
export USE_HERMES=true
# keep the rest of the script unchanged
# When React Native (0.69,0.71) and using Hermes
# add these lines to compose the packager and compiler source maps into one file
REACT_NATIVE_DIR=../node_modules/react-native
if [ -f "$REACT_NATIVE_DIR/scripts/find-node-for-xcode.sh" ]; then
source "$REACT_NATIVE_DIR/scripts/find-node-for-xcode.sh"
else
# Before RN 0.70, the script was named find-node.sh
source "$REACT_NATIVE_DIR/scripts/find-node.sh"
fi
source "$REACT_NATIVE_DIR/scripts/node-binary.sh"
"$NODE_BINARY" "$REACT_NATIVE_DIR/scripts/compose-source-maps.js" "$CONFIGURATION_BUILD_DIR/main.jsbundle.map" "$CONFIGURATION_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/main.jsbundle.map" -o "../$SOURCEMAP_FILE"
js の sourcemap ファイルを取得したら、ビルドプラットフォームに対応するネイティブの sourcemap と一緒に、以下の形式で zip パッケージにまとめます。
ファイルの有効性は、source-map-visualization などのソースマップ可視化ツールを使用して確認できます。
アップロード方法¶
現在、次の 3 種類の SourceMap アップロード方法をサポートしています。
- コンソールからのアップロード:SourceMap ファイルの手動アップロードと削除に適しています。
- スクリプトによるアップロード:パブリックネットワークの DataWay 環境での自動アップロードに適しています。
- ビルド段階のプラグインによるアップロード:Web プロジェクトでパッケージング段階に SourceMap を自動アップロードするのに適しています。
コンソールでのアップロードと削除¶
設定とパッケージングが完了したら、コンソールの [RUM] > [アプリリスト] > [アプリの右上にあるその他アイコンをクリック] > [SourceMap] に移動して、ファイルのアップロードと削除を実行できます。現在のアカウントに「編集」以上の権限があることを確認してください。
アップロードと削除は、アプリが所属するワークスペース内で実行し、現在のワークスペースのみを選択してください。ワークスペース間の読み取り専用状態ではこれらの設定導入口は提供されません。詳細はワークスペース間検索の説明を参照してください。
ファイルリストには、アップロード済みのファイル、環境、バージョン、最終アップロード日時が表示されます。環境でフィルタリングしたり、環境やバージョンを入力して検索したりできます。ファイルに対応する削除アイコンをクリックすると、そのファイルを削除できます。
アップロード時の注意事項:
- ファイルサイズは 500M を超えることはできません。
- ファイル形式は
.zipである必要があります。 - 圧縮パッケージを解凍した後のファイルパスが
error_stack内の URL のパスと一致していることを確認してください。 - 複数のファイルを同時にアップロードすることはできません。
- 同じ名前のファイルをアップロードすると上書き確認のプロンプトが表示されます。ご注意ください。
スクリプトによるアップロード¶
現在のアプリがパブリックネットワークの DataWay 接続方式を採用している場合は、スクリプトを使用して OpenAPI からパッケージ化された sourcemap.zip ファイルをアップロードすることもできます。
詳細は、スクリプトでの SourceMap アップロード を参照してください。
ビルド段階のプラグインによるアップロード¶
Web プロジェクトの場合、コンソールからのアップロードやスクリプトによるアップロードに加えて、プロジェクトのビルド段階でプラグインを使用して SourceMap ファイルを自動アップロードすることもできます。
現在、次の方法をサポートしています。
SourceMap のアップロードが完了すると、エラースタックの解析に使用できます。
自動クリーンアップ¶
SourceMap の自動クリーンアップでは、アプリと環境ごとに保持件数を設定でき、以前にアップロードされた SourceMap を自動的に削除して、手動でのメンテナンスを軽減できます。この機能はデフォルトでオフになっており、各ルールは現在のアプリで選択した環境にのみ適用され、他の環境には影響しません。
設定する前に、アプリが所属するワークスペースに移動し、現在のワークスペースのみを選択してください。管理導入口は コンソールでのアップロードと削除 を参照してください。
削除の影響
削除は元に戻せません。対象バージョンの新しいエラーおよび履歴エラーのソースコード復元に影響する可能性がありますが、元のエラーデータは保持されます。自動クリーンアップをオフにしたり、保持件数を増やしたりしても、削除済みのファイルは復元されません。有効にする前に、引き続き調査が必要なバージョンに対応する SourceMap を保持する必要があるかどうかを確認してください。
保持ルールの設定¶
- [RUM] > [アプリリスト] に移動し、対象アプリの右上にあるその他アイコンをクリックして、[SourceMap] を選択します。
- [自動クリーンアップ] をクリックし、設定する環境を選択します。
- [自動クリーンアップを有効にする] をオンにし、[最近アップロードされたものを保持] に保持件数を入力します。
- [クリーンアップ範囲をプレビュー] をクリックし、現在の件数、保持件数、削除予定件数、削除対象のバージョンを確認します。
- 調整が必要な場合は、[戻って修正] をクリックします。クリーンアップ範囲を確認したら、[自動クリーンアップを有効にすることを確認] をクリックします。
保持件数は以下のルールに従って集計されます。
- 同じアプリ、同じ環境、同じバージョンのファイルは 1 件としてカウントされます。
- すでに準備完了状態のファイルがあるバージョンのみがカウントされ、初回アップロード時に未準備または失敗したバージョンはカウントされません。
- 最終アップロード日時に基づいて最新の指定件数が保持され、保持件数を超えた古いアップロードバージョンはクリーンアップ範囲に入ります。
- その後、新しいファイルが準備完了になると、システムはルールに従って自動的にクリーンアップします。
たとえば、あるアプリの production 環境で保持件数を 5 に設定した場合、システムはその環境内で最近アップロードされた 5 件の SourceMap を保持し、他の環境のファイルはこのルールの影響を受けません。
クリーンアップ状態の確認¶
[自動クリーンアップ] ウィンドウの[最近のクリーンアップ]領域で、実行状態、削除済み、失敗、保留中の件数、および開始時間と完了時間を確認できます。[履歴を見る] をクリックすると、クリーンアップ記録をさらに確認できます。
自動クリーンアップの無効化¶
対応するアプリの SourceMap > 自動クリーンアップ に移動し、対象の環境を選択して、[自動クリーンアップを有効にする] をオフにし、ページの指示に従って保存します。
オフにすると以降の削除は停止しますが、実行中の個別の削除は完了する場合があります。削除済みのファイルは復元されません。

