ref(anr): Add Android-specific ANR detection options (#749)

Author: limbonaut

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Breaking changes
+
+- Add Android-specific ANR (Application Not Responding) detection options ([#749](https://github.com/getsentry/sentry-godot/pull/749))
+  - ANR detection is now enabled by default; set `SentryOptions.android.enable_anr_detection` to `false` to opt out
+  - ANR detection is now separate from the App Hang Tracking options (`app_hang_tracking`, `app_hang_timeout_sec`), which now apply to Apple platforms only
+  - Configure these through `SentryOptions.android`, or in the **Project Settings** under **Sentry > Android > Application Not Responding**
+
 ### Dependencies
 
 - Bump Sentry JavaScript from v10.55.0 to v10.57.0 ([#743](https://github.com/getsentry/sentry-godot/pull/743), [#754](https://github.com/getsentry/sentry-godot/pull/754))

android_lib/src/main/java/io/sentry/godotplugin/SentryAndroidGodotPlugin.kt

@@ -182,9 +182,10 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
             val maxBreadcrumbs = optionsData["max_breadcrumbs"].toIntOrThrow()
             val enableLogs = optionsData["enable_logs"] as Boolean
             val enableMetrics = optionsData["enable_metrics"] as Boolean
-            val appHangTracking = optionsData["app_hang_tracking"] as Boolean
-            val appHangTimeoutSec = optionsData["app_hang_timeout_sec"] as Double
-            val shutdownTimeoutMs = optionsData["shutdown_timeout_ms"].toIntOrThrow()
+            val enableAnrDetection = optionsData["enable_anr_detection"] as Boolean
+            val anrTimeoutIntervalMs = optionsData["anr_timeout_interval_ms"].toLongOrThrow()
+            val attachAnrThreadDump = optionsData["attach_anr_thread_dump"] as Boolean
+            val shutdownTimeoutMs = optionsData["shutdown_timeout_ms"].toLongOrThrow()
 
             SentryAndroid.init(godot.getActivity()!!.applicationContext) { options ->
                 options.dsn = dsn.ifEmpty { null }
@@ -198,9 +199,10 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
                 options.nativeSdkName = "sentry.native.android.godot"
                 options.logs.isEnabled = enableLogs
                 options.metrics.isEnabled = enableMetrics
-                options.isAnrEnabled = appHangTracking
-                options.anrTimeoutIntervalMillis = (appHangTimeoutSec * 1000.0).toLong()
-                options.shutdownTimeoutMillis = shutdownTimeoutMs.toLong()
+                options.isAnrEnabled = enableAnrDetection
+                options.anrTimeoutIntervalMillis = anrTimeoutIntervalMs
+                options.isAttachAnrThreadDump = attachAnrThreadDump
+                options.shutdownTimeoutMillis = shutdownTimeoutMs
                 options.isTombstoneEnabled = true
                 options.beforeSend =
                     SentryOptions.BeforeSendCallback { event: SentryEvent, hint: Hint ->

android_lib/src/main/java/io/sentry/godotplugin/UtilityFunctions.kt

@@ -62,6 +62,13 @@ fun Any?.toIntOrThrow(): Int =
         else -> throw IllegalArgumentException("Expected Int or Long, got ${this?.let { it::class } ?: "null"}")
     }
 
+fun Any?.toLongOrThrow(): Long =
+    when (this) {
+        is Int -> this.toLong()
+        is Long -> this
+        else -> throw IllegalArgumentException("Expected Int or Long, got ${this?.let { it::class } ?: "null"}")
+    }
+
 fun Any?.toLongOrNull(): Long? =
     when (this) {
         is Long -> this

doc_classes/SentryAndroidOptions.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryAndroidOptions" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd">
+	<brief_description>
+		Android-specific options for Sentry SDK.
+	</brief_description>
+	<description>
+		Contains configuration options that apply only when the project runs on Android, such as ANR (Application Not Responding) detection. Access this configuration through [member SentryOptions.android].
+		See also [SentryOptions].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="anr_timeout_interval_ms" type="int" setter="set_anr_timeout_interval_ms" getter="get_anr_timeout_interval_ms" default="5000">
+			Specifies how long, in milliseconds, the main thread must stay blocked before the SDK reports an ANR.
+			Applies only when [member enable_anr_detection] is enabled, and only to the V1 implementation used on Android versions before 11. On Android 11 and later, the operating system determines when the application stops responding, so this value has no effect.
+		</member>
+		<member name="attach_anr_thread_dump" type="bool" setter="set_attach_anr_thread_dump" getter="get_attach_anr_thread_dump" default="false">
+			If [code]true[/code], attaches the operating system's thread dump to the ANR event as a plain-text attachment, adding detail for investigating where the application became unresponsive.
+			Applies only when [member enable_anr_detection] is enabled, and only to the V2 implementation used on Android 11 and later.
+		</member>
+		<member name="enable_anr_detection" type="bool" setter="set_enable_anr_detection" getter="get_enable_anr_detection" default="true">
+			If [code]true[/code], detects and reports ANR (Application Not Responding) errors. The SDK monitors the main thread for unresponsiveness and reports an event when an ANR occurs.
+			Android 11 and later use the system-based V2 implementation, while earlier versions use the watchdog-based V1 implementation. See [member anr_timeout_interval_ms] and [member attach_anr_thread_dump] for options specific to each implementation. On Apple platforms, [member SentryOptions.app_hang_tracking] configures the equivalent app hang detection.
+			To learn more, visit [url=https://docs.sentry.io/platforms/android/configuration/app-not-respond/]Application Not Responding documentation[/url].
+		</member>
+	</members>
+</class>

doc_classes/SentryOptions.xml

@@ -13,12 +13,15 @@
 	<tutorials>
 	</tutorials>
 	<members>
+		<member name="android" type="SentryAndroidOptions" setter="" getter="get_android">
+			Configures Android-specific options, such as ANR (Application Not Responding) detection.
+		</member>
 		<member name="app_hang_timeout_sec" type="float" setter="set_app_hang_timeout_sec" getter="get_app_hang_timeout_sec" default="5.0">
 			Specifies the timeout duration in seconds after which the application is considered to have hanged. When [member app_hang_tracking] is enabled, if the main thread is blocked for longer than this duration, it will be reported as an application hang event to Sentry.
 		</member>
 		<member name="app_hang_tracking" type="bool" setter="set_app_hang_tracking" getter="is_app_hang_tracking_enabled" default="false">
 			If [code]true[/code], enables automatic detection and reporting of application hangs. The SDK will monitor the main thread and report hang events when it becomes unresponsive for longer than the duration specified in [member app_hang_timeout_sec]. This helps identify performance issues where the application becomes frozen or unresponsive.
-			[b]Note:[/b] This feature is only supported on Android, iOS, and macOS platforms.
+			[b]Note:[/b] This feature applies to iOS and macOS only. On Android, [member android] configures ANR (Application Not Responding) detection instead.
 		</member>
 		<member name="attach_log" type="bool" setter="set_attach_log" getter="is_attach_log_enabled" default="true">
 			If [code]true[/code], the SDK will attach the Godot log file to the event.

src/register_types.cpp

@@ -72,6 +72,7 @@ using namespace sentry;
 void register_runtime_classes() {
 	GDREGISTER_CLASS(SentryLoggerLimits);
 	GDREGISTER_CLASS(SentryExperimental);
+	GDREGISTER_CLASS(SentryAndroidOptions);
 	GDREGISTER_CLASS(SentryOptions);
 	GDREGISTER_INTERNAL_CLASS(RuntimeConfig);
 	GDREGISTER_CLASS(SentryUser);

src/sentry/android/android_sdk.cpp

@@ -350,8 +350,9 @@ void AndroidSDK::init() {
 	optionsData["max_breadcrumbs"] = SENTRY_OPTIONS()->get_max_breadcrumbs();
 	optionsData["enable_logs"] = SENTRY_OPTIONS()->get_enable_logs();
 	optionsData["enable_metrics"] = SENTRY_OPTIONS()->get_experimental()->get_enable_metrics();
-	optionsData["app_hang_tracking"] = SENTRY_OPTIONS()->is_app_hang_tracking_enabled();
-	optionsData["app_hang_timeout_sec"] = SENTRY_OPTIONS()->get_app_hang_timeout_sec();
+	optionsData["enable_anr_detection"] = SENTRY_OPTIONS()->get_android()->get_enable_anr_detection();
+	optionsData["anr_timeout_interval_ms"] = SENTRY_OPTIONS()->get_android()->get_anr_timeout_interval_ms();
+	optionsData["attach_anr_thread_dump"] = SENTRY_OPTIONS()->get_android()->get_attach_anr_thread_dump();
 	optionsData["shutdown_timeout_ms"] = SENTRY_OPTIONS()->get_shutdown_timeout_ms();
 
 	android_plugin->call(ANDROID_SN(init),

src/sentry/dotnet/csharp_interop.cpp

@@ -145,6 +145,11 @@ struct NativeOptions {
 
 	// Experimental
 	uint8_t enable_metrics;
+
+	// Android
+	uint8_t android_enable_anr_detection;
+	int32_t android_anr_timeout_interval_ms;
+	uint8_t android_attach_anr_thread_dump;
 };
 
 // Generic array handle for returning native-allocated arrays across the interop boundary.
@@ -200,6 +205,10 @@ struct ManagedOptions {
 	int32_t logger_log_mask;
 
 	uint8_t enable_metrics;
+
+	uint8_t android_enable_anr_detection;
+	int32_t android_anr_timeout_interval_ms;
+	uint8_t android_attach_anr_thread_dump;
 };
 
 struct NativeTraceContext {
@@ -242,6 +251,9 @@ static void _apply_managed_options(const ManagedOptions &data, Ref<SentryOptions
 	options->set_logger_breadcrumb_mask(data.logger_breadcrumb_mask);
 	options->set_logger_log_mask(data.logger_log_mask);
 	options->get_experimental()->set_enable_metrics(data.enable_metrics);
+	options->get_android()->set_enable_anr_detection(data.android_enable_anr_detection);
+	options->get_android()->set_anr_timeout_interval_ms(data.android_anr_timeout_interval_ms);
+	options->get_android()->set_attach_anr_thread_dump(data.android_attach_anr_thread_dump);
 }
 
 void _populate_options_data(NativeOptions &r_data, const Ref<SentryOptions> &options) {
@@ -276,6 +288,9 @@ void _populate_options_data(NativeOptions &r_data, const Ref<SentryOptions> &opt
 	r_data.logger_breadcrumb_mask = options->get_logger_breadcrumb_mask();
 	r_data.logger_log_mask = options->get_logger_log_mask();
 	r_data.enable_metrics = options->get_experimental()->get_enable_metrics();
+	r_data.android_enable_anr_detection = options->get_android()->get_enable_anr_detection();
+	r_data.android_anr_timeout_interval_ms = options->get_android()->get_anr_timeout_interval_ms();
+	r_data.android_attach_anr_thread_dump = options->get_android()->get_attach_anr_thread_dump();
 }
 
 // *** Functions called from C#

src/sentry/dotnet/managed/Sentry.Godot/Interop/NativeBridge.cs

@@ -114,6 +114,9 @@ private struct NativeOptions
         public int logger_breadcrumb_mask;
         public int logger_log_mask;
         public byte enable_metrics;
+        public byte android_enable_anr_detection;
+        public int android_anr_timeout_interval_ms;
+        public byte android_attach_anr_thread_dump;
     }
 
     // Must match layout of ManagedOptions in csharp_interop.cpp.
@@ -149,6 +152,9 @@ private unsafe struct ManagedOptions
         public int logger_breadcrumb_mask;
         public int logger_log_mask;
         public byte enable_metrics;
+        public byte android_enable_anr_detection;
+        public int android_anr_timeout_interval_ms;
+        public byte android_attach_anr_thread_dump;
     }
 
     [StructLayout(LayoutKind.Sequential)]
@@ -477,6 +483,9 @@ private static void ApplyNativeOptions(NativeOptions data, SentryGodotOptions op
         opts.LoggerBreadcrumbMask = (SentryGodotOptions.GodotLoggerEventMask)data.logger_breadcrumb_mask;
         opts.LoggerLogMask = (SentryGodotOptions.GodotLoggerEventMask)data.logger_log_mask;
         opts.EnableMetrics = data.enable_metrics != 0;
+        opts.Android.EnableAnrDetection = data.android_enable_anr_detection != 0;
+        opts.Android.AnrTimeoutInterval = TimeSpan.FromMilliseconds(data.android_anr_timeout_interval_ms);
+        opts.Android.AttachAnrThreadDump = data.android_attach_anr_thread_dump != 0;
     }
 
     public static void ApplyNativeOptions(SentryGodotOptions opts)
@@ -765,6 +774,9 @@ public static unsafe void InitNativeSdk(SentryGodotOptions opts)
                 logger_breadcrumb_mask = (int)opts.LoggerBreadcrumbMask,
                 logger_log_mask = (int)opts.LoggerLogMask,
                 enable_metrics = (byte)(opts.EnableMetrics ? 1 : 0),
+                android_enable_anr_detection = (byte)(opts.Android.EnableAnrDetection ? 1 : 0),
+                android_anr_timeout_interval_ms = (int)opts.Android.AnrTimeoutInterval.TotalMilliseconds,
+                android_attach_anr_thread_dump = (byte)(opts.Android.AttachAnrThreadDump ? 1 : 0),
             };
             csharp_interop_sdk_init(managed);
         }

src/sentry/dotnet/managed/Sentry.Godot/SentryGodotOptions.cs

@@ -50,7 +50,8 @@ public SentryGodotOptions()
     /// when it becomes unresponsive for longer than <see cref="AppHangTimeout"/>.
     /// </summary>
     /// <remarks>
-    /// Only supported on Android, iOS, and macOS.
+    /// This feature applies to iOS and macOS only. On Android, <see cref="Android"/> configures
+    /// ANR (Application Not Responding) detection instead.
     /// </remarks>
     public bool AppHangTracking { get; set; } = false;
 
@@ -137,6 +138,11 @@ public enum GodotLoggerEventMask
     /// </remarks>
     public SentryLoggerLimits LoggerLimits { get; set; } = new SentryLoggerLimits();
 
+    /// <summary>
+    /// Configures Android-specific options, such as ANR (Application Not Responding) detection.
+    /// </summary>
+    public SentryAndroidOptions Android { get; set; } = new SentryAndroidOptions();
+
     private readonly List<SentryAttachment> _defaultAttachments = [];
 
     internal IReadOnlyList<SentryAttachment> DefaultAttachments => _defaultAttachments;
@@ -229,3 +235,44 @@ public sealed class SentryLoggerLimits
     /// </summary>
     public TimeSpan ThrottleWindow { get; set; } = TimeSpan.FromMilliseconds(10000);
 }
+
+/// <summary>
+/// Contains configuration options that apply only when the project runs on Android, such as ANR (Application Not
+/// Responding) detection. Access this configuration through <see cref="SentryGodotOptions.Android"/>.
+/// </summary>
+/// <seealso cref="SentryGodotOptions"/>
+public sealed class SentryAndroidOptions
+{
+    /// <summary>
+    /// Enables detection and reporting of ANR (Application Not Responding) errors. The SDK monitors the main thread
+    /// for unresponsiveness and reports an event when an ANR occurs.
+    /// </summary>
+    /// <remarks>
+    /// Android 11 and later use the system-based V2 implementation, while earlier versions use the watchdog-based V1
+    /// implementation. See <see cref="AnrTimeoutInterval"/> and <see cref="AttachAnrThreadDump"/> for options specific
+    /// to each implementation. On Apple platforms, <see cref="SentryGodotOptions.AppHangTracking"/> configures the
+    /// equivalent app hang detection.
+    /// To learn more, visit <see href="https://docs.sentry.io/platforms/android/configuration/app-not-respond/">Application Not Responding documentation</see>.
+    /// </remarks>
+    public bool EnableAnrDetection { get; set; } = true;
+
+    /// <summary>
+    /// Specifies how long the main thread must stay blocked before the SDK reports an ANR.
+    /// </summary>
+    /// <remarks>
+    /// Applies only when <see cref="EnableAnrDetection"/> is enabled, and only to the V1 implementation used on Android
+    /// versions before 11. On Android 11 and later, the operating system determines when the application stops responding, so
+    /// this value has no effect.
+    /// </remarks>
+    public TimeSpan AnrTimeoutInterval { get; set; } = TimeSpan.FromMilliseconds(5000);
+
+    /// <summary>
+    /// Attaches the operating system's thread dump to the ANR event as a plain-text attachment, adding detail for
+    /// investigating where the application became unresponsive.
+    /// </summary>
+    /// <remarks>
+    /// Applies only when <see cref="EnableAnrDetection"/> is enabled, and only to the V2 implementation used on Android
+    /// 11 and later.
+    /// </remarks>
+    public bool AttachAnrThreadDump { get; set; } = false;
+}