Diagnosing Issues Using Crash Reports and Device Logs

Use crash reports and device logs to debug app issues.

Overview

Customers expect apps to be stable, free of bugs, and use system resources efficently. The operating system helps you meet these expectations by collecting different log types you can use to diagnose issues in your app:

  • Crash reports describe how your app terminated, and document the code running on each thread at the time of the crash.

  • Jetsam event reports describe the system-memory conditions under which the operating system terminated an app.

  • Device console logs contain detailed information on operations that occur in both the operating system and apps.

Distribution builds of your app, such as for the App Store, an enterprise enviroment, or a testing team, require you to use crash reports and device logs to diagnose issues encounterd by your customers. Distribution builds don’t contain the necessary entitlements for debugging in Xcode.

Address Stability Issues Using Crash Reports

Crash reports are the most common type of log you’ll use when diagnosing an issue. When receiving crash reports for your app, use them to understand the stability problems the app is having. A crash report describes how your app terminated, and also contains the complete backtrace of each thread, which shows the code running at the time of the crash.

To debug a problem using a crash report:

  1. Build Your App With Symbol Information and retain the Xcode archive before distributing the app.

  2. Retrieve a crash report for an issue. See Acquiring Crash Reports and Diagnostic Logs for the different ways you can retrieve crash reports.

  3. Symbolicate the Crash Report in Xcode to convert the hexadecimal addresses into identifiable symbol names

  4. Analyze the crash report to identify the issue.

  5. Update your code to fix the issue.

  6. Add tests with the XCTest framework to ensure the issue doesn’t reoccur in the future.

Uncover Memory Inefficiencies Using Jetsam Event Reports

Ensure that your apps use memory efficiently. When an app on iOS, iPadOS, watchOS, or tvOS uses memory inefficiently, less memory is available for other apps to remain in memory in the background. This lower available memory limits how quickly a user can switch between apps, because apps can’t resume from memory and must first complete a full app launch.

When the operating system experiences low-memory conditions, and requires more memory than is currently free, the device’s operating system can terminate apps to reclaim the memory they’re using. A jetsam event report describes the system-memory conditions under which the operating system terminated an app. See Locate Crash Reports and Memory Logs On The Device for how to access these logs and Identifying High-Memory Use with Jetsam Event Reports for information on intrepreting a jetsam event report.

Jetsam event reports don’t contain stack traces of executing threads in an app, but they do contain additional system information about memory use. When your app crashes due to memory pressure, see Gathering Information About Memory Use to understand your app’s memory use patterns, and Responding to Low-Memory Warnings to learn when to lower your memory use.

Diagnose Problems Using Device Console Logs

Apple devices maintain a continuous in-memory transcript of operations in the operating system and individual apps. These logs can be reviewed after an issue occurs. Some issues, such as problems installing an app, can be diagnosed by reviewing the operating system logs using the Console app on macOS. See Access Device Console Logs for instructions on accessing a device’s console log.

Add log messages for your app to the operating system’s log with the Logging framework. The logs you provide can contain additional grouping and labeling information to assist with tracing an issue from the original user action. This information is useful for diagnosing complex interactions, such as debugging the interaction between your app and one of its app extensions.

Topics

Essentials

Acquiring Crash Reports and Diagnostic Logs

Gather crash reports and device logs from the App Store, TestFlight, and directly from devices.

Crash Reports

Adding Identifiable Symbol Names to a Crash Report

Replace hexadecimal addresses in a crash report with function names and line numbers that correspond to your app’s code.

Device Logs

Identifying High-Memory Use with Jetsam Event Reports

Discover why the operating system terminated your app when available memory was low.

Logging

Efficiently capture telemetry from your app for debugging and performance analysis.

See Also

Debugging

Running Your App in the Simulator or on a Device

Launch your app in a simulated iOS, tvOS, or watchOS device or on a device connected to your Mac.

Improving Your App's Performance

Model, measure, and boost the performance of your app by using a continuous-improvement cycle.

Building Your App To Include Debugging Information

Configure Xcode to produce the symbol information for debugging and crash reports.