Skip to content

Commit 4ef2c0e

Browse files
markushiclaude
andauthored
docs(android): Document ANR profiling and fingerprinting (#16816)
## DESCRIBE YOUR PR Document two new Android SDK features available in version 8.35.0: - **ANR Profiling (Experimental)**: Captures main thread stack profiles during ANR detection, attached as flamegraphs on the issue details page. Configured via `anrProfilingSampleRate` (disabled by default). - **ANR Fingerprinting**: Groups system-frame-only ANRs into a single issue to reduce noise. Enabled by default, configurable via `enableAnrFingerprinting`. Changes across three files: - `docs/platforms/android/configuration/app-not-respond.mdx` — New sections with configuration examples (AndroidManifest.xml, Kotlin, Java) - `docs/platforms/android/configuration/options.mdx` — New `SdkOption` entries for both features - `docs/platforms/android/index.mdx` — Links to new features in Next Steps Related SDK PRs: - getsentry/sentry-java#4899 - getsentry/sentry-java#5168 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): - [ ] Other deadline: - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 98eb23a commit 4ef2c0e

File tree

4 files changed

+87
-1
lines changed

4 files changed

+87
-1
lines changed

docs/platforms/android/configuration/app-not-respond.mdx

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Application Not Responding (ANR)
33
sidebar_order: 4
4-
description: Learn how to turn off or specify ANR.
4+
description: Learn how to turn off or configure ANR detection, profiling, and fingerprinting.
55
og_image: /og-images/platforms-android-configuration-app-not-respond.png
66
---
77

@@ -105,6 +105,77 @@ SentryAndroid.init(context) { options ->
105105

106106
![ANR Thread Dump](./img/app-not-respond-thread-dump.png)
107107

108+
## ANR Profiling (Experimental)
109+
110+
<Alert>
111+
112+
ANR Profiling is available starting in SDK version `8.35.0`. This feature is experimental and may change in future versions.
113+
114+
</Alert>
115+
116+
<Alert>
117+
118+
ANR profiles are powered by the Profiling platform and require a plan with profiling enabled. See the [pricing page](https://sentry.io/pricing/) for more details.
119+
120+
</Alert>
121+
122+
The SDK can capture stack profiles for foreground ANRs of the main thread when an ANR is detected. A profile is a time-based view of your stack trace, showing which functions were executing and for how long. The captured profile is attached to the ANR event on the next app start, providing a flamegraph on the Sentry issue details page. This gives you deeper insight into what the main thread was doing at the time of the ANR.
123+
124+
```mermaid
125+
flowchart LR
126+
A[App start] --> B
127+
B[Main thread<br>blocked > 1s] --> C[Collect and store ANR profile to disk]
128+
E[Next app start] --> F[Read<br>ApplicationExitInfo] --> G[Match stored<br>ANR profile] --> H[Attach ANR profile<br>to ANR event]
129+
```
130+
131+
To enable ANR profiling, set the `anrProfilingSampleRate` to a value between `0.0` and `1.0`. This controls the probability of collecting a profile for each detected foreground ANR:
132+
133+
```xml {filename:AndroidManifest.xml}
134+
<application>
135+
<meta-data android:name="io.sentry.anr.profiling.sample-rate" android:value="1.0" />
136+
</application>
137+
```
138+
139+
```kotlin
140+
SentryAndroid.init(context) { options ->
141+
options.anrProfilingSampleRate = 1.0
142+
}
143+
```
144+
145+
```java
146+
SentryAndroid.init(context, options -> {
147+
options.setAnrProfilingSampleRate(1.0);
148+
});
149+
```
150+
151+
Once enabled, ANR events will include a profile section on the issue details page, showing a flamegraph of the main thread activity at the time of the ANR:
152+
153+
![ANR Profile](./img/anr-profile.png)
154+
155+
## ANR Fingerprinting
156+
157+
The SDK assigns a static fingerprint to ANR events whose stack traces contain only system frames (for example, classes from `java.lang` or `android.os`). This groups noisy system-frame-only ANRs into a single issue, reducing noise in your issue stream. Foreground and background system-frame-only ANRs are grouped separately.
158+
159+
ANR fingerprinting is enabled by default starting in SDK version `8.35.0`. To disable it:
160+
161+
```xml {filename:AndroidManifest.xml}
162+
<application>
163+
<meta-data android:name="io.sentry.anr.enable-fingerprinting" android:value="false" />
164+
</application>
165+
```
166+
167+
```kotlin
168+
SentryAndroid.init(context) { options ->
169+
options.isEnableAnrFingerprinting = false
170+
}
171+
```
172+
173+
```java
174+
SentryAndroid.init(context, options -> {
175+
options.setEnableAnrFingerprinting(false);
176+
});
177+
```
178+
108179
## ANR Root Cause Analysis
109180

110181
Sentry performs various root cause analyses to give you insights about why certain ANRs might appear. If a potential root cause is detected, it'll be displayed in a new section below the ANR stack trace. Sentry can detect the following root causes:
247 KB
Loading

docs/platforms/android/configuration/options.mdx

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,20 @@ A boolean value that determines whether the app start process will be profiled.
375375

376376
</SdkOption>
377377

378+
## ANR Options
379+
380+
<SdkOption name="anrProfilingSampleRate" type="float" defaultValue="null" availableSince="8.35.0">
381+
382+
A number between `0` and `1`, controlling the percentage chance a profile will be collected for each detected foreground ANR. (`0` represents 0% while `1` represents 100%.) The default is null (disabled). When set, the SDK captures a stack profile of the main thread at the time of ANR detection and attaches it to the ANR event on the next app start.
383+
384+
</SdkOption>
385+
386+
<SdkOption name="enableAnrFingerprinting" type="bool" defaultValue="true" availableSince="8.35.0">
387+
388+
When enabled, the SDK assigns a static fingerprint to ANR events whose stack traces contain only system frames. This groups noisy system-frame-only ANRs into a single issue, reducing noise. Foreground and background system-frame-only ANRs are grouped separately.
389+
390+
</SdkOption>
391+
378392
## Transaction-Based Profiling Options
379393

380394
This mode will eventually be deprecated, and it's recommended to upgrade to <PlatformLink to="/configuration/options/#ui-profiling-options">UI Profiling</PlatformLink>. The same behaviour, without the 30 seconds limitation, can be achieved with the `trace` <PlatformLink to="/configuration/options/#profile-lifecycle">profile lifecycle</PlatformLink> option. In order to upgrade to UI Profiling, you also need to remove the transaction-based options from your configuration.

docs/platforms/android/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,3 +188,4 @@ class MyActivity : AppCompatActivity() {
188188
- <PlatformLink to="/features">Learn about the features of Sentry's Android SDK</PlatformLink>
189189
- <PlatformLink to="/enhance-errors">Learn how to enhance stack traces of your Sentry errors</PlatformLink>
190190
- <PlatformLink to="/enriching-events">Enrich events with additional context to make debugging simpler</PlatformLink>
191+
- <PlatformLink to="/configuration/app-not-respond">Diagnose ANRs</PlatformLink> with profiling and automatic fingerprinting

0 commit comments

Comments
 (0)