Skip to content

SourceMap Configuration

Sourcemap (source code mapping) is used to map the compressed code in the production environment back to the original source code. RUM supports this source file information mapping by zipping and uploading the corresponding symbol table files, which can automatically transform the reported error Metrics data.

Zip Package Preparation

Compress the .map files generated after webpack obfuscation and compression of js files into a zip package. It must ensure that the file paths after decompressing this package are consistent with the URL paths in the error_stack. For example, the following 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

The path that needs conversion is /static/js/app.7fb548e3d065d1f48f74.js, and its corresponding sourcemap path is /static/js/app.7fb548e3d065d1f48f74.js.map. Therefore, the directory structure after decompressing the zip package should be as follows:

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

The converted 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

The packaging method is basically the same as Web.

There are currently two types of sourcemap files on Android: one is the mapping file generated by Java bytecode after being compressed and obfuscated by R8/Proguard, and the other is the unstripped .so file for C/C++ native code that retains the symbol table and debugging information. If your Android application contains both types of sourcemap files, you need to include both in the zip package. The directory structure after decompressing the zip package is similar to:

<app_id>-<env>-<version>/
├── 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

By default, the mapping file is located at <project folder>/<Module>/build/outputs/mapping/<build-type>/, and the .so files are located at <project folder>/<Module>/build/intermediates/cmake/debug/obj/ when using CMake for compilation, or at <project folder>/<Module>/build/intermediates/ndk/debug/obj/ (debug build) or <project folder>/<Module>/build/intermediates/ndk/release/obj/ (release build) when using NDK for compilation.

The conversion effect is as follows:

Original 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)

Converted 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)

Original 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)
...

Converted 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
...

On the iOS platform, the sourcemap file is a symbol table file with debugging information and has a .dSYM extension. Typically, it is in the same directory as the .app file after project compilation, as shown below:

$ 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

Note that XCode Release builds generate .dSYM files by default, while Debug builds do not. To enable .dSYM generation for Debug builds, set the following in XCode:

Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

When zipping, include the corresponding .dSYM files in the zip package. If your project involves multiple .dSYM files, all of them should be included in the zip package. Afterward, copy the zip package to the <DataKit installation directory>/data/rum/ios directory. The directory structure after decompressing the zip package is similar to (.dSYM files are essentially directories, similar to macOS executable .app files):

<app_id>-<env>-<version>/
├── AFNetworking.framework.dSYM
│   └── Contents
│       ├── Info.plist
│       └── Resources
│           └── DWARF
│               └── AFNetworking
└── App.app.dSYM
    └── Contents
        ├── Info.plist
        └── Resources
            └── DWARF
                └── App

React Native's sourcemap includes native iOS, Android, and js parts, totaling three source maps.

Refer to the respective packaging instructions for obtaining native iOS and Android sourcemap.

For the js part of the sourcemap:

Android source mapping is enabled by default. The source map file is located at android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

iOS requires additional configuration to enable source map generation. Open Xcode and edit the "Bundle React Native code and images" build phase. Add a SOURCEMAP_FILE entry with the desired output path above other export items.

set -e
# output source maps
export SOURCEMAP_FILE="./main.jsbundle.map";

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"

After obtaining the js sourcemap file, compress it along with the corresponding native sourcemap according to the format below.

// Android
<app_id>-<env>-<version>/
├── js/
    ├── main.jsbundle.map 
└── android/
    ├── mapping.txt
    ├── armeabi-v7a/
    │   ├── libgameengine.so
    │   ├── libothercode.so
    │   └── libvideocodec.so
    └── arm64-v8a/
        ├── libgameengine.so
        ├── libothercode.so
        └── libvideocodec.so    

// iOS
<app_id>-<env>-<version>/
├── js/
    ├── main.jsbundle.map 
└── ios/
    ├── AFNetworking.framework.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── AFNetworking
    └── App.app.dSYM
        └── Contents
            ├── Info.plist
            └── Resources
                └── DWARF
                    └── App

You can use tools like source-map-visualization to verify the availability of the files.

File Upload and Deletion

After completing the configuration, users can directly upload and delete files via the front-end page.

Source Map Upload

Below the 🔍 bar, you can view the names and application types of uploaded files. You can search by entering the file name; clicking will delete the current file.

Upload Guidelines:

  1. File size cannot exceed 500M;
  2. File format must be .zip;
  3. Ensure that the file paths after decompressing the package match the URL paths in the error_stack;
  4. Do not upload multiple files simultaneously;
  5. Uploading files with the same name will result in an overwrite prompt, please note.

Additionally, Datakit collector configuration supports SourceMap transformation.

For more details, see SourceMap Transformation.

Feedback

Is this page helpful? ×