How to Decode iOS Crash Logs: From dSYM Files to Online Symbolication

What Is Symbolication?

During development, crash logs often contain only raw hexadecimal memory addresses, making them unreadable. Symbolication converts these addresses into human‑readable function names, file names, and line numbers, allowing developers to pinpoint the exact code that caused the crash.

Symbolication Principles

dSYM Files

In iOS, a dSYM file is a debug‑information bundle (usually named xxx.app.dSYM) that stores the mapping between binary addresses and source symbols. The DWARF format inside the dSYM contains compressed debug data such as file names, method names, and line numbers. Useful commands include:

dwarfdump --debug-line /path/to/TestBacktrace.app.dSYM > debug_line.txt

and

otool -l /path/to/TestBacktrace.app.dSYM/Contents/Resources/DWARF/TestBacktrace | grep __TEXT -C 5

Generating dSYM Files

When building in Xcode, the Debug configuration does not generate dSYM files by default; enable them in

Build Settings → Build Options → Debug Information Format

. Release builds generate dSYMs automatically. Each dSYM contains a unique UUID that identifies the exact build.

Matching dSYM by UUID

Extract the app’s UUID from the crash log’s Binary Images section, e.g.:

Binary Images:
0x102a40000 - 0x102a6bfff TestBacktrace arm64 <6be881754f573769926b838490e39857>

Then verify the dSYM’s UUID with:

xcrun dwarfdump --uuid /path/to/TestBacktrace.app.dSYM

If the UUIDs match, the dSYM is the correct one. When many dSYMs exist locally, you can locate the matching file with:

mdfind "com_apple_xcode_dsym_uuids == 6BE88175-4F57-3769-926B-838490E39857"

Symbolication Process

iOS uses ASLR, so the runtime address equals the binary’s base address plus an offset. By retrieving the base address, offset, and dSYM’s __TEXT start address, you can compute the corresponding address inside the dSYM and look up the symbol:

dwarfdump TestBacktrace.app.dSYM --lookup 0x100007464

The lookup returns entries such as DW_TAG_Subprogram, DW_AT_name, DW_AT_decl_file, and DW_AT_decl_line, which together produce a line like:

3   TestBacktrace   0x102a47464 -[AppDelegate Application:didFinishLaunchingWithOptions:] + 29796 (AppDelegate.m:23)

Local Symbolication

Using Xcode UI

Place the crash log, the corresponding dSYM, and the app binary in the same folder, then drag the log onto the Xcode Device Log window and choose Symbolicate Log or Re‑symbolicate Log.

Using symbolicatecrash Command‑Line Tool

Locate the script (usually under

/Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Resources/symbolicatecrash

), set the developer directory, and run:

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
./symbolicatecrash TestBacktrace-2021-07-30-135514.ips TestBacktrace.app.dSYM > symbol.log

System Library Symbolication

When a crash involves only system libraries, you need the corresponding system‑library dSYM files. The crash log provides the library’s UUID; only a matching system symbol file can resolve the addresses. System symbols can be obtained from a connected device (Xcode copies them to ~/Library/Developer/Xcode/iOS DeviceSupport) or extracted from iOS firmware (iPSW) using tools such as dsc_extractor and dyld_shared_cache.

Online Symbolication

Why Online?

CI servers generate dSYM files, but fetching them locally is costly. Production apps generate millions of crash logs daily across many iOS versions, making manual or per‑log local symbolication impractical.

Solution Overview

We extract a mapping file from each dSYM that lists address ranges, function names, source files, and line numbers. For system libraries we extract symbols from the dyld shared cache. The server stores these mapping files and, when a crash log arrives, matches the UUIDs, looks up the address in the mapping, and returns a fully symbolicated stack—all on Linux.

Mapping File Generation

Example mapping format:

Format:        Mach-O/64-BitArch:        arm64
Symbols:        6c64    6c78    -[ViewController viewDidLoad] (in TestBacktrace) (ViewController.m:17)
6c78    6c84    -[ViewController viewDidLoad] (in TestBacktrace) (ViewController.m:0)

The extraction parses DWARF debug_line and the symbol table to produce address‑to‑symbol entries.

System Symbol Extraction

Steps:

Download the appropriate iPSW firmware for the target iOS version.

Extract the largest .dmg (the system image) and decrypt it using the firmware key.

Obtain dsc_extractor.bundle from the matching Xcode version.

Run

dsc_extractor dsc_extractor.bundle /System/Library/Caches/com.Apple.dyld/dyld_shared_cache_arm64 output_dir

to unpack all system dylibs and frameworks.

Generate mapping files for each extracted binary similarly to the app dSYM.

Results and Benefits

After deploying the online service, Baidu’s performance platform processes over one million crash or lag logs per day, covering more than 30 product lines. Symbolication now occurs automatically upon upload, reducing the time from crash occurrence to developer notification to under ten minutes and eliminating manual tooling overhead.