chimehq / impact

Crash capturing library for Apple platforms

Impact

Impact is a crash detection and recording library for Apple platforms. It is not a full crash reporting system. But, it could be the core of one. Its design goals are:

• Improve understanding of crash reporting systems
• Support for all Apple platforms
• Reliablity
• Accuracy
• Simplicity
• Fun

Current feature set:

• Mach Exceptions
• UNIX signals
• NSExceptions (including from within AppKit)
• Frame pointer-based stack unwinding
• Partial compact unwind support for x86_64 and arm64
• Partial DWARF CFI support for x86_64 and arm64

Impact uses a text-based log format. While the format itself is stable, the contents are still unstable. It is designed to be simple, while still making both debugging and parsing possible in the face of crash-time failure.

Isn't Crash Reporting a Solved Problem?

In-process crash reporting is just terrible. The mechanisms available for crash event detection, UNIX signals and Mach exceptions, are complex, buggy, and are not capable of capturing all kinds of failures. On top of that, the enviroment in which a crash reporter needs to run is extraordinarily hostile. It's just messy business.

Apple has had all of the device-side pieces in place to produce a world-class crash reporting system for a long time. While they have the reporting side down, the developer experience (analysis, presentation, investigative tools) leaves a lot to be desired. This has kept 3rd-party reporting services essential for the vast majority of app developers. Apple's system also doesn't work for macOS apps outside the App Store, which is disappointing.

My sincere hope is that Apple addresses these limitations so we can all stop this foolishness once and for all.

But, for now, in-process reporting is a necessary component for most developers. There are many trade-offs and design decisions that dramatically affect the qualities of a reporting system. Understanding those trade-offs, and being explicit about choices that affect them is one of the goals of this project.

Also, crash reporting is just a fun and fascinating problem. It tends to be very commonly used and very poorly understood. I think the Apple development community could benefit a lot from a more in-depth understanding of the area.

Can I Use Impact in my App?

You must keep in mind that Impact only captures information about crash events. It does not have any facilities for transmitting those events back to you or translating them into human-readable versions. A full reporting system requires a little more work. Here are a few options:

• Impact on its own, with full control over how you produce and consume reports
• Integrate with Wells for report transmission and management
• MetricKit crash reporting with graceful fallback via Meter and ImpactMeterAdapter

Relationship to Crashlytics

I worked at Crashlytics for many years. During my time there, I briefly worked with PLCrashReporter before starting from scratch and building a completely custom system. I spent a considerable amount of time there analyzing and understanding the failure modes of in-process crash reporting. That work shaped most of the design of the Crashlytics SDK, though things might have changed since I left.

Impact does share many of those design philosophies. It's hard to unsee solutions, sometimes. But, it's primarily because I believe those core design concepts are the best approach.

Contributing

It would be wonderful to see contributions. If you'd like to work on something, the safest bet is to open an issue or PR first. That way, we can discuss the changes before you spend too much time working.

There is absolutely no experience/knowledge requirement. Interest is all you need, I am happy to help.

Suggestions or Feedback

We'd love to hear from you! Get in touch via an issue or pull request.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

impact's Issues

xcconfig not found

Trying to build it, but "xcconfigs/UniversalFramework_Framework.xcconfig" doesn't seem to be checked into the source tree.

Can I use Impact within a binary framework?

Want to enable crash capture system in our framework which will then report these crashes to our backend.

We just want to be able to capture the crash and check if this crash is originating from our framework. Is that possible?

Our framework will then be used within multiple apps which might have third party crash reporting engines integrated.
Will this work along with other crash reporting engines ?

KSCrash

Thanks for this interesting new project in a space that's often overlooked.

Being a satisfied user with KSCrash, which has served me well for many years – and it being used as the backend for at least one commercial crash reporting tool (Sentry) – I wonder how Impact relates to this.

I.e., did you have a look at KSCrash and considered using it as a starting point? 

Any simple tasks?

Hi!
I would like to contribute. :)
Do you have any novice friendly tasks?