Splunk MINT SDK for iOS

Splunk MINT SDK for iOS Developer Guide

Download manual as PDF

Download topic as PDF

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.  New run script.png
    
  6. In the script editor, add the following script:
  7. 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.)

  8. 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.
PREVIOUS
Requirements and installation for iOS
  NEXT
Add Splunk MINT to your iOS project

This documentation applies to the following versions of Splunk MINT SDK for iOS: 5.2.x


Comments

I added a few links above to indicate where in MINT Management Console to find the values for the API token and API key.

Apruneda splunk, Splunker
February 28, 2017

The tokens and keys used by MINT are described here: http://docs.splunk.com/Documentation/MintIOSSDK/5.2.x/DevGuide/AboutSplunkMINTSDKs#What_are_the_keys_and_tokens_used_by_MINT.3F.
Typically you use the same API token for everything (your single MINT account), and then the API key for an individual app project under the account.

For automated builds we recommend using the build script above under "Configure server-side symbolication". The owner of the project needs to use their API key and the MINT account's API token for symbolication to work as
intended. Ownership might be unclear due to teams, so the MINT Management
Console displays the owner and API key for each project on the main
dashboard. Teams and project owners are defined in MINT Management Console.

At this time, we don¹t support a virtual build user account because API keys belong to individual users.

Apruneda splunk, Splunker
February 28, 2017

Another question that would be nice to find answered here would be some guidance about the relationship between user's API tokens and use of the dSYM upload script/APIs. Can any user's API token be used? Must it be an API token associated with a user that has access to the project in which the symbolication file will be uploaded? That is, is there some kind of enforcement of uploads wrt the API token?

Finally, is there a recommended Best Practice for automated builds and continuous integration systems and the API token? Eg. Should we create a "virtual build system user" and use that user's API token for dSYM uploads?

Kulick
February 27, 2017

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters