Technical Note TN2151

Crash Reporting for iPhone OS Applications

This document contains essential information for developers who wish to receive and process crash reports for their iPhone OS applications.

Acquiring Crash Reports Report Types Symbolication Document Revision History

Acquiring Crash Reports

When an application crashes on the iPhone or iPod touch, a "crash report" is stored on the device. Crash reports describe the conditions under which the application terminated, in most cases including a complete stack trace for each executing thread, and are typically very useful for debugging issues in the application.

When the user synchronizes their device using iTunes, crash reports are copied to a directory on the user's computer. If the application was distributed via the App Store and the user has chosen to submit crash logs to Apple, the crash log will be uploaded and the developer can download it via iTunes Connect. For applications that have been distributed using Ad Hoc or Enterprise methods, getting crash reports requires user cooperation. Specifically, the user will need to retrieve the crash report from the directory where it was copied by iTunes. Depending on the platform, the directory is:

• Mac OS X: ~/Library/Logs/CrashReporter/MobileDevice/<DEVICE_NAME>

• Windows XP: C:\Documents and Settings\<USERNAME>\Application Data\Apple Computer\Logs\CrashReporter\MobileDevice\<DEVICE_NAME>

• Windows Vista: C:\Users\<USERNAME>\AppData\Roaming\Apple Computer\Logs\CrashReporter\MobileDevice\<DEVICE_NAME>

<USERNAME> is the user's login name for the computer. <DEVICE_NAME> is the name of the iPod touch or iPhone, for example, "John's iPhone".

You are only interested in .crash files. The crash report's file name begins with the application name and contains date/time information. In addition, <DEVICE_NAME> will appear at the end of the file name, before the extension.

Back to Top

Report Types

There are four distinct kinds of crash reports. They are:

• Application crash: possibly the most common kind of report, this is generated when execution is halted due to bad access or other programming error.

• Low memory: occurs when the application has been killed by the system because it has failed to free up sufficient memory in response to low memory warnings. The format of this report differs from the others in that there are no stack traces for the application threads. Rather than be concerned about what part of your code was executing at the time of termination, you should investigate your memory usage patterns and your responses to low memory warnings.

• User force-quit: distinguished by exception code 0xdeadfa11, force quits occur when the user holds down the home button for six seconds. It's reasonable to assume the user has done this because the application has become unresponsive, but it's not guaranteed - force-quit will work on any application.

• Watchdog timeout: distinguished by exception code 0x8badf00d, timeouts occur when an application takes too long to launch or terminate.

Except for the low memory crash logs, these logs contain stack traces for each thread at the time of termination. The next section discusses those traces.

Back to Top

Symbolication

The most interesting part of a crash report is the stack trace of your application at the time execution halted. This trace is similar to what you would see when stopping execution in the debugger, except that you aren't given the method or function names, also known as "symbols". Instead, you have hexadecimal addresses and executable code - your application or system frameworks - to which they refer. You need to map these addresses to symbols. Unlike crash logs from Mac OS X, iPhone OS logs do not contain symbol information when they're written out. You have to "symbolicate" iPhone OS logs before you can analyze them.

Symbolication - resolving stack trace addresses to source code methods and lines - requires the application binary that was uploaded to the App Store and the .dSYM file that was generated when that binary was built. This must be an exact match - otherwise, the report cannot be symbolicated. It's essential that you keep each build distributed to any users (regardless of mechanism) with its .dSYM file.

Given a crash report, the matching binary, and its .dSYM file, symbolication is relatively easy. The Xcode Organizer window has a tab for crash reports of the currently selected device. You can view externally received crash reports in this tab - just place them in the appropriate directory. This is the same as the Mac OS X directory described in the first section. It doesn't matter which device you have tethered, but the directory in which you place the crash report must be the directory for the tethered and selected device.

It is not necessary to place the binary and .dSYM file in any particular location. Xcode uses Spotlight and the UUID to locate the correct files. It is necessary, though, that both files be in the same directory and that this directory is one that is indexed by Spotlight. Anywhere in your home directory should be fine.

Back to Top

Document Revision History

Posted: 2009-06-01