Symbolication
Explained here is how to symbolicate your crashes to get more details from stack traces.
Instabug needs your project's dSYM in order to be able to symbolicate crash reports from your app. If you are seeing a message saying "This crash is not symbolicated" on your Instabug dashboard, that means Instabug doesn't have your project's dSYM and won't be able to symbolicate crashes.
In this page, we will detail how you can find your dSYMs, upload your dSYMs, and what to do if you have __hidden in your stack traces.
Finding dSYMs
There are two types of dSYM files: required and optional.
Required dSYM files are used to symbolicate your application's frames. In the screenshot below, only the required dSYM is missing.
Optional dSYM files are used to symbolicate the frames belonging to any plugin or library you are using.
To find your project's dSYM, run the command shown to you on your Instabug dashboard.
mdfind "com_apple_xcode_dsym_uuids == your-UUID-here"
Uploading dSYMs
After you have located your project's dSYM, you can either upload it manually or by using the upload script included in the SDK.
Manually
- Compress the dSYM file you have located on your machine into a zip file.
- Go to Upload dSYMs in the Settings menu of your Instabug dashboard.
- Upload the compressed file.
Automatically
Instabug has a shell script that can automatically upload your project's dSYM during the build process. To use it, go to your project's Build Phases tab and add a new Run Script Build Phase, then add the following to it.
#- -- SCRIPT BEGIN - --
# SKIP_SIMULATOR_BUILDS=1
SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Instabug_dsym_upload.sh' | head -1)
if [ ! "${SCRIPT_SRC}" ]; then
echo "Instabug: err: script not found. Make sure that you're including Instabug.bundle in your project directory"
exit 1
fi
APP_TOKEN="YOUR-APP-TOKEN-HERE"
source "${SCRIPT_SRC}"
#- -- SCRIPT END - --
Make sure you replace YOUR-APP-TOKEN-HERE
with your actual app token (found under SDK Integration in the Settings menu of your Instabug dashboard.
If you're using Xcode 10, you will need to add the previous script to the Build > Post-actions.
Using API
Additionally, we have an API end point that you can use to upload your dSYMs directly from the console. The dSYMs must be uploaded as a zip file.
URL:
/api/sdk/v3/symbols_files
METHOD:
POST
PARAMS:
file
os (android, ios,,,)
application_token
Debug Builds
To enable crash symbolication for debug builds, you have to change your project's build settings to generate dSYM files for debug builds.
To do so, select your target in Xcode then go to Build Settings, search for Debug Information Format, and change its value to DWARF with dSYM File.
Bitcode-Enabled Apps
If your app build has Bitcode enabled, you will need to download dSYMs first from Xcode, then upload them to Instabug.
To upload dSYMs for Bitcode-enabled apps, follow these steps:
- In Xcode, select Window then Organizer.
- Under the Archives tab, select an archive with the app version you need to symbolicate crashes from.
- Click the Download dSYMs... button. Xcode will insert the
.dSYM
files into the selected archive. - View the archive by right-clicking on it in Xcode and selecting Show in Finder.
- Right-click on the archive and select Show Package Contents, then open the dSYMs directory.
- Compress all the
.dSYM
files you find in that directory and upload the archive to the Instabug dashboard.
__hidden in Stack Traces
If you have stack traces that contain frames that have __hidden
instead of a symbol name, this is because you did not share your app's symbols with Apple while uploading a build to iTunes Connect.
To make sure stack traces of crashes from your app do not contain any hidden symbols, always check Upload your app's symbols to receive symbolicated reports from Apple when uploading a new build.
With this option unchecked, dSYMs generated by iTunes Connect for apps that have Bitcode enabled will be obfuscated. To de-obfuscate those dSYMs, download them from iTunes Connect, then use the following command (substituting your archive and dSYM paths):
xcrun dsymutil -symbol-map ~/Library/Developer/Xcode/Archives/2017-11-23/MyGreatApp\ 11-23-17\,\ 12.00\ PM.xcarchive/BCSymbolMaps ~/Downloads/dSYMs/3B15C133-88AA-35B0-B8BA-84AF76826CE0.dSYM
Run this command for each dSYM file inside the dSYMs folder you downloaded from iTunes Connect. After that is complete, upload the updated dSYMs to Instabug to get fully symbolicated stack traces.
Updated about 5 years ago
After a crash has been desymbolicated and the fix is done, reach out to your affected users and let them know to update.