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`:
 [code] 
**CocoaPods:**
 [code] 
### Setup
 [code] 
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
| Deprecated | Replacement |
| ----------------------------------------------- | ---------------------------------------------------- |
| `userInfo` property | Per-key API in `KSCrash+UserInfo.h` |
| `deadlockWatchdogInterval` | `KSCrashMonitorTypeWatchdog` |
| `enableSigTermMonitoring` | Removed (always caught) |
| `KSCrashMonitorTypeMainThreadDeadlock` | `KSCrashMonitorTypeWatchdog` |
| `KSCrashMonitorType