kstenerud/KSCrash

[!NOTE] Branch layout (August 2026)

• master: latest stable release, currently 2.6.0
• develop: next-release work, target this for new PRs

KSCrash 2.6

The best open-source crash reporting framework for Apple platforms. Supports iOS, macOS, tvOS, watchOS, and visionOS.

KSCrash catches Mach exceptions, signals, C++/ObjC exceptions, main thread hangs, and OS-level terminations (OOM, thermal, CPU, reboot). It generates full Apple-format crash reports with every field filled in.

If you are upgrading from 2.5.x, see the migration guide. For upgrades from 1.x, see the 1.x to 2.0 migration guide.

Quick Start

Install

SPM: Add https://github.com/kstenerud/KSCrash.git in Xcode (File > Add Packages), or in Package.swift:

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

CocoaPods:

pod 'KSCrash', '~> 2.6'

Setup

import KSCrashRecording // KSCrash for CocoaPods

let config = KSCrashConfiguration()
try KSCrash.shared.install(with: config)

That's it. KSCrash will catch crashes and store reports on disk. To send reports to a server, use an installation. See KSCrashInstallation.h for details.

Features

See the Architecture and Code Tour wiki pages for how these work under the hood.

Hang Detection

The Watchdog monitor detects main thread hangs (250ms+) and captures full backtraces. Enable with .watchdog in your monitor config. See KSCrash+Hang.h for real-time hang observation.

Termination Detection

Detects OS-level terminations (OOM, thermal, CPU, reboot) by comparing previous-run state at launch. Query the result with KSCrash.shared.previousTerminationReason.

CPU Monitoring

Tracks CPU usage with sliding-window averages mirroring Apple's enforcement thresholds. Optionally generates non-fatal reports on warning/critical transitions via enableCPUExceptionReporting.

Custom User Data

Store per-key data that persists across crashes via KSCrash+UserInfo.h. Uses an mmap'd key-value store with zero crash-time overhead.

Additional Features

• Profiler: Sampling profiler for thread backtraces (KSCrashProfiler module)
• MetricKit: Apple diagnostic payload integration (KSCrashMonitors module)
• Report: Strongly-typed Swift model for crash reports (KSCrashReportModel module)
• Zombie Detection: Catches messages to deallocated objects
• Memory Tracking: Real-time memory pressure monitoring via AppMemoryTracker
• Crash Doctor: Automatic crash cause diagnosis
• Custom Crashes: Report exceptions from scripting languages via reportUserException
• Namespacing: Embed KSCrash in your own library without symbol clashes

For configuration options, see KSCrashConfiguration.h. For the full API, see KSCrash.h.

Deprecations in 2.6

See the migration guide for details and rationale.

License

MIT License. See LICENSE for details.

Notes

This project is tested with BrowserStack.