KSCrash

🚀 KSCrash 2.0 Released!

KSCrash 2.0 is now available with significant improvements and enhancements. If you are upgrading from version 1.x, please refer to the migration guide for details on transitioning to the latest version:

➡️ Migration Guide for KSCrash 1.x to 2.0

Another crash reporter? Why?

Because while the existing crash reporters do report crashes, there's a heck of a lot more that they COULD do. Here are some key features of KSCrash:

• On-device symbolication in a way that supports re-symbolication offline (necessary for iOS versions where many functions have been redacted).
• Generates full Apple reports, with every field filled in.
• 32-bit and 64-bit mode.
• Supports all Apple devices, including Apple Watch.
• Handles errors that can only be caught at the mach level, such as stack overflow.
• Tracks the REAL cause of an uncaught C++ exception.
• Handles a crash in the crash handler itself (or in the user crash handler callback).
• Detects zombie (deallocated) object access attempts.
• Recovers lost NSException messages in cases of zombies or memory corruption.
• Introspects objects in registers and on the stack (C strings and Objective-C objects, including ivars).
• Extracts information about objects referenced by an exception (such as "unrecognized selector sent to instance 0xa26d9a0")
• Its pluggable server reporting architecture makes it easy to adapt to any API service.
• Dumps the stack contents.
• Diagnoses crash causes (Crash Doctor).
• Records lots of information beyond what the Apple crash report can, in a JSON format.
• Supports including extra data that the programmer supplies (before and during a crash).

KSCrash handles the following kinds of crashes:

• Mach kernel exceptions
• Fatal signals
• C++ exceptions
• Objective-C exceptions
• Main thread deadlock (experimental)
• Custom crashes (e.g. from scripting languages)

Here are some examples of the reports it can generate.

Call for help!

My life has changed enough over the past few years that I can't keep up with giving KSCrash the love it needs.

I'm looking for someone to help me maintain this package, make sure issues get handled, merges are properly vetted, and code quality remains high. Please contact me personally (kstenerud at my gmail address) or comment in https://github.com/kstenerud/KSCrash/issues/313

How to Install KSCrash

Swift Package Manager (SPM)

Option 1: Using Xcode UI

1. In Xcode, go to File > Add Packages...
2. Enter: https://github.com/kstenerud/KSCrash.git
3. Select the desired version/branch
4. Choose your target(s)
5. Click "Add Package"

Option 2: Using Package.swift

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/kstenerud/KSCrash.git", .upToNextMajor(from: "2.5.1"))
]

Then, include "Installations" as a dependency for your target:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "Installations", package: "KSCrash"),
        ]),
]

CocoaPods

1. Add to your Podfile:

   pod 'KSCrash', '~> 2.5'
   

2. Run:

   $ pod install
   

3. Use the generated .xcworkspace file.

Post-Installation Setup

Add the following to your AppDelegate.swift file:

Import KSCrash

For Swift Package Manager:

import KSCrashInstallations

For CocoaPods:

import KSCrash

Configure AppDelegate

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let installation = CrashInstallationStandard.shared
        installation.url = URL(string: "http://put.your.url.here")!

        // Install the crash reporting system
        let config = KSCrashConfiguration()
        config.monitors = [.machException, .signal]
        installation.install(with: config) // set `nil` for default config

        // Optional: Add an alert confirmation (recommended for email installation)
        installation.addConditionalAlert(
            withTitle: "Crash Detected",
            message: "The app crashed last time it was launched. Send a crash report?",
            yesAnswer: "Sure!",
            noAnswer: "No thanks"
        )

        return true
    }
}

Other Installation Types

Email Installation

let installation = CrashInstallationEmail.shared
installation.recipients = ["some@email.address"] // Specify recipients for email reports
// Optional: Send Apple-style reports instead of JSON
installation.setReportStyle(.apple, useDefaultFilenameFormat: true)

Console Installation

let installation = CrashInstallationConsole.shared
installation.printAppleFormat = true // Print crash reports in Apple format for testing

Sending Reports

To send any outstanding crash reports, call:

installation.sendAllReports { reports, completed, error in
    // Stuff to do when report sending is complete
}

Optional Monitors

KSCrash includes two optional monitor modules: BootTimeMonitor and DiscSpaceMonitor. These modules are not included by default and must be explicitly added if needed. They contain privacy-concerning APIs that require showing crash reports to the user before sending this information off the device.

To include these modules:

• With CocoaPods:

  pod 'KSCrash/BootTimeMonitor'
  pod 'KSCrash/DiscSpaceMonitor'
  

• With SPM, add to your target dependencies:

  .product(name: "BootTimeMonitor", package: "KSCrash"),
  .product(name: "DiscSpaceMonitor", package: "KSCrash"),
  

If these modules are linked, they act automatically and require no additional setup. It is the responsibility of the library user to implement the necessary UI for user consent.

For more information, see Apple's documentation on Disk space APIs and System boot time APIs.

Optional Demangling

KSCrash has an optional module that provides demangling for both C++ and Swift symbols: DemangleFilter. This module contains a KSCrash filter (CrashReportFilterDemangle) that can be used for demangling symbols in crash reports during the sendAllReports call (if this filter is added to the filters pipeline).

This module is used automatically if you use the Installations API. If you want to avoid demangling, you can set isDemangleEnabled in the CrashInstallation instance to false.

If you don't use the Installations API, you can include this module manually:

• With CocoaPods:

  pod 'KSCrash/DemangleFilter'
  

• With SPM, add to your target dependencies:

  .product(name: "DemangleFilter", package: "KSCrash"),
  

The CrashReportFilterDemangle class also has a static API that you can use yourself in case you need to demangle a C++ or Swift symbol.

Integrating KSCrash Into Your Library

If you want to leverage KSCrash as the crash detection layer in your own crash reporter library, you'll need to namespace it so that the symbols don't clash with other libraries that do the same.

KSCrash fully supports namespacing all of its public symbols, allowing it to coexist with other versions of itself.

There are various approaches you can take to integrate KSCrash into your product.

What's New?

Out-of-Memory Crash Detection

KSCrash now includes advanced memory tracking capabilities to help detect and prevent out-of-memory crashes. The new KSCrashAppMemoryTracker allows you to monitor your app's memory usage, pressure, and state transitions in real-time. This feature enables proactive memory management, helping you avoid system-initiated terminations due to excessive memory use. Check out the "Advanced Usage" section for more details on how to implement this in your app.

C++ Exception Handling

That's right! Normally if your app terminates due to an uncaught C++ exception, all you get is this:

Thread 0 name:  Dispatch queue: com.apple.main-thread
Thread 0 Crashed:
0   libsystem_kernel.dylib          0x9750ea6a 0x974fa000 + 84586 (__pthread_kill + 10)
1   libsystem_sim_c.dylib           0x04d56578 0x4d0f000 + 292216 (abort + 137)
2   libc++abi.dylib                 0x04ed6f78 0x4ed4000 + 12152 (abort_message + 102)
3   libc++abi.dylib                 0x04ed4a20 0x4ed4000 + 2592 (_ZL17default_terminatev + 29)
4   libobjc.A.dylib                 0x013110d0 0x130b000 + 24784 (_ZL15_objc_terminatev