SourceMap Configuration¶
Sourcemap (Source Code Mapping) is used to map minified code in production environments back to the original source code. RUM supports mapping this source code file information by zipping and uploading the corresponding symbol table files. This enables automatic conversion of the reported error Measurement data.
Zip Package Packaging Instructions¶
Zip and package the .map files generated after webpack obfuscation and minification of js files. It is essential to ensure that the file path after extracting the zip package matches the URL path in the error_stack. Assuming 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 to be converted is /static/js/app.7fb548e3d065d1f48f74.js, and its corresponding sourcemap path is /static/js/app.7fb548e3d065d1f48f74.js.map. Therefore, the directory structure after extracting the corresponding zip package should be as follows:
The converted error_stack_source:
The packaging method is basically the same as for Web.
Android currently has two types of sourcemap files. One is the mapping file generated after Java bytecode is compressed and obfuscated by R8/Proguard. The other is the (unstripped) .so files for C/C++ native code compiled without removing symbol tables and debugging information. If your Android application contains both types of sourcemap files, you need to package both into the zip file. The directory structure after extracting the zip package should be similar to:
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
By default, the mapping file is located at: <project folder>/<Module>/build/outputs/mapping/<build-type>/. The .so files are located at: <project folder>/<Module>/build/intermediates/cmake/debug/obj/ when compiling the project with CMake, or at: <project folder>/<Module>/build/intermediates/ndk/debug/obj/ (debug compilation) or <project folder>/<Module>/build/intermediates/ndk/release/obj/ (release compilation) when compiling with NDK.
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 :
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
...
The sourcemap file on the iOS platform is a symbol table file with debugging information, with the .dSYM suffix. Generally, after project compilation, it is located in the same directory as the .app file, 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 compilation generates .dSYM files by default, while Debug compilation does not. The following corresponding settings need to be made in XCode:
Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File
When creating the zip package, package the corresponding .dSYM file(s) into the zip. If your project involves multiple .dSYM files, they all need to be packaged into the zip. The directory structure after extracting the zip package should be similar to the following (.dSYM files are essentially directories, similar to executable .app files on macOS):
React Native's sourcemap includes native iOS, Android, and js parts, totaling three types of source maps.
Refer to the corresponding packaging instructions for obtaining native iOS and Android sourcemap files.
The method to obtain the js part sourcemap is as follows:
Android source maps are enabled by default. The source map file is located at android/app/build/generated/sourcemaps/react/release/index.android.bundle.map.
iOS requires some 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 the other export items.
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, package it together with the native sourcemap corresponding to its build platform into a zip file according to the following format.
You can use source map visualization tools like source-map-visualization to verify file availability.
Upload Methods¶
Currently, the following three types of SourceMap upload methods are supported:
- Frontend Page Upload: Suitable for manually uploading and deleting SourceMap files.
- Script Upload: Suitable for automated uploads in public DataWay scenarios.
- Build Phase Plugin Upload: Suitable for automatically uploading SourceMap during the packaging phase of Web projects.
Frontend Page Upload and Deletion¶
After packaging configuration is complete, users can go to the frontend page [RUM] > [Application List] > [Click the more icon in the upper right corner of the target application] > [SourceMap] to perform file upload and deletion operations. Please ensure the current account has "Edit" or higher permissions.
Below the 🔍 search bar, you can view the names and application types of uploaded files. You can search by file name; click to delete the current file.
Upload Notes:
- File size must not exceed 500M.
- File format must be
.zip. - Ensure the file path after extracting the zip package matches the URL path in the
error_stack. - Cannot upload multiple files simultaneously.
- Uploading a file with the same name will trigger a replacement prompt. Please be cautious.
Script Upload¶
If the current application uses the public DataWay access method, you can also use a script to upload the packaged sourcemap.zip file via OpenAPI.
For more details, please refer to Script Upload SourceMap.
Build Phase Plugin Upload¶
For Web projects, besides frontend page upload and script upload, you can also automatically upload SourceMap files during the project build phase via plugins.
The following methods are currently supported:
After the SourceMap upload is complete, it can be used for error stack parsing.

