Get Better Visibility Into App Hangs On Apple Devices
App hangs are the worst kind of bug: they don’t crash, they don’t log, and unless you're actively profiling, good luck catching them in the debugger.
Maybe the main thread is blocked because it’s decoding a massive image with UIImage(data:). Maybe a background task is holding a lock or waiting on a DispatchGroup that never finishes. Maybe an async flow is stuck waiting on a continuation that never resumes. Either way, the app looks broken, the user gets frustrated, and you’re left staring at Instruments wondering what actually happened.
We can’t stop your app from hanging—that part’s still on you—but we can help you catch it before your users rage-quit, uninstall, and leave a one-star review about how your app “doesn’t even open.”
Starting with version 8.50.0 of the Sentry Cocoa SDK, we’re rolling out improved app hang detection for iOS, macOS, and other Apple platforms. This update gives you better visibility into how, when, and why your app hangs—so you can fix them faster.
The Sentry Cocoa SDK has supported app hang detection since 2022—but up until now, it’s been limited to non-fatal hangs and didn’t offer much context beyond “something blocked the main thread for over 2 seconds”. Helpful, but not easy to understand the impact.
We’ve overhauled app hang tracking to give your team deeper visibility into the kinds of hangs that actually impact users—and the context you need to prioritize and fix them. Here’s what’s unlocked in this update:
Fatal app hangs & hang classification: We now detect hangs that lead to your app being terminated, either by the user or the OS watchdog. Plus, you can see whether a hang was fully blocking the main thread or only partially impacting UI responsiveness. With these updates, the Cocoa SDK now captures 4 types of app hangs:
Non-Fully Blocking: Instances when the UI thread isn’t fully blocked and can render a few frames.
Fully Blocking: When the UI thread is fully blocked.
Fatal Non-Fully Blocking: A non-fully blocking app hang that leads to a manual termination by the user or a force kill by the operating system.
Fatal Fully Blocking: The worst case. A fully blocking app hang that leads to a manual termination by the user or a force kill by the operating system.
Hang duration: Get precise timing data for non-fatal hangs so you can understand how long users are stuck.
App hang rate: Monitor how frequently hangs are occurring across your Apple projects.
To use the new functionality, make sure you’re on Sentry Cocoa SDK 8.50.0+ and have set the option enableAppHangTrackingV2 = true.
You shouldn’t have to play a guessing game or do back-of-the-napkin math to understand how many of your users are being affected by fatal app hangs (in other words, the worst case scenario). If fatal app hangs spiked at the same time as your latest release, you need the visibility to be able to make that connection. To make it easier to keep on top of app hangs, The project details page can now display the app hang rate for every project, which is the percentage of unique users who experienced a fatal app hang.
Users often won’t notice the difference between fully blocking (when the UI thread is stuck and can’t render a single UI frame) and non-fully blocking app hangs (when the UI thread can render a few frames).
But it’s an important distinction for many development teams, because fully blocking app hangs are more likely to have an actionable stack trace pointing to the root cause, since the code responsible for the app hangs usually blocks the UI thread when Sentry detects it. Non-fully blocking app hangs are less likely to have actionable stack traces because the app is performing multiple distinct chunks of heavy computation, making it harder to tell which chunk is responsible for the hang.
If you don’t want to distinguish between fully blocking and non-fully blocking app hangs, you can simply set the option enableReportNonFullyBlockingAppHangs = false. If you set this option to false, you’ll still get fatal fully blocking app hangs and fully blocking app hangs, but not fatal non-fully blocking and non-fully blocking.
In the past, our Cocoa SDK stated that an app hung for at least 2 seconds, but it did not specify how long - it could be anything between 2 and 20 seconds. Now the Cocoa SDK reports the approximate length of app hangs for non-fatal app hangs, providing important context for triaging and debugging.
With these new improvements, version 8.50.0 of the Cocoa SDK now detects fatal app hangs and introduces app hang rate to track the percentage of users affected when enabling the option enableAppHangTrackingV2 = true . It also differentiates between fully blocking and non fully blocking app hangs, improving stack trace accuracy. Additionally, it also measures the duration for non-fatal app hangs.
To get started with tracking app hangs and errors of all kinds on your iOS devices, check out our docs or GitHub.
