Crash symbolication

Bugsee is able to properly process and symbolicate crash reports that are uploaded from your users. Even if your binary has its symbol stripped, Bugsee will do wonders guessing the right symbols. In some cases it might be enough to root cause the problem, however best results will be achieved when Bugsee can match a crash report with a symbol file (dSYM) of crashed build.

Bugsee can automatically upload dSYM files during the build phase. The system is smart enough to match the right dSYM to a crash report.

Auto dSYM upload

See the screen show below and follow the instructions to set up an automatic uploading of your dSYM files.

Build phase

  • Add an extra "Run Script" build phase to your project
  • Paste the following script into it and don't forget to change your_app_token with the one you use for initializing the SDK
    SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'BugseeAgent' | head -1)
    if [ ! "${SCRIPT_SRC}" ]; then
        echo "Error: BugseeAgent script not found !!!"
        echo "If you link Bugsee.framework from outside the project folder, please copy the script"
        echo "into your main project directory or manually update SCRIPT_SRC variable with the right path"
        exit 1
    fi
    /usr/bin/python "${SCRIPT_SRC}" <your_app_token>

The script above finds the BugseeAgent helper utility within your project folder (location may vary). For optimization purposes you can modify the script with the direct link to BugseeAgent in your particular folder structure.

Debug builds

You must also make sure that dSYM files are being created in debug configuration as well, as usually that is not the case:

dSYM generation

In case you are are using CocoaPods frameworks with use_frameworks! attribute enabled, you might want to add the following post install hook to the end of your Podfile to make sure dSYM for all the frameworks are being generated as well:

#...end of Podfile...
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['DEBUG_INFORMATION_FORMAT'] = 'dwarf-with-dsym'
    end
  end
end

Manual dSYM upload

In some cases you might need to upload dSYM files manually. Bugsee accepts .zip files with one or multiple dSYM files inside. Once you have located the files and compressed them into an archive, click on the "Manual upload" button within Bugsee and either drag your files over the dialog or click on it to open the file browser:

Manual upload

Once a dSYM file is uploaded manually, we are going to re-process old issues related to that specific build, the process might take some time, usually several minutes.

Bitcode enabled builds

When you submit Bitcode-enabled builds to Apple Appstore, the dSYM files generated locally in your Mac are not going to be helpful in symbolication process due to the fact Apple is recompiling your apps before distributing them to the users. Proper dSYM should be obtained from Apple and the uploaded to Bugsee to process your crash reports. Follow the steps below to obtain the dSYM files:

Downloading dSYM files using XCode

  1. Go to your Xcode Organizer, point to the build you submitted and click on the “Download symbols"

    Download symbols

  2. Right click on the build and select “Show in Finder”:

    Download symbols

  3. Once in Finder, right click on the package and select on “Show package contents”

    Download symbols

  4. Inside the dSYM folder you should find several files which correspond to symbol files for different architectures. Compress them and upload them following the procedure for manual dSYM uploading.

    Download symbols

Downloading dSYM files using iTunes Connect

  1. Locate your build in iTunes connect and click on the Download dSYM link

    iTunes Connect

  2. Upload the zip file you just downloaded directly to Bugsee by following the procedure for manual dSYM uploading. If your build has multiple architectures and/or multiple binary files, all the dSYM files are already included in the zip file and will be processed automatically.

Fastlane dSYM upload

Bugsee supports fastlane for uploading dSYM files by providing a fastlane plugin with upload_symbols_to_bugsee action.

Add bugsee fastlane to your project:

fastlane add_plugin bugsee

For uploading symbols during build(gym) (non-bitcode case):

lane :mybuildlane do
  gym(
        # your settings for the bild
  )
  upload_symbols_to_bugsee(
        app_token: "<your_app_token>",
  )
end

For refreshing dSYM files from iTunes connect (bit-code case):

lane :refresh_dsyms do
  download_dsyms(
        build_number: "1819" # optional, otherwise it will download dSYM for all builds
  ) # Download dSYM files from iTC
  upload_symbols_to_bugsee(
        app_token: "<your_app_token>",
  )
  clean_build_artifacts           # Delete the local dSYM files
end