Symbolication

Explained here is how to symbolicate your crashes to get more details from stack traces for your iOS apps.

Symbolication is a required process to translate your crash reports into a readable format. For Luciq to be able to successfully symbolicate your crashes, make sure you always upload the needed dSYMs. Every new app version or build generates new files.

There are two types of dSYM files:

1. Required dSYM files are used to symbolicate your application's frames. In the screenshot below, only the required dSYM is missing.

2. Optional dSYM files are used to symbolicate the frames belonging to any plugin or library you are using.

With Bitcode

When you have Bitcode enabled in your project's settings, the dSYM files you have locally on your machine won't successfully symbolicate the crashes coming from the App Store or App Store Connect. The correct dSYM files are generated by App Store Connect after recompiling your uploaded app on App Store Connect or the App Store. However, crashes coming from a local build or distributed through non-Apple channels can be treated as if Bitcode is disabled, and you can follow the instructions here.

You can either manually download the needed files from App Store Connect or automatically upload them to Luciq through Fastlane.

Using Manual Upload - With Bitcode

To symbolicate your crashes, download your dSYM ZIP archive from App Store Connect, then upload them to your Luciq dashboard.

1. In Xcode, select Window then Organizer.

2. Under the Archives tab, select an archive with the app version you need to symbolicate crashes from.

3. Click the Download dSYMs... button. Xcode will insert the .dSYM files into the selected archive.

4. View the archive by right-clicking on it in Xcode and selecting Show in Finder.

5. Right-click on the archive and select Show Package Contents, then open the dSYMs directory.

6. Compress all the .dSYM files you find in that directory and upload the archive to the Luciq dashboard.

Using Fastlane - With Bitcode

If you're already using Fastlane to automate your mobile development process, you can benefit from our Luciq/Fastlane plugin to automatically upload your dSYM files to Luciq.

To get started, whether you have Bitcode enabled or not, you can follow the instructions explained below.

Installing Fastlane

1. If you don’t have Fastlane, open your terminal and navigate to your project then run the next command to install it:

Shell

sudo fastlane init

1. If you don’t have the latest Fastlane version installed, run the following command:

Shell

sudo gem install fastlane

Installing Luciq Plugin

1. Open your Gemfile inside your project directory and add the following:

Ruby

gem 'fastlane-plugin-luciq_official', '~> 0.2.1'

1. Run the following to install our official Fastlane plugin:

Shell

sudo gem install fastlane-plugin-luciq_official

Using the Plugin

1. With the plugin installed, you can navigate the project using Finder, open the Fastlane directory, then open the Fastfile.

2. Inside the Fastfile, you can create a new lane and name it upload_dsyms, for example, then add the following inside your lane implementation:

Lane

luciq_official(api_token:<Luciq Token>, dsym_array_paths:<Array of dsyms paths>)

#-------Example Below-------
luciq_official(api_token: <Luciq-Token>, dsym_array_paths: ['/Users/admin/Desktop/dsyms/Alamofire.framework.dSYM', '/Users/admin/Desktop/dsyms/Luciq.framework.dSYM', '/Users/admin/Desktop/dsyms/SDWebImage.framework.dSYM'])

1. If you don't have any dSYMs' paths, you can use Fastlane to install them from AppStoreConnect. To do so, you'll need to add the next few lines of code inside your lane:

Lane

download_dsyms(version: 'latest')
luciq_official(api_token:<Luciq Token>,
     dsym_array_paths:[ ])

This will require you to pass your AppStoreCredentials and application's BundleId to install the dSYMs locally. Our plugin will then take care of uploading them to your Luciq dashboard.

1. The final step is to run the following command:

Shell

sudo bundle exec fastlane upload_dsyms

Without Bitcode

When you have Bitcode disabled in your project's settings, the dSYM files Luciq needs to symbolicate your crashes are available locally on your machine. You can either find them locally and upload them manually to your Luciq dashboard, automate it through an Xcode Build Phase script, or upload them through Fastlane.

