Crash Log Symbolication Troubleshooting Guide
If your crash logs are not being symbolicated, or partially symbolicated, please use the following guide before contacting support[at]app47.com.
How to Verify your Agent Version
You must have the iOS agent version 2.4 or higher installed in the application. You can download this from the resource area of the portal.
The agent version can be found in one of two places:
- If running locally on a device and you have access to the raw console log, the agent will report the current version.
- Embedded Agent version 2.4 started and ready for service.
- When viewing a specific log message, the Agent, along with the OS and App Version, are reported in the log details area.
What if Application Symbols are not Symbolicated?
If your application symbols are not be symbolicated, the reason is either no dSYM is uploaded, or the wrong one is uploaded to the service. See the next section on how to upload your dSYM file if you are not sure how to do this.
How to Upload your dSYM File
To fully symbolicate the crash log, the dSYM file associated with that specific build must be uploaded to the App47 service and associated with the build. There three ways to upload your dSYM file.
- When adding or editing an iOS build through the UI Portal
- When uploading a build through the APIv1
- When uploading a build through the APIv2
What if Application Symbols not Symbolicated even with the Correct dSYM File?
If you believe you have uploaded the correct dSYM file, but your application symbols are still not being symbolicated, please check the UUID for both the crash log and the dSYM. See the next two sections on how to find the UUID if you are not sure how to do this.
How to Find the UUID for a Given Log File
Using the UI portal, navigate to 'Analyze' ⇒ 'Logs' and find a crash log that is not symbolicated. Expand the log details by clicking on the down triangle.
After all the threads are presented, the list of Binary Images are presented in the crash log, the very first entry will be your application.
For example, in the example below:
Binary Images: 0x10008c000 - 0x10013bfff +Agent arm64 <854cd1e1b2a23403836e6c7fc4e72cf5> /var/containers/Bundle/Application/8FE4D2D2-2AC6-4B91-A940-D016C8F9500E/Agent.app/Agent
is the UUID for this crash log. There must be a matching dSYM file that has a matching UUID to symbolicate this crash log.
How to Find the UUID for a Given Build
There are two ways to check the UUID for a build:
- Through the UI portal.
- Locally on your machine.
See the two subsections below for more information on these processes.
Verify the dSYM UUID Through the UI Portal
- Navigate to Manage, Builds.
- Select the application you are troubleshooting.
- Select the iOS build you believe should have the correct dSYM UUID. Do this by clicking on the link for the version of the build.
If the build has a dSYM file associated with it, there will be two entries in the “Build Information” table.
- dSYM URL - URL to download the dSYM file previously uploaded
- Build UUID - list of UUIDs contained in the dSYM file, one of these values must match the UUID previously found in the crash log.
Note: The symbolication engine first tries the associated dSYM file matching the app version reported by the agent. If the symbolication does not work, it will try other builds that contain a dsym file in order to best symbolicate your crash log file.
Verify the dSYM UUID Locally
With the dSYM file (it's actually a directory) locally on your iOS machine with Xcode installed, issue the following command:
dwarfdump --uuid yourapp.app.dSYM
This will report the UUIDs contained in the dSYM, please note that you will need to lower case all characters and remove the “-” from the dwarfdump command to match the UUID found in the crash log.
What if System Symbols are not Symbolicated?
If symbols outside of your application are not symbolicated, then the device symbol files are missing from our symbolication service. This is where we can use your help!! We have tried our best to capture as many device symbols we have access too, however each version and device type is unique, so you can imagine there are many permutations in the world.
If your system symbols are not symbolicated and you would like to contribute symbols from your environment, please let us know by sending an email to support[at]app47.com and we'll grant you access to the folder: https://app47.box.com/v/iOSDeviceSupport.
This will allow you to view the symbols currently available as well as upload additional symbols.
How to Upload Additional Symbols
Once you have access to the Box folder setup for iOS Device symbols, please go to your development machine and open finder to: ~/Library/Developer/Xcode/iOS DeviceSupport.
You can compare files contained in https://app47.box.com/v/iOSDeviceSupport and what you have locally. If you have a directory not on our box folder, you can upload the directory one of two ways:
- Use the Box Sync application to copy the folder over. Each folder is approximately 2GB, so it will take some time to sync.
- Zip the folder up locally and then use the file upload tool to upload the zip file. Our support team will be notified of the new file and will unzip it in place.
- WE THANK YOU!! Very much for helping us improve iOS Crash Log symbolication!!