Symbolicator

Description

The Symbolicator is a program to symbolicate crash logs generated on Mac OS X.

Symbolication is the process of replacing bare memory addresses with function name, filename, and line number information. The Symbolicator obtains this information from dSYM bundles, which you generate as part of your build process and archive as part of your release process.

Apple has an article about setting up your Xcode project to generate dSYM bundles and stripped executables. You'll release the fully-stripped executables to users, and keep the dSYM bundles on hand so that you can symbolicate any crash logs you receive.

When you receive a crash log, pipe it through the Symbolicator, probably into a pager or editor. The Symbolicator will use Spotlight to find any dSYM bundles it needs, and dwarfdump to extract symbol information for the addresses in the crash log.

Usage

The Symbolicator reads your crash log from files you name on the command-line, or from standard input. It writes the symbolicated crash log(s) to standard output.

This means that you can use ThisService to make a Symbolicator service: open the crash log in a text editor, select everything, and run the service, and your text editor will replace the un-symbolicated crash log text with the symbolicated version.

You will need to have the dSYM bundles lying around somewhere on your system. The Symbolicator uses Spotlight to find them, so you won't need to tell it about them; just having them is enough.

Symbolicator vs. other symbolication tools

Xcode's Organizer window: Only works on iPhone crash logs; displays Mac crash logs unchanged
atos (Xcode 3.1.1) -o path-to-GrowlHelperApp-executable: Does not resolve the symbol; output: “0x00014223 (in GrowlHelperApp)”
atos (Xcode 3.1.1) -o path-to-dSYM-executable: Does not resolve the symbol; output: “0x00014223”
gdb: Requires the main bundle and dSYM bundle to be in the same directory
symbolicatecrash (TN2151 edition): Passes crash log through unchanged
symbolizecrashlog (from Debugging and Symbolizing): Uses atos, so it has the same problem as atos; like symbolicatecrash, passes crash log through unchanged
dwarfdump --lookup: Works, but you have to look up one address at a time

All of the other symbolication tools either don't work or require you to keep the main bundle and dSYM bundle together, whereas the Symbolicator:

works wherever the dSYM bundle is on your system, as long as Spotlight can find it
works even when atos doesn't.

The Symbolicator makes dwarfdump easier to use on an entire crash log: You simply feed in the crash log, and the Symbolicator will run dwarfdump on each address for you.

Downloads

Symbolicator-1.0.1.zip: The Python program, in a zip archive.
MD5 hash: 6c77ec4a1464ab95657a035efe296436
SHA-1 hash: e8e9d53c1b2b3885d0ac7424f55571807550edea
Symbolicator-1.0.zip: The Python program, in a zip archive.
MD5 hash: 17d6b84c891da9d3f533b7e2fa96fbfe
SHA-1 hash: ddd97dcd799abb784ef9b74d9e8531f7b82dd986

I obtained these MD5 and SHA1 signatures, and you can check them, using EasyHash.

Mercurial repository

If you want to contribute bug-fixes or enhancements to the Symbolicator, the easiest way to do that is to clone the Mercurial repository for the Symbolicator. To do this, type this command into a terminal:

hg clone https://bitbucket.org/boredzo/symbolicator

I provide the Symbolicator under a three-clause BSD license. For more information, see the file named LICENSE.txt that comes with it.

Version history

1.0.1

Now has a setup.py file (contributed by Augie Fackler)
Now available from the Python Package Index using easy_install
Fixed failure to recognize bundle identifiers containing numerals (9dd25e0d1a88)
Fixed failure to recognize the end of a crash log that didn't have a blank line after it (60d8114727c1)
Now approximately ²⁄₃ faster (0bbf27ea9258)

1.0

First release.