Using Manual Upload - Without Bitcode

First, you need to find the needed dSYM files on your machine. You can find the command bellow to find the file that belongs to a specific UUID.

Shell

mdfind "com_apple_xcode_dsym_uuids == your-UUID-here"

On your Luciq dashboard, you will find all your missing files and the commands needed to allocate the files locally as displayed below.

An example warning message in the crashes page of your dashboard that alerts you about a required dSYM file that is missing.

After, finding the dSYM files locally, upload them to your dashboard as explained below:

1. Compress the dSYM file you have located on your machine into a zip file.

2. Go to Upload dSYMs in the Settings menu of your Luciq dashboard.

3. Upload the compressed file.

Using Xcode Build Phase Script - Without Bitcode

Luciq has a shell script that can automatically upload your project's dSYM during the build process. To use it, go to your project's Build Phases tab and add a new Run Script Build Phase, then add the following to it.

Shell

#- -- SCRIPT BEGIN - --
# SKIP_SIMULATOR_BUILDS=1
  SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Luciq_dsym_upload.sh' | head -1)
  if [ ! "${SCRIPT_SRC}" ]; then
    echo "Luciq: err: script not found. Make sure that you're including LuciqResources.bundle in your project directory"
    exit 1
  fi
  APP_TOKEN="YOUR-APP-TOKEN-HERE"
  source "${SCRIPT_SRC}"
#- -- SCRIPT END - --

Make sure you replace YOUR-APP-TOKEN-HERE with your actual app token (found under SDK Integration in the Settings menu of your Luciq dashboard.

If you're using Xcode 10, you will need to add the previous script to the Archive > Post-actions.

Using Fastlane - Without Bitcode

If you're already using Fastlane to automate your mobile development process, you can benefit from our Luciq/Fastlane plugin to automatically upload your dSYM file to Luciq.

POST API

In addition to the options explained above, you can use our POST API to upload your dSYM files directly from your console. The input file must be passed as a zip file.

Shell

URL:
/api/sdk/v3/symbols_files
METHOD:
POST
PARAMS:
symbols_file
os (android, ios,,,)
application_token

Troubleshooting

Debug Builds

To enable crash symbolication for debug builds, you have to change your project's build settings to generate dSYM files for debug builds.

To do so, select your target in Xcode then go to Build Settings, search for Debug Information Format, and change its value to DWARF with dSYM File.

Missing dSYMs on App Store Connect

On App Store Connect, you may find several missing dSYM files that belong to the third party frameworks you're including in your app. For better accuracy, Apple requires the bcsymbolmap files to be included in your project archive that you upload. However, by default the bcsymbolmap are not included in the archive file generated by Xcode.

To automatically add the needed files in your Xcode archive, add the following script, in your Post Archive Action.

__hidden in Stack Traces

If you have stack traces that contain frames that have __hidden instead of a symbol name, this is because you did not share your app's symbols with Apple while uploading a build to iTunes Connect.

To make sure stack traces of crashes from your app do not contain any hidden symbols, always check Upload your app's symbols to receive symbolicated reports from Apple when uploading a new build.

With this option unchecked, dSYMs generated by iTunes Connect for apps that have Bitcode enabled will be obfuscated. To de-obfuscate those dSYMs, download them from iTunes Connect, then use the following command (substituting your archive and dSYM paths):

Shell

xcrun dsymutil -symbol-map ~/Library/Developer/Xcode/Archives/2017-11-23/MyGreatApp\ 11-23-17\,\ 12.00\ PM.xcarchive/BCSymbolMaps ~/Downloads/dSYMs/3B15C133-88AA-35B0-B8BA-84AF76826CE0.dSYM

Run this command for each dSYM file inside the dSYMs folder you downloaded from iTunes Connect. After that is complete, upload the updated dSYMs to Luciq to get fully symbolicated stack traces.