Symbolication

Upload dSYM files so Luciq can symbolicate your iOS crashes into readable stack traces. Covers required versus optional dSYMs and the POST API.

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.

Using Manual Upload

First, you need to find the needed dSYM files on your machine. You can find the command below 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 the Luciq CLI

You can also upload dSYM files from your terminal or CI pipeline using the Luciq CLI. Compress your dSYM files into a zip file, then run:

Shell

gem install luciq-cli
luciq login
luciq upload ios-dsym MyApp-dSYMs.zip --slug my-app --mode production

In CI, set LUCIQ_AUTH_TOKEN from your secret store instead of running luciq login. See the Uploading Symbol Files guide for all options.

Using Xcode Build Phase Script

⚠️ Important: Disable User Script Sandboxing

Starting with recent versions of Xcode, a build setting called User Script Sandboxing is enabled by default for new projects.

This setting must be disabled for the Luciq dSYM upload script to run correctly

How to disable

1. Open your project in Xcode
2. Select your project → Build Settings
3. Search for User Script Sandboxing
4. Set User Script Sandboxing to NO
5. Apply the setting to all relevant targets (Debug & Release)

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

# Check PROJECT_DIR first (CocoaPods, Carthage, Manual)
SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Luciq_dsym_upload.sh' | head -1)

# If not found, check SPM location
if [ -z "$SCRIPT_SRC" ]; then
  SCRIPT_SRC=$(find "$BUILT_PRODUCTS_DIR" -name 'Luciq_dsym_upload.sh' | head -1)
fi

if [ -z "$SCRIPT_SRC" ]; then
  echo "Luciq: err: script not found. Make sure the Luciq SDK is properly installed."
  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.

Using Fastlane

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.

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. The final step is to run the following command:

Shell

sudo bundle exec fastlane upload_dsyms

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.