Analyzing Crash Reports

After you distribute your app for testing by using TestFlight or after you make it available on the store, routinely download and analyze crash reports. When an app crashes, the system creates a crash log that describes the conditions under which the app terminated, in most cases including a complete stack trace for each executing thread. Apple provides a crash report service that collects and aggregates user crash logs. Crash reports are available for apps, WatchKit extensions, and other app extensions.

Alternatively, view crash logs directly on devices or import crash reports, as described in Viewing and Importing Crashes in the Devices Window. For example, if you distribute your app outside of the store, you can solicit crash reports directly from users and import them into Xcode.

About the Crash Report Service

Apple provides a service that allows you to download crash reports for the most recent app versions and builds that you distribute through the store. The service collects and groups similar crash logs into crash reports. Each build of an app may have multiple crash reports and each crash report may contain multiple crash logs. However, crash logs are not sent to Apple unless the user agrees to share crash data with app developers. TestFlight users automatically agree to share crash data. The service does the following to generate crash reports:

Xcode displays information about crash reports in the Crashes organizer:

../Art/7_AboutCrashesOrganizer.shot/Resources/shot_2x.png../Art/7_AboutCrashesOrganizer.shot/Resources/shot_2x.png

Before Viewing Crash Reports

Perform all these steps to fully enable the crash report service. If you previously uploaded an app with symbols to iTunes Connect and distributed it using TestFlight or the store, you may already see crash reports in the Crashes organizer. If you do not see crash reports in the the Crashes organizer, verify that you have performed these steps.

Step

../Art/checkbox_checked_2x.png

In Xcode, enter an Apple ID in Accounts preferences that belongs to the Apple Developer Program, as described in Adding Your Apple ID Account in Xcode.

../Art/checkbox_checked_2x.png

Set the version and build number, as described in Setting the Version Number and Build String. If you are distributing another build of your app, increment the build string.

../Art/checkbox_checked_2x.png

Create a single app archive and upload it to iTunes Connect with symbols, as described in Uploading Your App to iTunes Connect. (Ensure that the “Include app symbols for your application…” box is checked before you click Submit.)

Do not delete archives that you upload to iTunes Connect.

../Art/checkbox_checked_2x.png

In iTunes Connect, distribute the app to testers using TestFlight, as described in TestFlight Beta Testing (Optional), or submit the app for review, as described in Submitting the App to App Review.

../Art/checkbox_checked_2x.png

Users who download your app from the store need to agree to share crash data with app developers, as described in Sharing Crash Data with App Developers. (TestFlight users automatically agree to share crash data.)

../Art/checkbox_checked_2x.png

In Xcode, to view crash reports, enter an Apple ID that is a team agent or admin, or an iTunes Connect user, as described in Adding Your Apple ID Account in Xcode.

../Art/checkbox_checked_2x.png

In Xcode, to go from a stack frame in the Crashes organizer to the source code in debug navigator, open the Xcode project that you archived and uploaded to iTunes Connect.

Also, allow up to three days between when you first distribute your app and when crash reports appear in Xcode. To maintain a good user experience, crash data is sent from user devices to Apple when the user allows.

Viewing Crash Reports in the Crashes Organizer

The Crashes organizer displays crash reports for all the apps developed by all your teams.

To view crash reports

  1. In the organizer, click Crashes.

    ../Art/7_ViewingCrashReportSteps.shot/Resources/shot_2x.png../Art/7_ViewingCrashReportSteps.shot/Resources/shot_2x.png
  2. In the left column, select an app or local archive from the list.

    The list of apps is obtained from iTunes Connect and includes information about every version and build you uploaded to iTunes Connect.

  3. At the top of the second column, choose a version and build from the pop-up menu.

    Xcode begins refreshing the crash reports for the version and build you select. Xcode downloads the top 25 crash reports—crash reports with the most number of occurrences on unique devices—that occurred during the past two weeks.

  4. In the second column, select a crash report.

    The title of the crash report defaults to the stack frame where the crash likely occurred. The number of unique device occurrences of the crash appears below the crash title. Crash reports for a WatchKit extension are denoted with a watch icon (../Art/app_extension_watch_icon.shot/Resources/shot_2x.png) and crash reports for other app extensions are denoted with a puzzle icon (../Art/app_extension_icon.shot/Resources/shot_2x.png).

  5. In the detail area, view the crash logs.

    The detail area displays the stack trace for each thread. The stack frame where the crash occurred is highlighted in orange.

  6. In the inspector, add information and view statistics about a crash report.

Viewing and Finding Crash Reports

In the crash report list, perform these actions:

../Art/7_select_crash_reports.shot/Resources/shot_2x.png

In the detail area, perform these actions:

Editing Information About Crash Reports

As you resolve issues, you can store information about crash reports locally.

In the crash report list, perform these actions:

In the detail area, perform this action:

../Art/7_view_crash_reports.shot/Resources/shot_2x.png

In the inspector, perform this action:

