SourceMap Configuration¶
SourceMap is used to map minified production code back to the original source code. RUM supports mapping source file information by packaging the corresponding symbol table files into a zip archive and uploading them. This allows automatic conversion of reported error measurement data.
Zip Packaging Instructions¶
Zip the .map files generated after webpack obfuscation and minification of JS files. The file path after decompression of the zip archive must match the URL path in error_stack. Assume 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 the corresponding sourcemap path is /static/js/app.7fb548e3d065d1f48f74.js.map. The directory structure after decompression of the zip archive should be as follows:
The converted error_stack_source:
The packaging method is essentially the same as for Web.
Android currently supports two types of sourcemap files: one is the mapping file generated after Java bytecode is compressed and obfuscated by R8/Proguard, and the other is the unstripped .so file for C/C++ native code compiled without stripping symbol tables and debug information. If your Android app includes both types of sourcemap files, both must be included in the zip archive. The directory structure after decompression of the zip archive is 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>/, and the .so files are located at: <project_folder>/<Module>/build/intermediates/cmake/debug/obj/ when compiled with CMake, or at <project_folder>/<Module>/build/intermediates/ndk/debug/obj/ (debug build) or <project_folder>/<Module>/build/intermediates/ndk/release/obj/ (release build) when compiled with NDK.
The conversion effect is as follows:
Before conversion 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)
After conversion error_stack_source:
Before conversion 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)
...
After conversion 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, suffixed with .dSYM. Generally, after the project is compiled, 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 builds generate .dSYM files by default, while Debug builds do not. You need to configure Xcode accordingly:
Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File
When packaging the zip, simply include the corresponding .dSYM file(s). If your project involves multiple .dSYM files, they must all be packaged together into the zip archive. The directory structure after decompression of the zip archive is similar to the following (a .dSYM file is essentially a directory, similar to the .app executable on macOS):
React Native's sourcemap includes the native iOS, Android, and JS parts, totaling three types of source maps.
For native iOS and Android source maps, refer to the packaging instructions for those platforms.
The JS source map can be obtained 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: Enabling source map generation requires additional configuration. Open Xcode and edit the "Bundle React Native code and images" build phase. Above the other export items, add a SOURCEMAP_FILE entry with the desired output path.
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 source map file, package it together with the native source maps corresponding to the build platform into a zip archive as follows:
You can verify the file availability using a source map visualization tool such as source-map-visualization.
Upload Methods¶
The following three methods for uploading SourceMap files are currently supported:
- Manual upload via the UI: Suitable for manually uploading and deleting SourceMap files.
- Script upload: Suitable for automated uploads in public DataWay scenarios.
- Build-time plugin upload: Suitable for automatic upload of SourceMap files during the build phase of Web projects.
Manual Upload and Deletion¶
After packaging, you can go to the UI page [Real User Monitoring (RUM)] > [Application List] > [Click the More icon in the upper right corner of the application] > [SourceMap] to upload and delete files. Make sure your account has "Edit" permissions or higher.
Below the 🔍 field, you can view the uploaded file names and their application types. You can enter a file name to search; click to delete the current file.
Upload Notes:
- The file size must not exceed 500 MB.
- The file format must be
.zip. - Ensure that the file path after decompression of the zip archive matches the URL path in
error_stack. - Multiple files cannot be uploaded at the same time.
- Uploading a file with the same name will prompt an overwrite confirmation.
Script Upload¶
If your application uses the public DataWay access method, you can also upload the packaged sourcemap.zip file via script using the OpenAPI.
For more details, see Script Upload of SourceMap.
Build-time Plugin Upload¶
For Web projects, in addition to manual upload via the UI and script upload, you can also automatically upload SourceMap files during the project build phase using plugins.
The following methods are currently supported:
Once the SourceMap is uploaded, it can be used for error stack resolution.

