Enabling human readable reports on iOS

For MobileFirst Quality Assurance to display a human readable stack trace from an app that no longer has its symbols, it must use a symbol lookup process to translate the stack trace back into a version that can be understood. This process is called symbolication and it is a necessary component for correctly tracking crash data in MobileFirst Quality Assurance for builds that have their symbols removed.

Before you begin

You must have access to a computer that is running Xcode to prepare the symbol file.
Download the following file:
Library Version Last Updated Purpose

Python Symbolication Script 4 September 30, 2013 Use this script to symbolicate your iOS application.

Library	Version	Last Updated	Purpose
Python Symbolication Script	4	September 30, 2013	Use this script to symbolicate your iOS application.

About this task

When Xcode compiles an app, it can do so by either including or excluding symbols in the outputted binary file. Symbols are useful for interpreting stack traces and are typically included when the app is still in testing. However, because including symbols makes the app larger, they are typically removed before the app is sent to the App Store.

After the symbols are removed from an app, logs of crashes from that app contain only memory address references instead of human readable symbol names. For MobileFirst Quality Assurance to display a human readable stack trace from an app that no longer has its symbols, MobileFirst Quality Assurance must use a symbol lookup process to translate the stack trace into a version that can be understood. This process is called symbolication and it is a required component for tracking crash data in MobileFirst Quality Assurance for builds that have their symbols removed.

Preparing your app for symbolication is a two-step process:

Generate a special dictionary file, which is called an "ahsym" file, by using a compiled archive from Xcode.
Upload your ahsym file to MobileFirst Quality Assurance.

Symbolication is only required if you want to have crash reporting for an app that has its symbols removed (for example, an app that you plan to submit to the Apple App Store). However, you can also strip the symbols from an app that is still in testing.

If your crash reports do not contain human readable method names and instead display a long series of numbers, then you probably need to upload a symbol file to MobileFirst Quality Assurance.

Procedure

Creating a symbol file for your app is straightforward. First, you run a small script on your iOS app archive and then upload the resulting symbol file to MobileFirst Quality Assurance. After you upload the file, MobileFirst Quality Assurance can interpret all stack traces for that particular build.

Verify the availability of command-line tools.
The symbolication process uses an Apple tool that is called dwarfdump to create the symbols dictionary. Verify that this tool is installed and working on your computer by opening your Terminal application and running the dwarfdump command at the prompt:
```
$ dwarfdump
```
If you see dwarfdump: Command not found, then you might have to install the Xcode command-line tools. Do so by starting Xcode and then clicking Xcode > Preferences from the menu. On the preferences window, click Downloads, and then click Install next to Command-Line Tools under the Components menu.
Download the MobileFirst Quality Assurance Python Symbolication Script.
MobileFirst Quality Assurance symbol files are generated by using a MobileFirst Quality Assurance specific command-line application that is written in Python. Download the Python script and extract the file. Place the dump_reduce.py Python script in an easy-to-locate folder.
Create an iOS app archive.
Compile your app as you would normally. Open the Organizer in Xcode, and select the build that you compiled. Right-click, and open the build in Finder. Note the location of the build archive (also known as your xcarchive).
Run the Python symbolication script.
Run the Python script to process the xcarchive that you created. The way that you run the script depends on whether your xcarchive file contains one target or multiple targets.
- If your xcarchive file contains one target, complete this step:
  In most cases, your xcarchive file contains a single target. If the Python script is in the /Applications directory and your xcarchive file is in the ~/Documents/Code/myApp.xcarchive directory, run the Python script in the following form:
```
% python /Applications/dump_reduce.py -x ~/Documents/Code/myApp.xcarchive -o ~/Documents/Code/myApp
```
  The command-line options are as follows:
  -x or --xcarchive
  
  The location of the xcarchive file that you created in Xcode.
  
  -o or --out
  
  The name of the .ahsym file for the script to create. The .ahsym extension is added automatically.
  
  Running the script might take several minutes for larger applications. After the script finishes, a .ahsym file is output to the location that is specified by the -o option.
- If your xcarchive file contains multiple targets, complete this step:
  If your xcarchive file contains multiple targets, you must add an extra option to the dump_reduce.py command to specify the location of the dsym Info.plist and dsym data files for the target to process. Otherwise, the process is the same as the earlier single-target example.
  If your dsym Info.plist file is in the ~/Documents/Code/myApp.xcarchive/dSYMs/myApp.app.dSYM/Contents/Info.plist directory and your dsym data file is in the ~/Documents/Code/myApp.xcarchive/dSYMs/myApp.app.dSYM/Contents/Resources/DWARF/myApp directory, then run the Python script in the following form:
```
% python /Applications/dump_reduce.py -p ~/Documents/Code/myApp.xcarchive/dSYMs/myApp.app.dSYM/Contents/Info.plist -d ~/Documents/Code/myApp.xcarchive/dSYMs/myApp.app.dSYM/Contents/Resources/DWARF/myApp -o ~/Documents/Code/myApp
```
  The command-line options are as follows:
  -o or --out
  
  The name of the .ahsym file to be created by the script. The .ahsym extension is added automatically.
  
  -p or --plist
  
  The location of the dsym plist file.
  
  -d or --dsym
  
  The location of the dsym data file.
  
  Running the script might take several minutes for larger applications. When the script finishes, a .ahsym file is output to the location that is specified by the -o option.
Upload the .ahsym file to MobileFirst Quality Assurance.
Open the MobileFirst Quality Assurance, and switch to the Builds tab. Drag the .ahsym file that you created to the upload section on the browser window. After MobileFirst Quality Assurance processes the file, logs for crash that originate from the same build as the .ahsym file are symbolicated.
Important: If you recompile your application for distribution, even without changing any code, you must also create a new .ahsym file and upload it to MobileFirst Quality Assurance.

When you upload new builds to MobileFirst Quality Assurance, you can upload an IPA file, an .ahsym file, or both. The combinations work in different ways:
An IPA file only

You uploaded a new build of your app and can distribute it with the build distribution. Crashes are not symbolicated. This approach is typical when you use MobileFirst Quality Assurancein pre-production, where you are distributing development builds to a team of testers.

A .ahsym file only

You did not upload a build, but you uploaded a symbols dictionary. When MobileFirst Quality Assurance detects crashes from this particular build version, it symbolicates them. However, it is possible to use build distributions. This approach is typical when you use MobileFirst Quality Assurance in production, where you are distributing your build in the App Store, but you want to use MobileFirst Quality Assurance for crash reporting.

Both an IPA and a .ahsym files

You uploaded both a build and a symbols dictionary. MobileFirst Quality Assurance recognizes that these two components belong together and treat them as a joined unit. The IPA file can be distributed through build distributions and all crashes are symbolicated. Use this approach if you are testing a version of your app that had its symbols removed for some reason.