iOS Crash Log Symbolication: Methods, Tools, and Youzan's Implementation

Background

Youzan built a Crash platform but iOS crash logs were not symbolicated, making debugging difficult. Symbolicating crash logs is essential for reducing crash rates and quickly locating issues.

1. Crash Log Collection and Analysis

Methods to collect crash logs:

View directly on the device via Settings → Privacy → Analytics & Improvements.

Sync to a Mac using the "Music" app, then locate logs at ~/Library/Logs/CrashReporter/MobileDevice/ (requires manual symbolication).

Connect the device and open Xcode → Devices and Simulators.

Use Xcode's Window → Organizer to view other devices' logs.

Xcode can automatically look for symbol files and attempt symbolication, but all methods require access to the device.

2. Crash Log Structure

A crash log consists of four parts: basic information, crash reason, all thread stacks, and the Binary Images list.

Examples of each section are shown as images in the original article.

3. How to Symbolicate Crash Logs

Symbolication is usually performed with the atos and symbolicatecrash tools.

3.1 atos

Usage example:

atos -arch <Binary Architecture> -o <Path to dSYM file>/Contents/Resources/DWARF/<binary image name> -l <load address> <address to symbolicate>

Required parameters: architecture, dSYM path, load address, and the crash address, all of which can be extracted from the crash log.

Example command:

$ atos -arch arm64 -o TheElements.App.dSYM/Contents/Resources/DWARF/TheElements -l 0x1000e4000 0x00000001000effdc

Result:

-[AtomicElementViewController myTransitionDidStop:finished:context:]

3.2 symbolicatecrash

symbolicatecrash is a wrapper around atos that can process an entire crash file.

Find the tool:

find /Applications/Xcode.App -name symbolicatecrash -type f

Usage example:

export DEVELOPER_DIR="/Applications/Xcode.App/Contents/Developer"

<path of symbolicatecrash>/symbolicatecrash <Path to dSYM file crash log>

symbolicatecrash log.crash > result.log

Multiple dSYM files can be supplied with the -d option.

4. Symbolication Process Analysis

The process involves parsing Binary Images, threads, and the Last Exception Backtrace, then matching each address with its corresponding dSYM using UUIDs. Steps include:

Parse all Binary Images and store them as objects containing base address, UUID, path, and architecture.

Parse all thread stacks and store raw addresses.

Translate the Last Exception Backtrace using the stored Binary Image information.

Remove unused images to improve efficiency.

Locate the appropriate symbol file for each image (app dSYM or system symbol tables).

Run atos for each address and record the symbolicated output.

Replace raw addresses in the crash log with the symbolicated strings to generate the final report.

5. Youzan's Symbolication Solution

5.1 dSYM Management

Each build generates a dSYM file, which is saved locally and uploaded to the cloud. The build machine (MBD) records the dSYM UUID, bundle ID, version, and build number. This mapping allows locating the correct dSYM for a given crash UUID.

5.2 Crash Reporting

Crash data is reported via an SDK to an analytics platform, then consumed by Flink for real‑time processing and stored in a database.

5.3 Crash Symbolication Workflow

In the crash UI, the user clicks the "symbolicate" button, triggering an MBD symbolication job.

MBD extracts the crash UUID, finds the corresponding dSYM on the build machine, and dispatches the job.

The build machine runs a script that invokes symbolicatecrash and returns the result to MBD.

MBD stores the symbolicated output in the database and notifies the backend.

The UI refreshes to display the symbolicated crash.

6. Challenges and Improvements

Storing dSYM files on every build machine consumes space; a CDN‑based approach is planned.

Removing a build machine can break symbolication for crashes built on that machine; consolidating dSYM storage is under consideration.

Maintaining system symbol tables across machines is manual and error‑prone; automation is needed.

Conclusion

The article explains how to collect iOS crash logs, the structure of those logs, the tools ( atos and symbolicatecrash ) used for symbolication, and Youzan's end‑to‑end solution that integrates dSYM management, crash reporting, and automated symbolication. This knowledge enables developers to efficiently debug and improve app stability.