$ show kstenerud/KSCrash
KSCrash is a production-grade crash reporting and system monitoring library for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). It captures Mach exceptions, Unix signals, C++ and Objective-C exceptions, main thread hangs, watchdog timeouts, and OS-level terminations (OOM, thermal, CPU, reboot). The library generates Apple-format crash reports with full backtraces, binary images, system state, and user-provided context. It also includes performance monitors for CPU usage, memory pressure, and boot time, as well as a sampling profiler. The architecture is modular: a low-level C core provides async-signal-safe stack unwinding (compact unwind, DWARF CFI, frame pointer), safe memory access, JSON encoding/decoding, and a key-value store. Higher-level Objective-C and Swift modules implement individual crash monitors (Mach, signal, NSException, C++ exception, zombie, watchdog, termination, lifecycle, resource, user info) that register via a plugin API. Reports are stored on disk with mmap'd sidecar files for cross-launch state, then processed through a filter pipeline (demangling, compression, JSON formatting, diagnostic analysis) and delivered via configurable sinks (HTTP, email, console). The library is distributed as Swift packages and CocoaPods pods, with extensive CI covering unit tests, integration tests, benchmarks, static analysis, and API stability checks. Key strengths include rigorous async-signal-safety in crash-time code, a lock-free binary image cache for fast symbolication, a streaming JSON codec with pluggable callbacks, and a sidecar system that persists monitor data across app launches. The codebase demonstrates high craftsmanship in low-level systems programming, concurrency, and Apple platform internals. While primarily a crash reporter, its monitoring and profiling capabilities make it a comprehensive observability tool for Apple applications.
The LLM identified 6 files worth highlighting for reuse:
A streaming JSON encoder/decoder implemented in pure C with pluggable data handlers via callbacks. Designed for async-signal-safe operation (no heap allocation, no locks). Supports incremental parsing and encoding, making it reusable for any embedded or crash-time JSON processing. Demonstrates non-obvious skill in memory-safe, allocation-free serialization.
An mmap-backed, append-only key-value store with typed setters (string, int, double, bool, date) and iteration via callbacks. Supports compaction (O(nĀ²) but acceptable for small stores). Ideal for persisting small amounts of crash-time or configuration data across launches. Reusable in any project needing a simple, durable KV store without database dependencies.
A fixed-size ring buffer for CPU usage samples with sliding window averaging. Provides O(1) insertion and O(n) window computation. Used by KSCrashCPUTracker to classify CPU state (normal/warning/critical) over configurable time windows. The pattern is reusable for any sliding-window metric aggregation (memory, network, etc.) in performance monitoring.
Defines the KSCrashMonitorAPI struct, a plugin interface for crash monitors. Each monitor provides init, setEnabled, isEnabled, addContextualInfoToEvent, and createStitchedReport callbacks. Monitors are registered via a lock-free registry. This pattern enables clean separation of concerns and easy addition of new monitors (e.g., MetricKit, resource, boot time). Reusable for any system needing pluggable event observers with lifecycle management.
A lock-free cache for binary image (dyld) information, using atomic exchange and a sorted array for binary search. Designed for async-signal-safe symbolication during crash handling. Caches unwind info and addresses for fast lookup. The lock-free update pattern (publish via release/acquire on per-slot fields) is reusable for any read-mostly, crash-safe cache.
A custom spinlock implementation using atomic test-and-set with CPU pause instructions (PAUSE on x86, YIELD on ARM). Designed for async-signal-safe contexts where os_unfair_lock may not be available. Includes a try-lock variant. Reusable as a lightweight, portable spinlock for low-contention, signal-safe synchronization.