Finding Debug Symbols in Xcode

Specto uses dSYM (debug symbol) files generated by Xcode to be able to get symbol, file, and line number information from function addresses that are collected by the SDK. This is required to be able to view function call metrics, call trees, and flamegraphs.

Finding builds with missing dSYMs

  1. Click the Applications tab in the Specto dashboard sidebar
  2. Click your application from the list
  3. Find application versions that have an Upload dSYM files for version... button in the Artifacts column:
Versions that do not have debug symbols have an "Upload dSYM files" button next to themVersions that do not have debug symbols have an "Upload dSYM files" button next to them

Versions that do not have debug symbols have an "Upload dSYM files" button next to them

Builds where all of the necessary dSYMs have been uploaded will show *All artifacts uploaded` instead, as you can see in the screenshot.

Click the button to select a ZIP of dSYM files to upload.

Enabling dSYM generation

Xcode may not be producing dSYM files during the build process. By default, dSYM generation is enabled for Release builds and disabled for Debug builds. To enable dSYM generation:

  • Select the project in the Xcode Project navigator
Select the project in the Xcode Project navigatorSelect the project in the Xcode Project navigator

Select the project in the Xcode Project navigator

  • Select your app target, select the Build Settings tab, and then select All and Combined
Open the Build Settings for the application target in XcodeOpen the Build Settings for the application target in Xcode

Open the Build Settings for the application target in Xcode

  • Search for Debug Information Format in the search bar, and change the setting to DWARF with dSYM File
Set Debug Information Format to DWARF with dSYM FileSet Debug Information Format to DWARF with dSYM File

Set Debug Information Format to DWARF with dSYM File

Finding dSYMs for Debug/Release builds

For local builds that are not published to the App Store or TestFlight, the dSYMs are generated in the build products directory:

  • Copy the path to the build products directory by switching to the Report navigator in Xcode, selecting the latest Build action, and expanding the contents of the CreateBuildDirectory action (there may be more than one, the one we're looking for is the one that has Build/Products as a suffix):
Finding the CreateBuildDirectory action in the Xcode Report navigatorFinding the CreateBuildDirectory action in the Xcode Report navigator

Finding the CreateBuildDirectory action in the Xcode Report navigator

  • Run the following commands in your Terminal to find the list of dSYMs in the build products directory:
cd <build products directory path you copied from Xcode>
find . -type d -name "*.dSYM" | while read -r line; do dwarfdump -u "$line"; done

This will print a list of dSYM file paths along with their UUID and architecture:

UUID: 127E8AAF-2D19-3232-AB76-26546F03B3A4 (x86_64) Debug-iphonesimulator/ExampleiOS.app.dSYM/Contents/Resources/DWARF/ExampleiOS
UUID: 0B78F43D-A20B-305B-A909-4C68975A9F30 (x86_64) Debug-iphonesimulator/DominantColor.framework.dSYM/Contents/Resources/DWARF/DominantColor

If the list is too long, you can pipe the output to grep -i to look for a specific UUID, for example:

find . -type d -name "*.dSYM" | while read -r line; do dwarfdump -u "$line"; done | grep -i 127E
UUID: 127E8AAF-2D19-3232-AB76-26546F03B3A4 (x86_64) Debug-iphonesimulator/ExampleiOS.app.dSYM/Contents/Resources/DWARF/ExampleiOS

Finding dSYMs for Archive builds

If you create an Archive build for Xcode (in preparation for a release), you can extract the dSYMs directly from the .xcarchive file that Xcode generates:

  • In Xcode, go to the Window menu and Click Organizer
Opening the Xcode OrganizerOpening the Xcode Organizer

Opening the Xcode Organizer

  • Select your app from the sidebar, find the archive for the version of the app you're looking for in the list, right click on it, and click Show in Finder
Finding the archive in the Xcode OrganizerFinding the archive in the Xcode Organizer

Finding the archive in the Xcode Organizer

  • Right click the xcarchive file in Finder and click Show Package Contents
Opening an xcarchive bundle by right clicking > Show Package ContentsOpening an xcarchive bundle by right clicking > Show Package Contents

Opening an xcarchive bundle by right clicking > Show Package Contents

  • Navigate to the dSYMs directory to find all of the dSYM files in the archive. You can run dwarfdump -u on these files from your Terminal to check their UUID and architecture.
Navigating to the dSYMs directory inside the xcarchive bundleNavigating to the dSYMs directory inside the xcarchive bundle

Navigating to the dSYMs directory inside the xcarchive bundle

Finding dSYMs for Bitcode builds (App Store or TestFlight)

If you submit an app with bitcode enabled to the App Store or TestFlight, Apple generates new dSYMs for you that will need to be downloaded and uploaded to Specto. There are two ways to download the Apple-generated dSYMs:

Download from App Store Connect

  • Log in to App Store Connect
  • Navigate to My Apps, select your app, and then choose Activity
  • Select the build you want to download dSYMs for
  • Click Build Details > Download dSYM

Download from Xcode Organizer

  • Follow the steps above from Finding dSYMs for Archive builds to open the Organizer and select the app and archive you want to download bitcode dSYMs for
  • Click the Download Debug Symbols button
Downloading debug symbols from the Xcode OrganizerDownloading debug symbols from the Xcode Organizer

Downloading debug symbols from the Xcode Organizer

  • The dSYMs will be downloaded to the same dSYMs folder within the xcarchive that is described in the Finding dSYMs for Archive builds section

Uploading dSYMs to Specto

dSYMs can be uploaded either via the application settings in the Specto dashboard (as described in the beginning of this article), or via the specto-upload-symbols tool. The integration of the specto-upload-symbols tool with the Xcode build process is described in the iOS integration guides:

In addition to being integrated as an Xcode Run Script build phase, the tool can also be manually invoked outside of Xcode to upload dSYMs. Run specto-upload-symbols -h to print usage instructions.