Skip to main content

Symbolicate

Crash reports are a lot more useful when you see your symbolicated application frames.

Introduction​

In order for crash reports to be symbolicated, you need to upload your dSYM files to Shake.

Unsymbolicated crash reports will appear in the special section of your Shake dashboard. You will see UUIDs of the required dSYM files which you can then find on your system.

Enable dSYM files for debug builds​

If you plan using crash reporting in a development environment, every debug build action needs to generate dSYM files. When in your project:

  1. Click your App.xcodeproj blue project icon usually located at the top of the File Inspector tab in your left-hand pane
  2. Select your main app target
  3. Open Build Settings for that target
  4. Navigate to the Build Options section
  5. Choose dwarf with dSYM file option for your Debug/Development configuration

Find dSYM files​

Run this command in your terminal to list all available dSYM files found on your system so you can identify the ones that are missing:

mdfind -name .dSYM | while read -r line; do dwarfdump -u "$line"; done

Upload manually to Shake dashboard​

Locate your app's dSYM files: Xcode → Preferences → Locations → Derived Data → click the Finder folder link.

For archived apps with Bitcode enabled, which have already been uploaded to the App Store, visit Xcode → Window → Organizer to manually download the App Store generated debug symbols by clicking the Download Debug Symbols button on the right hand pane.

Now zip the symbolication files.

To upload dSYM files to the Shake dashboard:

  1. Visit Workspace administration → Apps
  2. Click your app name to expand it
  3. Click the Mapping files button
  4. Drag and drop your zipped symbolication files there

Upload dSYM files using RunPhase script​

note

Use this method if your app doesn't use Bitcode binary format.

Shake ships with the upload-symbols.sh script which uploads dSYM files to Shake servers.

To ensure that the latest dSYM files are automatically uploaded after every build process, add a new Run Script Phase: Xcode → Scheme → EditScheme → expand the Build Action options → Post Actions → +

Paste this script but make sure to replace your-api-client-id and your-api-client-secret with the actual values you have in your workspace administration:

Path/to/upload-symbols.sh \
--client_id your-api-client-id \
--client_secret your-api-client-secret

If your crash reports are not being symbolicated, make sure the script is working properly by doublechecking the Xcode Build log for Shake upload script errors. When looking at the Build log, search for the "SHAKE_SCRIPT" keyword to identify potential problems and see whether the upload was successful.

Upload dSYM files using fastlane plugin​

note

Use this method if your app has Bitcode format enabled.

fastlane is an open source app automation platform (docs). You can use it to automate App Store Connect authentication and downloading of dSYM files.

Install fastlane​

First, run the bundle init command in your terminal which will generate the Gemfile like this one:

Gemfile
source "https://rubygems.org"
gem "fastlane"

Then, run the bundle install command to install fastlane and associated dependencies.

Lastly, navigate your terminal to your project's directory and run the fastlane init command.

Install Shake plugin​

Terminal
bundle exec fastlane add_plugin upload_symbols_to_shake

Use the plugin​

If you have Bitcode enabled in your app's project settings, dSYM files are generated by the App Store when your app is recompiled after the upload. fastlane will need to download them.

In this case, use Shake with download_dsyms to upload dSYM files:

Fastfile
lane :refresh_dsyms do
    download_dsyms(version: "latest")
    upload_symbols_to_shake(client_id: "<Shake client id>", client_secret: "<Shake client secret>", bundle_id: "<Bundle id of project>",  plist_path: "<Path to Info.plist>")
end

You can find your <Shake client id> and <Shake client secret> in your workspace administration.

On the other hand, if you have Bitcode disabled, add the upload_symbols_to_shake action with gym to upload dSYMs generated from the build:

Fastfile
lane :refresh_dsyms do
    gym
        upload_symbols_to_shake(client_id: "<Shake client id>", client_secret: "<Shake client secret>", bundle_id: "<Bundle id of project>", plist_path: "<Path to Info.plist>")
end

Or, you can pass the dSYM file paths manually:

Fastfile
upload_symbols_to_shake(client_id: "<Shake client id>", client_secret: "<Shake client secret>", bundle_id: "<Bundle id of project>", dsym_array_paths: ["./App1.dSYM.zip", "./App2.dSYM.zip"],  plist_path: "<Path to Info.plist>")