コンテンツにスキップ

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 です。この場合、圧縮パッケージを解凍した後のディレクトリ構造は次のようになります:

sourcemap.zip
└──static/
    └── js
    └── app.7fb548e3d065d1f48f74.js.map

変換後の error_stack_source:

ReferenceError
  at a.hideDetail @ webpack:///src/components/header/header.vue:94:0
  at a.showDetail @ webpack:///src/components/header/header.vue:91:0
  at <anonymous> @ webpack:///src/components/header/header.vue:101:0

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/<ビルドタイプ>/ にあります。.so ファイルは、CMake でプロジェクトをコンパイルする場合は <プロジェクトフォルダー>/<Module>/build/intermediates/cmake/debug/obj/ に、NDK でコンパイルする場合は <プロジェクトフォルダー>/<Module>/build/intermediates/ndk/debug/obj/(デバッグビルド)または <プロジェクトフォルダー>/<Module>/build/intermediates/ndk/release/obj/(リリースビルド)にあります。

変換の効果は次のとおりです:

変換前の 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 :

java.lang.ArithmeticException: divide by zero
at prof.wang.activity.TeamInvitationActivity.onClick$lambda-0(TeamInvitationActivity.java:1)
at java.lang.Thread.run(Thread.java:1012)

変換前の 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 ファイルと似ています):

sourcemap.zip
├── AFNetworking.framework.dSYM
│   └── Contents
│       ├── Info.plist
│       └── Resources
│           └── DWARF
│               └── AFNetworking
└── App.app.dSYM
    └── Contents
        ├── Info.plist
        └── Resources
            └── DWARF
                └── App

React Native の sourcemap には、ネイティブ iOS、Android、js の各部分が含まれ、合計 3 種類の source map があります。

ネイティブ iOS および Android の sourcemap の取得方法は、対応するパッケージング手順の取得方法を参照してください。

js 部分の sourcemap の取得方法は次のとおりです:

Android のソースマップはデフォルトで有効です。ソースマップファイルは android/app/build/generated/sourcemaps/react/release/index.android.bundle.map にあります。

iOS でソースマップの生成を有効にするには、追加の設定が必要です。Xcode を開き、ビルドフェーズの「Bundle React Native code and images」を編集します。他のエクスポート項目の上に、必要な出力パスを指定した SOURCEMAP_FILE エントリを追加します。

set -e
#  ソースマップを出力
export SOURCEMAP_FILE="./main.jsbundle.map";

Hermes を使用する場合、React Native <0.71

set -e
#  ソースマップを出力
export SOURCEMAP_FILE="./main.jsbundle.map";
#  React Native 0.70 で Hermes を使用する場合は USE_HERMES を true に設定する必要があります。設定しないとソースマップが生成されません。
export USE_HERMES=true 

# スクリプトの残りの部分は変更しないでください

# React Native(0.69、0.71)で Hermes を使用する場合
# 以下の行を追加して、パッケージャーとコンパイラのソースマップを 1 つのファイルに合成します
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
    # RN 0.70 より前では、スクリプト名は 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 にパッケージングします。

// Android
sourcemap.zip
├── js/
    ├── index.android.bundle.map
└── android/
    ├── mapping.txt
    ├── armeabi-v7a/
    │   ├── libgameengine.so
    │   ├── libothercode.so
    │   └── libvideocodec.so
    └── arm64-v8a/
        ├── libgameengine.so
        ├── libothercode.so
        └── libvideocodec.so    
// iOS
sourcemap.zip
├── js/
    ├── main.jsbundle.map 
└── ios/
    ├── AFNetworking.framework.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── AFNetworking
    └── App.app.dSYM
        └── Contents
            ├── Info.plist
            └── Resources
                └── DWARF
                    └── App

ソースマップの可視化ツール(source-map-visualization など)を使用して、ファイルが利用可能かどうかを検証できます。

アップロード方法

現在、以下の 3 種類の SourceMap アップロード方法をサポートしています:

  • フロントページでのアップロード:SourceMap ファイルの手動アップロードと削除に適しています。
  • スクリプトによるアップロード:パブリックネットワーク DataWay 環境での自動アップロードに適しています。
  • ビルド段階のプラグインによるアップロード:Web プロジェクトがパッケージング段階で SourceMap を自動アップロードする場合に適しています。

フロントページでのアップロードと削除

パッケージングの設定が完了したら、フロントページの [RUM] > [アプリケーションリスト] > [アップロードするアプリの右上にあるその他のアイコンをクリック] > [SourceMap] に移動して、ファイルのアップロードと削除を行うことができます。現在のアカウントに「編集」以上の権限があることを確認してください。

アップロードと削除は、アプリケーションが属するワークスペース内で操作し、現在のワークスペースのみを選択してください。ワークスペースをまたぐ読み取り専用状態では、これらの設定エントリは提供されません。詳しくはワークスペースをまたぐクエリの説明を参照してください。

🔍 欄の下に、アップロード済みのファイル名とアプリケーションタイプが表示されます。ファイル名を入力して検索できます。 をクリックすると、現在のファイルを削除できます。

アップロード時の注意事項:

  1. ファイルサイズは 500M を超えることはできません。
  2. ファイル形式は .zip である必要があります。
  3. 圧縮パッケージを解凍した後のファイルパスが error_stack 内の URL のパスと一致していることを確認してください。
  4. 複数のファイルを同時にアップロードすることはできません。
  5. 同じ名前のファイルをアップロードすると上書きの確認プロンプトが表示されます。ご注意ください。

スクリプトによるアップロード

現在のアプリケーションがパブリックネットワーク DataWay の接続方式を採用している場合は、スクリプトを使用して OpenAPI 経由でパッケージング済みの sourcemap.zip ファイルをアップロードすることもできます。

詳細については、スクリプトによる SourceMap のアップロード を参照してください。

ビルド段階のプラグインによるアップロード

Web プロジェクトでは、フロントページでのアップロードとスクリプトによるアップロードに加えて、プロジェクトのビルド段階でプラグインを使用して SourceMap ファイルを自動アップロードすることもできます。

現在、以下の方法をサポートしています:

SourceMap のアップロードが完了すると、エラースタックの解析に使用できるようになります。

フィードバック

このページは役に立ちましたか?