January 19, 2025
+ 12

Description — Couchbase Lite on Objective-C — Using symbolicate to decode crash logs
Related Content — Using Logs | Troubleshooting Queries

Symbolication

In order to make sense of a crash report you will need to symbolicate its content. Symbolication being the process of replacing memory addresses in a crash report with human-readable function names and line numbers.

Finding local dSYM

To locate the local dSYM files:

  • For scheme based builds, they are located in the derived data path

  • For the target based builds, they are located in the configuration build directory path, as specified in the target setting

  • For archives, they are located in .xcarchive.

If you still cannot locate the file, then use mdfind as described in the Symbolication Troubleshooting section of the Apple Technical Note TN2151 — Understanding and Analyzing Application Crash Reports: https://developer.apple.com/library/archive/technotes/tn2151/_index.html

The CouchbaseLite dSYM

Couchbase Lite’s dSYM folder is located in the same directory as the Couchbase Lite binary framework (this also applies for Cocoapod and Carthage). It has the same filename as framework but has a .dSYM extension.

Example 1. dSYM in CouchbaseLiteSwift
objc
couchbase-lite-swift_enterprise_2.7.0/iOS/CouchbaseLiteSwift.framework.dSYM

How to obtain the .DSYM file for your app

To symbolicate crash reports generated by these apps you must download the generated dSYM files. Do this using Xcode’s Organizer or direcly from App Store Connect.

Downloading dSYM using Xcode Organizer

  1. Within Xcode’s Archives Organiser, select the required archive

  2. Within the Archive Information dialog panel, select Download Debug Symbols button

    The dSYM files are downloaded to the archive bundle in a folder named dSYMs

Downloading dSYM directly from App Store Connect

  1. Inside My Apps choose the Activity section

  2. Locate the required build (the one you want to download dSYM files for)

  3. In the Includes Symbols column, select the download dSYM link .

Using third-party crash report tools

You can upload your dSYM files to third-party crash reporting tools for analysis, either automatically via script or a manual zip file upload. Links for some of the more popular crash reporting tools are included below.

Obfuscated symbols (_hidden)

Xcode includes obfuscated symbols in dSYM files if apps are uploaded to Apple without symbols.

In such cases you need to to de-obfuscate dSYM files before symbolicating. De-obfuscation is done automatically if downloading through Xcode. But if you use App Store Connect, you may need to, use the xcrun command on each .dSYM file inside the downloaded dSYM folder.

Example 3. De-obfuscation using xcrun
objc
xcrun dsymutil -symbol-map <pathToApplicationArchieve>.xcarchive/BCSymbolMaps <pathToDownloadedDSYMs>/3B15C133-88AA-35B0-B8BA-84AF76826CE0.dSYM
See Translating 'hidden' symbol names back to their original names: https://developer.apple.com/library/archive/technotes/tn2151/_index.html