[WIP] feat(sessions): Expose session tracking options

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Add opt-in automatic network metrics for peer counts, ping, packet loss, and traffic rates, configurable through `SentryOptions.auto_metrics` and Project Settings ([#1033](https://github.com/getsentry/sentry-godot/pull/1033))
 - Web: Add tunneling through your own server to help avoid ad blockers ([#1057](https://github.com/getsentry/sentry-godot/pull/1057))
+- Add `auto_session_tracking` to control automatic session tracking and `session_tracking_interval_ms` to configure its background timeout ([#1069](https://github.com/getsentry/sentry-godot/pull/1069))
 
 ### Fixes
 

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

@@ -307,6 +307,8 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
             val propagateTraceparent = optionsData["propagate_traceparent"] as Boolean
             val orgId = optionsData["org_id"] as String
             val maxBreadcrumbs = optionsData["max_breadcrumbs"].toIntOrThrow()
+            val autoSessionTracking = optionsData["auto_session_tracking"] as Boolean
+            val sessionTrackingIntervalMs = optionsData["session_tracking_interval_ms"].toLongOrThrow()
             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
@@ -324,6 +326,8 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
                 options.isPropagateTraceparent = propagateTraceparent
                 options.orgId = orgId.ifEmpty { null }
                 options.maxBreadcrumbs = maxBreadcrumbs
+                options.isEnableAutoSessionTracking = autoSessionTracking
+                options.sessionTrackingIntervalMillis = sessionTrackingIntervalMs
                 options.sdkVersion?.name = "sentry.java.android.godot"
                 options.nativeSdkName = "sentry.native.android.godot"
                 options.isAnrEnabled = enableAnrDetection

doc_classes/SentryOptions.xml

@@ -38,6 +38,9 @@
 		<member name="auto_metrics" type="SentryAutoMetricsOptions" setter="" getter="get_auto_metrics">
 			Configures automatic performance metric collection. See [SentryAutoMetricsOptions].
 		</member>
+		<member name="auto_session_tracking" type="bool" setter="set_auto_session_tracking" getter="is_auto_session_tracking_enabled" default="true">
+			If [code]true[/code], the SDK automatically tracks sessions for [url=https://docs.sentry.io/product/releases/health/]Release Health[/url].
+		</member>
 		<member name="before_capture_screenshot" type="Callable" setter="set_before_capture_screenshot" getter="get_before_capture_screenshot" default="Callable()">
 			If assigned, this callback runs before a screenshot is captured. It takes [SentryEvent] as a parameter and returns [code]false[/code] to skip capturing the screenshot, or [code]true[/code] to capture the screenshot.
 			[codeblock]
@@ -201,6 +204,10 @@
 		<member name="send_default_pii" type="bool" setter="set_send_default_pii" getter="is_send_default_pii_enabled" default="false">
 			If [code]true[/code], the SDK will include PII (Personally Identifiable Information) with the events.
 		</member>
+		<member name="session_tracking_interval_ms" type="int" setter="set_session_tracking_interval_ms" getter="get_session_tracking_interval_ms" default="30000">
+			How long the application can remain in the background before its session ends, in milliseconds. Defaults to [code]30000[/code] (30 seconds). Only applies when [member auto_session_tracking] is enabled.
+			[b]Platform support:[/b] Android, iOS, and macOS. Has no effect on Windows, Linux, or Web.
+		</member>
 		<member name="shutdown_timeout_ms" type="int" setter="set_shutdown_timeout_ms" getter="get_shutdown_timeout_ms" default="2000">
 			The maximum time in milliseconds the SDK will wait for pending events to be sent when [method SentrySDK.close] is called. If the timeout expires, the SDK will perform a forced shutdown and any unsent events may be lost.
 		</member>

project/test/dotnet/DotnetTestHarness.cs

@@ -125,6 +125,8 @@ public void InitWithInteropOptions()
             _receivedOptions["trace_propagation_targets"] = tracePropagationTargets;
             _receivedOptions["propagate_traceparent"] = options.PropagateTraceparent;
             _receivedOptions["org_id"] = options.OrgId;
+            _receivedOptions["auto_session_tracking"] = options.AutoSessionTracking;
+            _receivedOptions["session_tracking_interval_ms"] = (int)options.AutoSessionTrackingInterval.TotalMilliseconds;
             _receivedOptions["max_breadcrumbs"] = options.MaxBreadcrumbs;
             _receivedOptions["shutdown_timeout_ms"] = (int)options.ShutdownTimeout.TotalMilliseconds;
             _receivedOptions["send_default_pii"] = options.SendDefaultPii;
@@ -171,6 +173,8 @@ public void InitWithInteropOptions()
             options.TracePropagationTargets.Add("ddd");
             options.PropagateTraceparent = false;
             options.OrgId = "222";
+            options.AutoSessionTracking = true;
+            options.AutoSessionTrackingInterval = TimeSpan.FromMilliseconds(45000);
             options.MaxBreadcrumbs = 22;
             options.ShutdownTimeout = TimeSpan.FromMilliseconds(2200);
             options.SendDefaultPii = false;

project/test/suites/test_options.gd

@@ -18,6 +18,7 @@ func test_bool_properties(property: String, test_parameters := [
 		["attach_screenshot"],
 		["attach_scene_tree"],
 		["send_default_pii"],
+		["auto_session_tracking"],
 ]) -> void:
 	options.set(property, true)
 	assert_bool(options.get(property)).is_true()
@@ -65,6 +66,13 @@ func test_web_options_retain_assigned_values(property: String, value: Variant, t
 	assert_that(options.web.get(property)).is_equal(value)
 
 
+func test_session_tracking_defaults() -> void:
+	assert_bool(options.auto_session_tracking).is_true()
+	assert_int(options.session_tracking_interval_ms).is_equal(30000)
+	assert_bool(ProjectSettings.get_setting("sentry/options/auto_session_tracking")).is_true()
+	assert_int(ProjectSettings.get_setting("sentry/options/session_tracking_interval_ms")).is_equal(30000)
+
+
 func test_auto_metrics_defaults() -> void:
 	assert_bool(options.auto_metrics.enable_frame_metrics).is_false()
 	assert_float(options.auto_metrics.frame_metrics_interval_sec).is_equal(1.0)
@@ -114,6 +122,17 @@ func test_string_properties(property: String, test_parameters := [
 	assert_str(options.get(property)).is_equal("test-value")
 
 
+## Test simple int properties.
+@warning_ignore("unused_parameter")
+func test_int_properties(property: String, value: int, test_parameters := [
+		["max_breadcrumbs", 42],
+		["shutdown_timeout_ms", 5000],
+		["session_tracking_interval_ms", 45000],
+]) -> void:
+	options.set(property, value)
+	assert_int(options.get(property)).is_equal(value)
+
+
 ## SentryOptions.sample_rate should be set to the specified value.
 func test_sample_rate() -> void:
 	options.sample_rate = 0.5
@@ -143,18 +162,6 @@ func test_empty_trace_propagation_targets_are_filtered_out() -> void:
 	assert_array(options.trace_propagation_targets).contains_exactly(["valid.example.com"])
 
 
-## SentryOptions.max_breadcrumbs should be set to the specified value.
-func test_max_breadcrumbs() -> void:
-	options.max_breadcrumbs = 42
-	assert_int(options.max_breadcrumbs).is_equal(42)
-
-
-## SentryOptions.shutdown_timeout_ms should be set to the specified value.
-func test_shutdown_timeout_ms() -> void:
-	options.shutdown_timeout_ms = 5000
-	assert_int(options.shutdown_timeout_ms).is_equal(5000)
-
-
 ## Test mask properties on godot_logger options.
 @warning_ignore("unused_parameter")
 func test_godot_logger_mask_properties(property: String, test_parameters := [

src/sentry/android/android_sdk.cpp

@@ -442,6 +442,8 @@ void AndroidSDK::init() {
 	optionsData["propagate_traceparent"] = SENTRY_OPTIONS()->is_propagate_traceparent_enabled();
 	optionsData["org_id"] = SENTRY_OPTIONS()->get_org_id();
 	optionsData["max_breadcrumbs"] = SENTRY_OPTIONS()->get_max_breadcrumbs();
+	optionsData["auto_session_tracking"] = SENTRY_OPTIONS()->is_auto_session_tracking_enabled();
+	optionsData["session_tracking_interval_ms"] = SENTRY_OPTIONS()->get_session_tracking_interval_ms();
 	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();

src/sentry/cocoa/cocoa_sdk.mm

@@ -335,6 +335,8 @@ void _add_default_attachments(SentryObjCScope *p_scope) {
 		options.sampleRate = double_to_objc(SENTRY_OPTIONS()->get_sample_rate());
 		options.tracesSampleRate = double_to_objc(SENTRY_OPTIONS()->get_traces_sample_rate());
 		options.maxBreadcrumbs = (NSUInteger)SENTRY_OPTIONS()->get_max_breadcrumbs();
+		options.enableAutoSessionTracking = SENTRY_OPTIONS()->is_auto_session_tracking_enabled();
+		options.sessionTrackingIntervalMillis = SENTRY_OPTIONS()->get_session_tracking_interval_ms();
 		options.sendDefaultPii = SENTRY_OPTIONS()->is_send_default_pii_enabled();
 		options.diagnosticLevel = sentry_level_to_objc(SENTRY_OPTIONS()->get_diagnostic_level());
 		options.orgId = string_to_objc_or_nil_if_empty(SENTRY_OPTIONS()->get_org_id());

src/sentry/dotnet/csharp_interop.cpp

@@ -231,6 +231,8 @@ struct NativeOptions {
 	double traces_sample_rate;
 	int32_t max_breadcrumbs;
 	double shutdown_timeout_ms;
+	uint8_t auto_session_tracking;
+	int32_t session_tracking_interval_ms;
 	uint8_t send_default_pii;
 
 	// Godot-specific
@@ -282,6 +284,8 @@ struct ManagedOptions {
 	double traces_sample_rate;
 	int32_t max_breadcrumbs;
 	double shutdown_timeout_ms;
+	uint8_t auto_session_tracking;
+	int32_t session_tracking_interval_ms;
 	uint8_t send_default_pii;
 
 	uint8_t attach_log;
@@ -344,6 +348,8 @@ static void _apply_managed_options(const ManagedOptions &data, Ref<SentryOptions
 	options->set_traces_sample_rate(data.traces_sample_rate);
 	options->set_max_breadcrumbs(data.max_breadcrumbs);
 	options->set_shutdown_timeout_ms(data.shutdown_timeout_ms);
+	options->set_auto_session_tracking(data.auto_session_tracking != 0);
+	options->set_session_tracking_interval_ms(data.session_tracking_interval_ms);
 	options->set_send_default_pii(data.send_default_pii);
 	options->set_attach_log(data.attach_log);
 	options->set_attach_scene_tree(data.attach_scene_tree);
@@ -394,6 +400,8 @@ void _populate_options_data(NativeOptions &r_data, const Ref<SentryOptions> &opt
 	r_data.traces_sample_rate = options->get_traces_sample_rate();
 	r_data.max_breadcrumbs = options->get_max_breadcrumbs();
 	r_data.shutdown_timeout_ms = options->get_shutdown_timeout_ms();
+	r_data.auto_session_tracking = options->is_auto_session_tracking_enabled() ? 1 : 0;
+	r_data.session_tracking_interval_ms = options->get_session_tracking_interval_ms();
 	r_data.send_default_pii = options->is_send_default_pii_enabled();
 	r_data.attach_log = options->is_attach_log_enabled();
 	r_data.attach_scene_tree = options->is_attach_scene_tree_enabled();

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

@@ -193,6 +193,8 @@ private struct NativeOptions
         public double traces_sample_rate;
         public int max_breadcrumbs;
         public double shutdown_timeout_ms;
+        public byte auto_session_tracking;
+        public int session_tracking_interval_ms;
         public byte send_default_pii;
         public byte attach_log;
         public byte attach_scene_tree;
@@ -234,6 +236,8 @@ private unsafe struct ManagedOptions
         public double traces_sample_rate;
         public int max_breadcrumbs;
         public double shutdown_timeout_ms;
+        public byte auto_session_tracking;
+        public int session_tracking_interval_ms;
         public byte send_default_pii;
         public byte attach_log;
         public byte attach_scene_tree;
@@ -690,6 +694,8 @@ private static void ApplyNativeOptions(NativeOptions data, SentryGodotOptions op
         opts.TracesSampleRate = data.traces_sample_rate;
         opts.MaxBreadcrumbs = data.max_breadcrumbs;
         opts.ShutdownTimeout = TimeSpan.FromMilliseconds(data.shutdown_timeout_ms);
+        opts.AutoSessionTracking = data.auto_session_tracking != 0;
+        opts.AutoSessionTrackingInterval = TimeSpan.FromMilliseconds(data.session_tracking_interval_ms);
         opts.SendDefaultPii = data.send_default_pii != 0;
         opts.AttachLog = data.attach_log != 0;
         opts.AttachSceneTree = data.attach_scene_tree != 0;
@@ -1013,6 +1019,8 @@ public static unsafe void InitNativeSdk(SentryGodotOptions opts)
                 traces_sample_rate = opts.TracesSampleRate ?? 0.0,
                 max_breadcrumbs = opts.MaxBreadcrumbs,
                 shutdown_timeout_ms = opts.ShutdownTimeout.TotalMilliseconds,
+                auto_session_tracking = (byte)(opts.AutoSessionTracking ? 1 : 0),
+                session_tracking_interval_ms = (int)opts.AutoSessionTrackingInterval.TotalMilliseconds,
                 send_default_pii = (byte)(opts.SendDefaultPii ? 1 : 0),
                 attach_log = (byte)(opts.AttachLog ? 1 : 0),
                 attach_scene_tree = (byte)(opts.AttachSceneTree ? 1 : 0),

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

@@ -9,6 +9,7 @@ namespace Sentry.Godot;
 /// Configures the Sentry SDK for Godot.
 /// </summary>
 /// <remarks>
+/// <see cref="SentryOptions.AutoSessionTrackingInterval"/> applies to Android, iOS, and macOS only.
 /// Regular expressions in <see cref="SentryOptions.TracePropagationTargets"/> sync to the native layer using only
 /// their pattern. Constructor-supplied <see cref="System.Text.RegularExpressions.RegexOptions"/> are not preserved.
 /// For case-insensitive matching in both layers, include <c>(?i)</c> in the pattern instead of using
@@ -22,9 +23,6 @@ public SentryGodotOptions()
         EnableScopeSync = true;
         ScopeObserver = new GodotScopeObserver();
 
-        // Native layer owns sessions; .NET-side tracking would double-count.
-        AutoSessionTracking = false;
-
         AddInAppExclude("Godot");
         AddIntegration(new GodotSdkIntegration());
 

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

@@ -118,7 +118,19 @@ private static void InitDotnet(SentryGodotOptions godotOptions)
 
         ConfigureAssemblyReader(godotOptions);
         ConfigureCocoaDebugImagesOnIOS(godotOptions);
-        Sentry.SentrySdk.Init(godotOptions);
+
+        // Native layer owns sessions; .NET-side tracking would double-count.
+        var autoSessionTracking = godotOptions.AutoSessionTracking;
+        godotOptions.AutoSessionTracking = false;
+        try
+        {
+            Sentry.SentrySdk.Init(godotOptions);
+        }
+        finally
+        {
+            godotOptions.AutoSessionTracking = autoSessionTracking;
+        }
+
         InitFirstChanceExceptionHandler();
     }
 

src/sentry/javascript/bridge/src/sentry-bridge.ts

@@ -217,6 +217,7 @@ class SentryBridge {
     propagateTraceparent: boolean,
     orgId: "" | `${number}`,
     maxBreadcrumbs: number,
+    autoSessionTracking: boolean,
     sendDefaultPii: boolean,
     sdkVersion: string,
     enableTunnel: boolean,
@@ -256,7 +257,7 @@ class SentryBridge {
           "Console", // very noisy in the Godot SDK
         ];
         const filtered = integrations.filter(function (integration: { name: string }) {
-          return !excludedIntegrations.includes(integration.name);
+          return !excludedIntegrations.includes(integration.name) && (autoSessionTracking || integration.name !== "BrowserSession");
         });
         filtered.push(wasmIntegration());
         if (traceLifecycle === TraceLifecycle.Stream) {

src/sentry/javascript/bridge/test.js

@@ -141,10 +141,10 @@ try {
 			transaction.tags = { processed : "true" };
 			transaction.shouldDiscard = discardNextTransaction;
 		};
-		const initBridge = (traceLifecycle, propagateTraceparent = false, orgId = "", tracePropagationTargets = [ { pattern : ".*", is_regex : false } ]) => {
+		const initBridge = (traceLifecycle, propagateTraceparent = false, orgId = "", tracePropagationTargets = [ { pattern : ".*", is_regex : false } ], autoSessionTracking = true) => {
 			bridge.init(() => {}, beforeSendTransaction, beforeSendFeedback, null, null, readAttachment, "https://test@sentry.io/123", false,
 					"1.0.0", "1", "production", 1.0, 1.0, traceLifecycle, JSON.stringify(tracePropagationTargets),
-					propagateTraceparent, orgId, 100, false,
+					propagateTraceparent, orgId, 100, autoSessionTracking, false,
 					"0.1.0", false, "", "", false);
 		};
 
@@ -166,6 +166,18 @@ try {
 			assertEqual(targets[1].source, "api\\.example\\.com", "regular expression patterns should be preserved");
 		});
 
+		runTest("init() disables automatic session tracking", () => {
+			initBridge(bridge.TraceLifecycle.Stream, false, "", [], false);
+			const client = bridge.createScope().getClient();
+			assert(!client.getIntegrationByName("BrowserSession"), "BrowserSession should be excluded when disabled");
+		});
+
+		runTest("init() enables automatic session tracking", () => {
+			initBridge(bridge.TraceLifecycle.Stream);
+			const client = bridge.createScope().getClient();
+			assert(client.getIntegrationByName("BrowserSession"), "BrowserSession should be included by default");
+		});
+
 		runTest("console output does not produce breadcrumbs", () => {
 			getIsolationScope().clearBreadcrumbs();
 			let event;

src/sentry/javascript/javascript_sdk.cpp

@@ -420,6 +420,7 @@ void JavaScriptSDK::init() {
 			SENTRY_OPTIONS()->is_propagate_traceparent_enabled(),
 			SENTRY_OPTIONS()->get_org_id().utf8().get_data(),
 			SENTRY_OPTIONS()->get_max_breadcrumbs(),
+			SENTRY_OPTIONS()->is_auto_session_tracking_enabled(),
 			SENTRY_OPTIONS()->is_send_default_pii_enabled(),
 			SENTRY_GODOT_SDK_VERSION,
 			SENTRY_OPTIONS()->get_web()->get_enable_tunnel(),

src/sentry/native/native_sdk.cpp

@@ -444,6 +444,7 @@ void NativeSDK::init() {
 	}
 	sentry_options_set_max_breadcrumbs(options, SENTRY_OPTIONS()->get_max_breadcrumbs());
 	sentry_options_set_shutdown_timeout(options, SENTRY_OPTIONS()->get_shutdown_timeout_ms());
+	sentry_options_set_auto_session_tracking(options, SENTRY_OPTIONS()->is_auto_session_tracking_enabled());
 	sentry_options_set_sdk_name(options, "sentry.native.godot");
 	sentry_options_set_logger_enabled_when_crashed(options, false);