Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Crash Logs

    +

    Description — Couchbase Lite on Swift — 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. To do this you need to have debug symbol (.dSYM) files for the application and for Couchbase Lite’s framework.

    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
    couchbase-lite-swift_enterprise_2.7.0/iOS/CouchbaseLiteSwift.framework.dSYM

    Bitcode enabled Apps

    Apple creates new dSYM files for apps uploaded to the App Store or TestFlight with Bitcode enabled. 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

      See Download debug symbols: https://help.apple.com/xcode/mac/current/#/devef5928039

    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.

    Example 2. Third party crash reporting tools

    Obfuscated symbols (_hidden)

    Xcode includes obfuscated symbols in dSYM files if apps with Bitcode enabled 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
    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

    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. To do this you need to have debug symbol (.dSYM) files for the application and for Couchbase Lite’s framework.

    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 4. dSYM in CouchbaseLiteSwift
    couchbase-lite-swift_enterprise_2.7.0/iOS/CouchbaseLiteSwift.framework.dSYM

    Bitcode enabled Apps

    Apple creates new dSYM files for apps uploaded to the App Store or TestFlight with Bitcode enabled. 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

      See Download debug symbols: https://help.apple.com/xcode/mac/current/#/devef5928039

    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.

    Example 5. Third party crash reporting tools

    Obfuscated symbols (_hidden)

    Xcode includes obfuscated symbols in dSYM files if apps with Bitcode enabled 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 6. De-obfuscation using xcrun
    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

    Related Content

    How to . . .
    Learn more . . .
    Dive Deeper . . .