Opening the Source Code in the Debug Navigator

In the detail area, perform these actions:

In the inspector, perform this action:

../Art/7_inspect_crash_reports.shot/Resources/shot_2x.png

Xcode opens the associated project and displays the line of code in the debug navigator.

../Art/7_jump_to_source.shot/Resources/shot_2x.png../Art/7_jump_to_source.shot/Resources/shot_2x.png

Viewing Statistics About Crash Reports

View the crash data over the past two weeks by device type, operating system, and date. To change the device type, choose Device Type from the pop-up menu. To change the operating system, choose Operating System from the pop-up menu.

../Art/7_view_statistics.shot/Resources/shot_2x.png

Sharing Crash Data with App Developers

Apple can’t provide crash reports if users don’t share the crash data with app developers. If a user reports a crash and you don’t have a corresponding crash report, ask the user to share the crash data with app developers. Crash data is automatically sent to Apple for TestFlight apps but not apps the user downloads from the store.

Give these instruction to users. On all platforms, the crash data option is in the Diagnostics section of the Privacy settings.

To share crash data with iOS developers

  1. In Settings, tap Privacy.

  2. Scroll to the bottom and tap Diagnostics & Usage.

    ../Art/7_ios_privacy_settings.shot/Resources/shot_2x.png
  3. If necessary, tap the Share With App Developer switch to enable it.

Similarly, ask Mac users to share their crash data with app developers.

To share crash data with Mac developers

  1. In System Preferences, click Security & Privacy.

  2. Click Privacy and in the left column, click Diagnostics & Usage.

    ../Art/7_mac_privacy_settings.shot/Resources/shot_2x.png../Art/7_mac_privacy_settings.shot/Resources/shot_2x.png
  3. Select “Share crash data with app developers.”

    To enable the Privacy options, click the lock icon. In the dialog that appears, enter the credentials for a system account with admin privileges and click Unlock.

Apple TV users can also share their crash data.

To share crash data with tvOS developers

  1. In Settings, click General and click Privacy.

  2. Under Diagnostic Data, click “Share with App Developers.”

  3. In the dialog that appears, click “Send to Apple.”

Viewing and Importing Crashes in the Devices Window

In the Devices Window, you can view details about a crash log directly on a device or import crash reports you receive from other sources. If you have an archive containing the matching build and .dSYM files, Xcode automatically symbolicates crash reports. Xcode replaces the memory addresses in the crash log with human-readable function names and line numbers. Then you can view the stack trace for each execution thread in the Devices window.

For this reason, do not delete archives that you upload, export, and distribute to users. For example, if you distribute your app using an ad hoc provisioning profile or team provisioning profile (read Exporting Your App for Testing (iOS, tvOS, watchOS) and Exporting Your App for Testing (Mac)), retain the archive so you can import unsymbolicated crash reports you receive from testers.

You can also view crashes for apps distributed using TestFlight or the store. If you include bitcode when you upload your app, the store retains the .dSYM files and you must download them before you can view crashes in the Devices window. If you don’t include bitcode or distribute your app outside the store, your archive already contains the .dSYM files.

If you include bitcode when you upload your app, download the associated .dSYM file first.

To download the dSYMs files

  1. In the Archives organizer, select the archive.

  2. Click the Download dSYMs button.

    Xcode inserts the .dSYM files in the selected archive.

To view crash logs on a device or import a crash report

  1. Choose Window > Devices.

  2. If necessary, connect your device to your Mac.

  3. Select the device under Devices, and click the View Device Logs button.

    ../Art/7_viewdevicelogs_2x.png

    A sheet appears displaying the crash logs on the device.

  4. To view a crash log, select it in the left column.

    View the crash log in the detail view on the right.

  5. To import a crash report, drag the crash report from the Finder to the left column of the sheet.

  6. Click Done.

Reproducing Crashes in Xcode

Make sure to test the exact same build that crashed. Save all the archives that you distribute for testing or upload to iTunes Connect. Verify that the archive in Xcode matches the crash report by comparing the build and version numbers. Follow these same steps to determine if you’re testing the same build that you submitted to the store.

For Mac apps, to reproduce a crash, use a guest account with a fresh install of the version of OS X that matches the crash report. Don’t attempt to recreate a crash using a developer or admin system account, because the problems you want to analyze may not occur.

Supported Crash Reports

Crash logs are collected from apps running on these operating system releases and viewable in these Xcode releases.

Crashes of target

Running OS

Available in

iOS app

iOS 8.2 and later

Xcode 6.3 and later

iOS app extension

iOS 8.3 and later

Xcode 7.0 and later

Mac app

OS X 10.10 and later

Xcode 7.0 and later

Mac app extension

OS X 10.11 and later

Xcode 7.1 and later

tvOS app

tvOS 9.0 and later

Xcode 7.2 and later

WatchKit extension

watchOS 2 app paired with iOS 9.1 app

Xcode 7.1 and later