Overview of iOS Crash Reporting Tools: Part 1/2

The Symbolication Process

In the case of iOS, this requires two things. The first is the exact application binary that caused the crash. The second is the dSYM file created during the compilation of the binary.

How do you get a hold of these two items? Well, if you are using the “Build and Archive” command in Xcode then you are already storing them! In Xcode, you can see these in the “Organizer” window. To see for yourself, open Xcode then go to Window\Organizer. Then select the “Archives” tab where you will see a list of your apps on the left and on the right you’ll see a list of the archives for the selected app.

However, if you haven’t been using “Build and Archive”, or don’t have any applications to choose from, simply create a dummy app to see where Xcode stores these files.

Note: If you’re familiar with the Organizer, feel free to skip this section and move on to the section titled “Find that dSYM!”

To create a dummy app. Start up Xcode, go to File\New\New Project, choose the iOS\Application\Empty Application template, and click Next, as shown in the screenshot below:

On the next page, feel free to put in any name for the application. The details don’t matter because this is just a throwaway app to create an archive with a binary and dSYM in it. Click Next, then choose a location to save your project. When Xcode presents the workspace, select iOS Device as the compilation target, as shown below:

Finally, select Product\Archive, as shown below:

This will generate an archive for your application, which can then be found in the Organizer.

Find that dSYM!

Go to the Organizer, by selecting Window\Organizer, select the Archives tab and then find either an archive for one of your own apps or the test app you made if you followed the previous section. In case you’re struggling to find the archive, here’s a screenshot of what the Organizer looks like:

Right-click on your choice of archive, and choose Show in finder. This will open up a Finder window with a file whose extension is .xcarchive. This is not a file, per se, but rather a folder.

Note:Just like archives, lots of “files” on Mac OS X and iOS are actually folders. Examples include applications (.app), iPhoto libraries (.photolibrary) and code frameworks (.framework).

To inspect the archive, first open a new terminal window. To open a terminal window, open a new Finder window, navigate to your Applications folder, then navigate to the Utilities subfolder, and finally run the Terminal application. Or you could simply type “terminal” into Spotlight and press return when it’s found Terminal. :]

Once Terminal is open, drag the .xcarchive file into the terminal window and you’ll see the complete path to the folder. Press Control-A to jump to the start of the path and type: "cd " (note that there is a space after the “cd”).

Next, press enter. You’ll notice that the terminal prompt (the bit before where the cursor sits) now has the name of the .xcarchive before the dollar sign.

Next, type the following command: "find . -type d". You should see some output similar to the following:

$ find . -type d
.
./Products
./Products/Applications
./Products/Applications/breezi.app
./Products/Applications/breezi.app/_CodeSignature
./Products/Applications/breezi.app/en.lproj
./dSYMs
./dSYMs/breezi.app.dSYM
./dSYMs/breezi.app.dSYM/Contents
./dSYMs/breezi.app.dSYM/Contents/Resources
./dSYMs/breezi.app.dSYM/Contents/Resources/DWARF

The command you just typed is using the “find” program, which does exactly what it sounds like – it finds things! The “.” means “search in the current directory” and the “-type d” means “find things that are directories”. In the resulting list of files, notice the .dSYM directory, along with the .app directory. Those are what you’ll need to finish the symbolication process and tie the crash report to your code.

It’s the .dSYM that’s really the most important bit. Recall from earlier that a release build has all the symbols stripped from the binary, which is why crash reports from release builds contain only hexadecimal addresses. The .dSYM contains all the information required to convert back into symbols through the process of symbolication.

Xcode has a method of symbolication built into it and it’ll generally do a good job of making sure any crash log you ever see has been symbolicated. It uses spotlight to find the appropriate .dSYM file for the crash log in question, but sometimes it can’t find it (maybe because you didn’t have it on your computer at the time as the build was made on a build server). In these cases, you can force Xcode to re-symbolicate once you have the .dSYM copied to your computer. To force Xcode to re-symbolicate a crash you can do so in the Organizer. Go to the Organizer again, select the “Devices” tab and then select “Device Logs” on the left. Then select the crash log that needs re-symbolicating and press the button at the bottom of the screen:

It’s not just Xcode that uses the .dSYM to symbolicate crash reports. It’s also required by crash reporting tools. As you’ll see throughout the reviews of the various crash reporting tools, the way you get this file to the crash reporting tool is different, but it’s always required for symbolication. There’s no point having crash logs if you can’t read them after all!

Making a Case for Crash Reporting

It’s an incredibly clunky process to collect crash logs manually and since a user will probably not have Xcode installed, they would have to use iTunes to access the crash logs. While not a technique I recommend asking your users to do, here’s how you’d do it in the absence of crash reporting tools:

1. Connect the device to the Mac, synch it via iTunes and navigate to the logs folder, which is different on each operating system:
   • OS X: ~/Library/Logs/CrashReporter/MobileDevice/(your iPhone’s name)/(your app name)
   • Windows XP: C:\Documents and Settings\Application Data\Apple computer\Logs\CrashReporter\(your iPhone’s name)\(your app name)
   • Windows Vista: C:\Users\AppData\Roaming\Apple computer\Logs\CrashReporter\MobileDevice\(your iPhone’s name)\(your app name)
2. Look for files with the extension of “.crash”.
3. Ask the user to send those files to you.
4. Once you have the files, open the Organizer in Xcode and select “Device Logs” on the top left, as shown below:

   

5. At the bottom select import to add the log to Xcode and, if necessary because Xcode hasn’t noticed the log yet, trigger a re-symbolication as explained earlier.

Phew! Can you imagine any user volunteering to do this for you?

This solution is pretty tedious, to say the least, and it requires the active involvement of your users. That might be OK when you’re in the beta testing phase, and your testers expect a bit of weirdness with the app. However, once you’re in production don’t expect that your users will be happy to go through all that work to give you a crash report!

Interestingly enough, Apple helps out and collects crash reports for applications that are published through the App Store. However, it only happens for users who opted to automatically send diagnostic data to Apple. If you have an app available through, the App Store login to iTunes Connect, select “Manage Your Applications”, choose one of your applications and the click the blue button “View details”, as shown below:

This will open a detailed view of your app’s properties. At the top right there is a button “Crash Reports”, as shown in the following screenshot:

This section will contain the crash logs collected by Apple. In my experience, these aren’t collected as frequently as with other crash reporting tools, probably because not all that many people have automatic sending of diagnostic reports turned on. Plus, they still require some manual work from developers, like importing and symbolicating.

The smart developer, who would rather spend time writing code than manually retrieving and symbolicating crash dumps, would prefer a process like this:

1. Release an application (either in beta or in production) which is able to capture and store crash logs.
2. The application periodically (or even immediately!) sends crash reports to a server which collects and organizes them for you.
3. The developer logs in to the server, finds the crash reports already symbolicated, and can easily find the root cause of the issue.

It’s not a far-fetched dream — tools like this do exist in the real world! However, there are quite a few to choose from. Some are free and open source, while others are commercial products. Of the many available, I’ve reviewed some of the most prominent offerings:

• Crashlytics
• Crittercism
• Bugsense
• TestFlight
• HockeyApp

Have a read through the reviews to see which one provides the particular solutions you’re looking for in your app. I have my own favorites, but I’d love to hear your thoughts on your personal choices in the comments section!