Reading iPhone Crash Logs

Sometimes programs crash. This annoys users and developers alike. Users are frustrated because they cannot use crashing software, developers are frustrated because they have to hunt bugs instead of doing something creative and rewarding. How do we communicate if an iPhone application crashes?

I’ll start with a disclaimer. I’m not sure whether the information provided in this post is covered by iPhone Developer Program NDA or not. If it is, the post will be removed. Secondly, this post is a result of googling, so I haven’t invented anything new here.

Working with crash logs typically involves certain interaction between developers and users, unless they are automagically sent to the developer. First of all, the user should get the crash log and send it to the developer, who should examine it, find the bug and fix it.

iPhone OS and Mac OS X are remarkably similar architectures. Both store crash logs to help identify crashing bugs. The difference between the two is how users retrieve them. On Mac OS X every user has unrestricted access to crash logs related to the applications she runs. The iPhone does not even have a file browser. What to do? iTunes comes to the rescue.

Whenever you synchronize your iPhone or iPod Touch, all the crash logs are transferred to your computer. Here are their locations:

* Mac OS X : ~/Library/Logs/CrashReporter/MobileDevice/
* Windows XP: C:\Documents and Settings\\Application Data\Apple computer\Logs\CrashReporter/
* Windows Vista: C:\Users\\AppData\Roaming\Apple computer\Logs\CrashReporter/MobileDevice/

The log file names start with application name and have the extension “crash”. They are just plain text files and can be sent by e-mail in original or zipped form, or even copy-pasted into your e-mail program.

The second part is trickier. Both Apple and common sense suggest that all AppStore binaries are shipped with stripped symbols. If you ever saw a crash log like this, read on:

Thread 0 Crashed:
0   libobjc.A.dylib           0x300c87ec 0x300bb000 + 55276
1   MobileLines               0x00006434 0x1000 + 21556
2   MobileLines               0x000064c2 0x1000 + 21698
3   UIKit                     0x30a740ac 0x30a54000 + 131244
4   UIKit                     0x30a66110 0x30a54000 + 74000
5   UIKit                     0x30a6565c 0x30a54000 + 71260
6   GraphicsServices          0x3169b0b4 0x31696000 + 20660
7   GraphicsServices          0x3169d818 0x31696000 + 30744
8   IOMobileFramebuffer       0x31f3e8f8 0x31f3d000 + 6392
9   com.apple.framework.IOKit 0x30f342b8 0x30f30000 + 17080
10  CoreFoundation            0x3025ced4 0x30229000 + 212692
11  CoreFoundation            0x3025bed6 0x30229000 + 208598
12  CoreFoundation            0x3025b584 0x30229000 + 206212
13  GraphicsServices          0x316998e4 0x31696000 + 14564
14  UIKit                     0x30a5e308 0x30a54000 + 41736
15  UIKit                     0x30a671dc 0x30a54000 + 78300
16  MobileLines               0x00002090 0x1000 + 4240
17  MobileLines               0x0000202c 0x1000 + 4140

In a nutshell, it contains function addresses and offsets instead of function names and line numbers. The structure is obvious, but, to be honest, I don’t know what “MobileLines 0×00006434 0×1000 + 21556″ is, even though I have all the source code. Thanks to Apple Developer Tools and to Craig Hockenberry who wrote about it, we have a perfect solution called symbolicatecrash.

I copied it to /usr/local/bin/ so that I can run it whenever I want without trying to remember its original location (you may prefer a symbolic link):
$ sudo cp /Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Plug-ins/iPhoneRemoteDevice.xcodeplugin/Contents/Resources/symbolicatecrash /usr/local/bin/

Running this script with the -h option provides the minimal help:

$ symbolicatecrash -h
usage:

symbolicatecrash [-Ah] LOGFILE [SYMBOL_PATH ...]

Symbolicates a crashdump LOGFILE which may be “-” to refer
to stdin. By default, all heuristics will be employed
in an attempt to symbolicate all addresses. Additional
symbol files can be found under specified directories.

Options:
-A Only symbolicate the application, not libraries
-h Display this message
-v Verbose

To add symbols to the crash log you need the dSYM file generated by the linker when you compiled your application for AppStore. In other words, when you build for AppStore you should keep the dSYM package in a safe place backed up by Time Machine. This is very important. You should keep a copy of the dSYM for each version of your application ever shipped. If you have the package, translating code offsets to function names with line numbers has never been easier:

$ symbolicatecrash report.crash MobileLines.app.dSYM > report-with-symbols.crash

Here is the result:

Thread 0 Crashed:
0   libobjc.A.dylib           0x300c87ec objc_msgSend + 20
1   MobileLines               0x00006434 -[BoardView setSelectedPiece:] (BoardView.m:321)
2   MobileLines               0x000064c2 -[BoardView touchesBegan:withEvent:] (BoardView.m:349)
3   UIKit                     0x30a740ac -[UIWindow sendEvent:] + 264
4   UIKit                     0x30a66110 -[UIApplication sendEvent:] + 248
5   UIKit                     0x30a6565c _UIApplicationHandleEvent + 4088
6   GraphicsServices          0x3169b0b4 PurpleEventCallback + 428
7   GraphicsServices          0x3169d818 HeartbeatVBLCallback + 152
8   IOMobileFramebuffer       0x31f3e8f8 IOMobileFramebufferNotifyFunc + 124
9   com.apple.framework.IOKit 0x30f342b8 IODispatchCalloutFromCFMessage + 304
10  CoreFoundation            0x3025ced4 __CFMachPortPerform + 72
11  CoreFoundation            0x3025bed6 CFRunLoopRunSpecific + 2364
12  CoreFoundation            0x3025b584 CFRunLoopRunInMode + 44
13  GraphicsServices          0x316998e4 GSEventRunModal + 268
14  UIKit                     0x30a5e308 -[UIApplication _run] + 404
15  UIKit                     0x30a671dc UIApplicationMain + 1064
16  MobileLines               0x00002090 main (main.m:16)
17  MobileLines               0x0000202c start + 44

Now, this is much better. Happy debugging!