-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
docs(flutter): Add ANR and App Hangs guidance #17881
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
buenaflor
wants to merge
8
commits into
master
Choose a base branch
from
buenaflor/docs-flutter-anr-app-hangs
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
5c59717
docs(flutter): Add ANR and App Hangs guidance
buenaflor 3101010
docs(flutter): Refine ANR symbolication guidance
buenaflor 3dbfade
docs(flutter): Capitalize App Hangs description
buenaflor 6f2b0d1
docs(flutter): Clarify ANR and App Hang event names
buenaflor 58c4379
docs(flutter): Clarify readable frame wording
buenaflor 3591333
Potential fix for pull request finding
buenaflor 84e3839
docs(flutter): Fix docs lint formatting
buenaflor dcd4d59
docs(flutter): Fix cross-platform ANR links
buenaflor File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
60 changes: 60 additions & 0 deletions
60
docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| --- | ||
| title: ANR and App Hangs | ||
| description: "Learn how Sentry detects and configures ANRs and App Hangs in Flutter apps." | ||
| sidebar_order: 45 | ||
| --- | ||
|
|
||
| Sentry can detect when your Flutter app's main thread is blocked for too long, causing the app to become unresponsive. The Flutter SDK relies on the underlying native Sentry SDKs to detect these events. | ||
|
|
||
| **This feature is available on Android, iOS, and macOS.** | ||
|
|
||
| ## What Gets Reported | ||
|
|
||
| On Android, these are reported as Application Not Responding (ANR) events. | ||
| On iOS and macOS, they're reported as App Hang events. | ||
| Depending on where the app was blocked, events can include stack frames from Dart, Java/Kotlin, Swift/Objective-C, or C/C++ code. | ||
|
|
||
| ## Configure Detection | ||
|
|
||
| ANR and App Hang detection are enabled by default. You can disable them or change their timeout thresholds in `SentryFlutter.init`: | ||
|
|
||
| ```dart | ||
| await SentryFlutter.init( | ||
| (options) { | ||
| // Android only: ANR | ||
| options.anrEnabled = true; // default: true | ||
| options.anrTimeoutInterval = const Duration(seconds: 5); // default: 5s | ||
|
|
||
| // iOS/macOS only: App Hang | ||
| options.enableAppHangTracking = true; // default: true | ||
| options.appHangTimeoutInterval = const Duration(seconds: 2); // default: 2s | ||
| }, | ||
| ); | ||
| ``` | ||
|
|
||
| For more configuration details, see the <Link to="/platforms/android/configuration/app-not-respond/">Android ANR documentation</Link> and the <Link to="/platforms/apple/configuration/app-hangs/">Apple App Hangs documentation</Link>. | ||
|
|
||
| ## Pause App Hang Tracking | ||
|
|
||
| On iOS and macOS, you can pause App Hang tracking at runtime. Use this when you can't avoid a known blocking operation, such as a synchronous database migration during startup, and don't want Sentry to report it as an app hang. | ||
|
|
||
| ```dart | ||
| SentryFlutter.pauseAppHangTracking(); | ||
|
|
||
| // Run code that you don't want Sentry to report as an app hang. | ||
|
|
||
| SentryFlutter.resumeAppHangTracking(); | ||
| ``` | ||
|
|
||
| ## Readable Stack Traces | ||
|
|
||
| Since ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and C/C++ code, Sentry needs the corresponding debug files to make each frame readable. | ||
|
|
||
| See the <PlatformLink to="/debug-symbols/dart-plugin/#anr-and-app-hang-symbolication">Sentry Dart Plugin documentation</PlatformLink> for the debug files required on Android, iOS, and macOS, including Android R8/ProGuard mapping files. | ||
|
|
||
| ## Platform Details | ||
|
|
||
| For more details about how each native SDK detects these events, see: | ||
|
|
||
| - [Android ANR documentation](/platforms/android/configuration/app-not-respond/) | ||
| - [Apple App Hangs documentation](/platforms/apple/configuration/app-hangs/) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
dunno if it makes sense to also expose anrProfiling options? but that's probably for a separate PR
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we dont expose it yet
I'll test it and see if it's useful for Flutter use cases