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. Set Debug Information Format option to dwarf with dSYM file for your Debug/Development configuration
note

On Xcode 16+ you should also set Enable Debug Dylib Support to No. This option affects how dSYM files are generated and should be disabled until we support it.

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 → Settings → Locations → Derived Data → click the Finder folder link.

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. Select Crash reports menu and click Choose a file button
  4. Drag and drop your zipped symbolication files there

Upload dSYM files using RunPhase script​

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: Product → Scheme → EditScheme → expand the Build options → Post Actions → +

Paste this script but make sure to replace app-api-key with the actual value you have in your app settings:

<path/to/upload-symbols.sh> --api_key <app-api-key>

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​

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​

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(api_key: "<App api key>", 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(api_key: "<App api key>", bundle_id: "<Bundle id of project>", dsym_array_paths: ["./App1.dSYM.zip", "./App2.dSYM.zip"],  plist_path: "<Path to Info.plist>")

You can find <App api key> in your app settings: