Configure your project for symbolication

What is symbolication?

Before you can analyze crash reports, the stack traces need to be symbolicated―that is, replacing memory addresses with human-readable function names and line numbers. These debug symbols are contained in dSYM bundles that are updated periodically.

When can I use symbolication?

Symbolication is supported when you use the MINT Data Collector to send data from your mobile apps to Splunk Enterprise.

If you are using the Splunk MINT App, you must set the MINT Data Collector token to enable symbolication.

You can configure symbolication on the server or on the device. However, server-side symbolication yields better symbolication results than device-side symbolication.

When is symbolication not supported?

Symbolication is not supported when using HTTP Event Collector. For more, see About Splunk MINT data collection.

If you use Swift, crash reports will not be fully symbolicated. Only your code is symbolicated, but Apple system libraries are not symbolicated, so crash reports will include some hexadecimal code.

Can I symbolicate Bitcode-enabled apps?

The Splunk MINT SDK for iOS supports Bitcode, but cannot automatically symbolicate crash reports for Bitcode-enabled apps.

When you enable Bitcode in your app, Apple recompiles the app for the Apple App Store. The resulting binary uses a different UUID that is not shared with MINT, so MINT cannot automatically download the corresponding dSYM bundles that are used to symbolicate your crash reports.

If you want your Splunk MINT crash reports to be symbolicated automatically, disable Bitcode by doing one of the following:

• Disable Bitcode for your app in Xcode (under Build Settings > Build Options, select "NO" for Enable bitcode.)
• Disable Bitcode for iOS targets in your app.
• Disable Bitcode in the Upload dialog box in the Xcode Organizer.

If you want to enable Bitcode in your apps but you also want your Splunk MINT crash reports to be symbolicated, you must manually configure symbolication by uploading dSYMs yourself. For details, see Configure symbolication for Bitcode-enabled apps.

Configure server-side symbolication

1. In Xcode, open your project and select the target.
2. Make sure that your binary name (usually the target name) contains only Latin characters (e.g., only those within ISO-8859-1 character set also known as Latin-1) and no spaces. Otherwise, symbolication may not be successful.
3. On the Build Settings tab, verify the following are set for all configurations (typically Debug and Release):
• Strip Debug Symbols During Copy: Yes
• Strip Linked Product: Yes
4. On the Build Phases tab, click the + symbol, then click New Run Script Phase.
5. In the script editor, add the following script:

   SCRIPT=`/usr/bin/find "${SRCROOT}" -name splunkmint_postbuild_dsym_upload_script.sh | head -n 1`
   
   /bin/bash "${SCRIPT}" "API_KEY" "API_TOKEN"

   To upload non-release dSYMs, add "-f" to the end of the script:

   SCRIPT=`/usr/bin/find "${SRCROOT}" -name splunkmint_postbuild_dsym_upload_script.sh | head -n 1`
   
   /bin/bash "${SCRIPT}" "API_KEY" "API_TOKEN" -f

   Be sure to replace API_KEY and API_TOKEN with the project's API key and project owner's API token, respectively.

   To find the API token and API key for a mobile app project, log in to MINT Management Console and find the project on the home page dashboard. The API key is displayed for each project, along with the project owner. Use the API token of the project owner—the project owner must log in to MINT Management Console, then go to Account > Account Info to find the API token.

   For more about keys and tokens, see What are the keys and tokens used by MINT? in this manual.

   Note This script is designed to run on released builds only. (The Xcode console displays symbolicated stack traces when you run your app in debug mode.)
6. To test the configuration, configure the project schema for release and build your project. If the build succeeds, symbolication should be set up correctly.

Configure on-device symbolication

You can symbolicate the crash reports on the device, although on-device symbolication does not provide as much useful information, such as the line of code that crashed your application.

Note Do not configure your mobile app for on-device symbolication if you are targeting iOS version 9.

1. In Xcode, open your project and select the target.
2. On the Build Settings tab, verify the following are set for all configurations (typically Debug and Release):
• Strip Debug Symbols During Copy: No
• Strip Linked Product: No
• Deployment Postprocessing: No
• Generate Debug Symbols: Yes

Configure symbolication for Bitcode-enabled apps

To enable symbolication for Bitcode-enabled apps, you must download the dSYM bundle that is provided to you by Apple, then upload this dSYM bundle to MINT. The easiest way to do this is by downloading the dSYM bundle at the same time you upload your app to the Apple App Store (archiving the application). If you forget to do this, you must find the version and build number for your app, download the corresponding dSYM bundles, then upload them to MINT.

Download dSYM bundles using Xcode Organizer after archiving your app

1. In Xcode, from the Xcode menu select Window > Organizer.
2. In Xcode Organizer, click the Archives tab.
3. Under iOS Apps, select your app from the list.
4. From the Version column, select the archive for your app, displayed as App Version (Build Uuid).
5. Click Download dSYMs to download the dSYM bundles from Apple.

Compress and upload dSYM bundles to MINT

1. In Finder, find the dSYM bundles (archive files) you just downloaded.
2. Right-click the archive file and select Show package contents.
3. Open the dSYMs folder.
4. Compress each dSYM file named with your app's build UUID to a ZIP file.
5. Open MINT Management Console by logging in to mint.splunk.com.
6. Select your app project.
7. Click the Settings dashboard.
8. Under Project Settings, click dSYMs.
9. Click Browse & Upload, then navigate to and select the dSYM bundles you compressed.

Find the version and build number of your app for missing dSYM bundles

1. Open MINT Management Console by logging in to mint.splunk.com.
2. Select your app project.
3. Click the Errors dashboard.
4. Click any error from the list.
5. Click Error Instances, then note the values for App Version and Build Uuid.