docs(flutter): document ANR / App Hang behaviour and symbolication

[buenaflor]

Problem

sentry_flutter reports Application Not Responding (ANR) on Android and App Hangs on iOS, but the two behave quite differently. Users today have no documentation explaining what to expect, why their Android ANRs look (potentially) worse than their iOS App Hangs, or what to do about it.

What users need to know

iOS App Hangs

• Detected and reported while the app is hanging.
• Dart source lines (main.dart:350) appear in the stack trace with standard dSYM upload.
• No extra build flags required.
• Users must either use sentry_dart_plugin or sentry-cli directly to upload the dSYM

Example of symbolicated Dart stacktrace in iOS App Hang pointing to the relevant LoC in Dart:

Android ANRs

• On modern Android (API ≥ 30), the event is reported on the next app launch, not during the hang. The stack comes from the native thread dump the system captured during the ANR, so it includes Dart frames (as raw addresses) plus Flutter engine and system frames.
• On older Android (API < 30), events are reported live. The stack is a JVM-level capture of the main thread (Java/Kotlin frames only); Dart frames typically don't appear.
• By default, Dart stack frames appear as raw addresses (libapp 0x2d3fe4 null) instead of source lines. To get source-level symbolication, users must either use sentry_dart_plugin (recommended) or build with --split-debug-info and upload the symbols manually.
• ANR events may not appear at all on emulators or some OEM devices (Samsung, etc.) because the OS doesn't always classify the hang as a true ANR.

Example of unsymbolicated Dart stacktrace in Android ANR:

Why iOS works out of the box and Android doesn't

Apple's toolchain always emits a standard dSYM (DWARF debug info) next to the Flutter AOT binary. Sentry's symbolicator speaks DWARF, so uploading the dSYM is enough.

flutter build apk --release emits no DWARF into libapp.so by default. The debug info Dart uses at runtime lives in a Dart-VM-private format that Sentry can't read — there's nothing equivalent to a dSYM to upload unless the user explicitly opts in via --split-debug-info or --dwarf-stack-traces.

What the docs should add

1. A short, user-facing explanation of the iOS/Android differences (live vs. post-mortem, different capture mechanisms).
2. A clear Android setup step for symbolication — point to sentry_dart_plugin as the default path (iOS should also point to uploading dsyms as setup step).

Follow-up

Improving the Android experience so it matches iOS out of the box is a separate SDK-level effort and not part of this docs task.

[linear-code]

DART-357