What are dSYM files and why are they needed

What are dSYM files and why are they needed

Gain high-level understanding about iOS Symbolication and Crash Reporting Providers


3 min read

Do you use a crash reporting solution to gain insights into your iOS application? Have you ever wondered why crash reports might contain gibberish and why crash reporting solutions ask you to upload so-called dSYM files?

Then this short blog post is for you :)

When Xcode compiles your source code into machine code, it generates a list of symbols in your app, i.e. class names, global variables, and method and function names. These symbols correspond to the file and line numbers where they're defined.

Debug builds of an app place the debug symbols inside the compiled binary file by default. Release builds of an app place the debug symbols in a companion Debug Symbol file (.dSYM) to reduce the size of the distributed app.

When a crash occurs on the device, a crash report contains stack traces for all running threads of your app at the time a crash occurred. But those stack traces only include memory addresses.

Report Crashes

Your crash reporting solution needs those dSYM files to make them human-readable. This process of "translation" is called symbolication.

A fully symbolicated crash report has function names on every frame of the backtrace, instead of hexadecimal memory addresses. Once a crash report was symbolicated then the crash reporting solution can group them smartly together.

Hence you need to upload dSYM files.

Upload dSYM file

Remember that each binary file in an app has its dSYM file, so you might need to upload multiple files for a single app.

For example, you have an iOS application that includes a watch extension, and your app uses a framework. Then you have to upload three files:

  • one for the main app executable
  • one for the app extension
  • one for the framework

Let me quickly talk about crash reporting solution providers.

All major providers share the basic capabilities of

  • collecting crash information from the device through an provider-specific SDK
  • making the crash information human readable (Symbolication)
  • grouping crash reports smartly together if sharing the same common root cause
  • providing analytical capabilities with various charts and filters.

I do not want to recommend any specific provider. There are plenty, here are just a few names in no particular order:

I encourage you compare them as the offering of advanced capabilities varies. Examples are listed below.

  • Greater details of technical information
    • Device features such as battery status and the proximity of sensors
    • Operating system details, including jailbreak status
    • analyzes stack traces and prioritizes the most relevant threads
    • records a video that shows the last actions of the user, including touch movements
  • Let’s you contact your users right after a crash happens (live conversation
  • Collect in-app feedback from your users (can leave bug reports, including screenshots, voice reports, annotations, and screen recordings)
  • Connects to your bug tracker of choice and creates an issue about the crash

Go with the solution provider of your choice, and I hope you understand why uploading dSYM files are necessary.

Did you find this article valuable?

Support Marco Eidinger by becoming a sponsor. Any amount is appreciated!