feat: Allow initializing manually and shutting down SentrySDK

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Improvements
+
+- Improve initialization flow ([#322](https://github.com/getsentry/sentry-godot/pull/322))
+
 ### Dependencies
 
 - Bump Cocoa SDK from v8.54.0 to v8.55.0 ([#318](https://github.com/getsentry/sentry-godot/pull/318))

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

@@ -123,6 +123,16 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
             }
     }
 
+    @UsedByGodot
+    fun close() {
+        Sentry.close()
+    }
+
+    @UsedByGodot
+    fun isEnabled(): Boolean {
+      return Sentry.isEnabled()
+    }
+
     @UsedByGodot
     fun addFileAttachment(path: String, filename: String, contentType: String, attachmentType: String) {
         val attachment = Attachment(

doc_classes/SentrySDK.xml

@@ -48,6 +48,12 @@
 				Captures an event with [param message] and sends it to Sentry, returning the event ID.
 			</description>
 		</method>
+		<method name="close">
+			<return type="void" />
+			<description>
+				Closes the SDK and flushes any pending events to ensure all queued data is sent to Sentry before shutdown. Called automatically when the application exits.
+			</description>
+		</method>
 		<method name="create_event" qualifiers="const">
 			<return type="SentryEvent" />
 			<description>
@@ -66,6 +72,12 @@
 				Returns the currently set user. See [SentryUser].
 			</description>
 		</method>
+		<method name="init">
+			<return type="void" />
+			<description>
+				Initializes the SDK. Called automatically during startup if [member SentryOptions.enabled] is set to [code]true[/code]. Manual initialization is only needed when you want to control the exact timing of SDK startup or when automatic initialization is disabled.
+			</description>
+		</method>
 		<method name="is_enabled" qualifiers="const">
 			<return type="bool" />
 			<description>

project/test/isolated/test_sdk_close.gd

@@ -0,0 +1,35 @@
+extends GdUnitTestSuite
+## Test SDK should stop capture if closed via code.
+
+
+signal callback_processed
+
+
+static func configure_options(options: SentryOptions) -> void:
+	# Ensure SDK auto-intialization.
+	options.enabled = true
+
+
+func before_test() -> void:
+	SentrySDK._set_before_send(_before_send)
+
+
+func _before_send(_ev: SentryEvent) -> SentryEvent:
+	callback_processed.emit()
+	return null
+
+
+func test_capture_when_sdk_closed() -> void:
+	var monitor := monitor_signals(self, false)
+
+	# SDK should auto initialize when enabled.
+	assert_bool(SentrySDK.is_enabled()).is_true()
+
+	SentrySDK.capture_message("message captured when SDK is initialiazed")
+	await assert_signal(monitor).is_emitted("callback_processed")
+
+	SentrySDK.close()
+	assert_bool(SentrySDK.is_enabled()).is_false()
+
+	SentrySDK.capture_message("message not captured when SDK is closed")
+	await assert_signal(monitor).is_not_emitted("callback_processed")

project/test/isolated/test_sdk_close.gd.uid

@@ -0,0 +1 @@
+uid://bitdh4j15m2tl

project/test/isolated/test_sdk_lifecycle.gd

@@ -0,0 +1,42 @@
+extends GdUnitTestSuite
+## Test SDK lifecycle methods.
+
+
+signal callback_processed
+
+
+static func configure_options(options: SentryOptions) -> void:
+	# Disable SDK auto-intialization.
+	options.enabled = false
+
+
+func before_test() -> void:
+	SentrySDK._set_before_send(_before_send)
+
+
+func _before_send(_ev: SentryEvent) -> SentryEvent:
+	callback_processed.emit()
+	return null
+
+
+## Test manual initialization and shutdown of SDK.
+func test_lifecycle() -> void:
+	var monitor := monitor_signals(self, false)
+
+	# SDK should be disabled when `options.enabled = false`
+	assert_bool(SentrySDK.is_enabled()).is_false()
+
+	SentrySDK.capture_message("message not captured before SDK is initialized")
+	await assert_signal(monitor).is_not_emitted("callback_processed")
+
+	SentrySDK.init()
+	assert_bool(SentrySDK.is_enabled()).is_true()
+
+	SentrySDK.capture_message("message captured when SDK is initialiazed")
+	await assert_signal(monitor).is_emitted("callback_processed")
+
+	SentrySDK.close()
+	assert_bool(SentrySDK.is_enabled()).is_false()
+
+	SentrySDK.capture_message("message not captured when SDK is closed")
+	await assert_signal(monitor).is_not_emitted("callback_processed")

project/test/isolated/test_sdk_lifecycle.gd.uid

@@ -0,0 +1 @@
+uid://lrv0g3lj2pds

src/register_types.cpp

@@ -39,59 +39,67 @@
 using namespace godot;
 using namespace sentry;
 
-void initialize_module(ModuleInitializationLevel p_level) {
-	if (p_level == MODULE_INITIALIZATION_LEVEL_CORE) {
-	} else if (p_level == godot::MODULE_INITIALIZATION_LEVEL_SERVERS) {
-	} else if (p_level == MODULE_INITIALIZATION_LEVEL_SCENE) {
-		GDREGISTER_CLASS(SentryLoggerLimits);
-		GDREGISTER_CLASS(SentryOptions);
-		GDREGISTER_INTERNAL_CLASS(RuntimeConfig);
-		GDREGISTER_CLASS(SentryConfiguration);
-		GDREGISTER_CLASS(SentryUser);
-		GDREGISTER_CLASS(SentryTimestamp);
-		GDREGISTER_CLASS(SentrySDK);
-		GDREGISTER_ABSTRACT_CLASS(SentryAttachment);
-		GDREGISTER_ABSTRACT_CLASS(SentryEvent);
-		GDREGISTER_INTERNAL_CLASS(DisabledEvent);
-		GDREGISTER_INTERNAL_CLASS(SentryEventProcessor);
-		GDREGISTER_INTERNAL_CLASS(ScreenshotProcessor);
-		GDREGISTER_INTERNAL_CLASS(ViewHierarchyProcessor);
-		GDREGISTER_INTERNAL_CLASS(SentryLogger);
+void register_runtime_classes() {
+	GDREGISTER_CLASS(SentryLoggerLimits);
+	GDREGISTER_CLASS(SentryOptions);
+	GDREGISTER_INTERNAL_CLASS(RuntimeConfig);
+	GDREGISTER_CLASS(SentryConfiguration);
+	GDREGISTER_CLASS(SentryUser);
+	GDREGISTER_CLASS(SentryTimestamp);
+	GDREGISTER_CLASS(SentrySDK);
+	GDREGISTER_ABSTRACT_CLASS(SentryAttachment);
+	GDREGISTER_ABSTRACT_CLASS(SentryEvent);
+	GDREGISTER_INTERNAL_CLASS(DisabledEvent);
+	GDREGISTER_INTERNAL_CLASS(SentryEventProcessor);
+	GDREGISTER_INTERNAL_CLASS(ScreenshotProcessor);
+	GDREGISTER_INTERNAL_CLASS(ViewHierarchyProcessor);
+	GDREGISTER_INTERNAL_CLASS(SentryLogger);
 
 #ifdef SDK_NATIVE
-		GDREGISTER_INTERNAL_CLASS(NativeEvent);
+	GDREGISTER_INTERNAL_CLASS(NativeEvent);
 #endif
 
 #ifdef SDK_ANDROID
-		GDREGISTER_INTERNAL_CLASS(AndroidEvent);
-		GDREGISTER_INTERNAL_CLASS(SentryAndroidBeforeSendHandler);
+	GDREGISTER_INTERNAL_CLASS(AndroidEvent);
+	GDREGISTER_INTERNAL_CLASS(SentryAndroidBeforeSendHandler);
 #endif
 
 #ifdef SDK_COCOA
-		GDREGISTER_INTERNAL_CLASS(cocoa::CocoaEvent);
+	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaEvent);
 #endif
+}
 
-		SentryOptions::create_singleton();
-
-		SentrySDK *sentry_singleton = memnew(SentrySDK);
-		Engine::get_singleton()->register_singleton("SentrySDK", SentrySDK::get_singleton());
-	} else if (p_level == MODULE_INITIALIZATION_LEVEL_EDITOR) {
+void register_editor_classes() {
 #ifdef TOOLS_ENABLED
+	GDREGISTER_INTERNAL_CLASS(SentryEditorExportPluginAndroid);
+	GDREGISTER_INTERNAL_CLASS(SentryEditorPlugin);
+
 #ifndef WINDOWS_ENABLED
-		GDREGISTER_INTERNAL_CLASS(SentryEditorExportPluginUnix);
+	GDREGISTER_INTERNAL_CLASS(SentryEditorExportPluginUnix);
 #endif // !WINDOWS_ENABLED
-		GDREGISTER_INTERNAL_CLASS(SentryEditorExportPluginAndroid);
-		GDREGISTER_INTERNAL_CLASS(SentryEditorPlugin);
+
+#endif // TOOLS_ENABLED
+}
+
+void initialize_module(ModuleInitializationLevel p_level) {
+	if (p_level == MODULE_INITIALIZATION_LEVEL_CORE) {
+	} else if (p_level == MODULE_INITIALIZATION_LEVEL_SERVERS) {
+	} else if (p_level == MODULE_INITIALIZATION_LEVEL_SCENE) {
+		register_runtime_classes();
+		SentryOptions::create_singleton();
+		SentrySDK::create_singleton();
+		SentrySDK::get_singleton()->prepare_and_auto_initialize();
+	} else if (p_level == MODULE_INITIALIZATION_LEVEL_EDITOR) {
+#ifdef TOOLS_ENABLED
+		register_editor_classes();
 		EditorPlugins::add_by_type<SentryEditorPlugin>();
 #endif // TOOLS_ENABLED
 	}
 }
 
 void uninitialize_module(ModuleInitializationLevel p_level) {
 	if (p_level == MODULE_INITIALIZATION_LEVEL_SCENE) {
-		if (SentrySDK::get_singleton()) {
-			memdelete(SentrySDK::get_singleton());
-		}
+		SentrySDK::destroy_singleton();
 		SentryOptions::destroy_singleton();
 	}
 }

src/sentry/android/android_sdk.cpp

@@ -125,11 +125,9 @@ void AndroidSDK::add_attachment(const Ref<SentryAttachment> &p_attachment) {
 	}
 }
 
-void AndroidSDK::initialize(const PackedStringArray &p_global_attachments) {
+void AndroidSDK::init(const PackedStringArray &p_global_attachments) {
 	ERR_FAIL_NULL(android_plugin);
 
-	sentry::util::print_debug("Initializing Sentry Android SDK");
-
 	for (const String &path : p_global_attachments) {
 		bool is_view_hierarchy = path.ends_with(SENTRY_VIEW_HIERARCHY_FN);
 		android_plugin->call(ANDROID_SN(addFileAttachment),
@@ -139,7 +137,7 @@ void AndroidSDK::initialize(const PackedStringArray &p_global_attachments) {
 				is_view_hierarchy ? "event.view_hierarchy" : String());
 	}
 
-	android_plugin->call("initialize",
+	android_plugin->call(ANDROID_SN(init),
 			before_send_handler->get_instance_id(),
 			SentryOptions::get_singleton()->get_dsn(),
 			SentryOptions::get_singleton()->is_debug_enabled(),
@@ -150,6 +148,16 @@ void AndroidSDK::initialize(const PackedStringArray &p_global_attachments) {
 			SentryOptions::get_singleton()->get_max_breadcrumbs());
 }
 
+void AndroidSDK::close() {
+	if (android_plugin != nullptr) {
+		android_plugin->call(ANDROID_SN(close));
+	}
+}
+
+bool AndroidSDK::is_enabled() const {
+	return android_plugin && android_plugin->call(ANDROID_SN(isEnabled));
+}
+
 AndroidSDK::AndroidSDK() {
 	AndroidStringNames::create_singleton();
 

src/sentry/android/android_sdk.h

@@ -49,7 +49,9 @@ class AndroidSDK : public InternalSDK {
 
 	virtual void add_attachment(const Ref<SentryAttachment> &p_attachment) override;
 
-	virtual void initialize(const PackedStringArray &p_global_attachments) override;
+	virtual void init(const PackedStringArray &p_global_attachments) override;
+	virtual void close() override;
+	virtual bool is_enabled() const override;
 
 	bool has_android_plugin() const { return android_plugin != nullptr; }
 

src/sentry/android/android_string_names.cpp

@@ -15,6 +15,9 @@ void AndroidStringNames::destroy_singleton() {
 
 AndroidStringNames::AndroidStringNames() {
 	// API methods.
+	init = StringName("init");
+	close = StringName("close");
+	isEnabled = StringName("isEnabled");
 	setContext = StringName("setContext");
 	removeContext = StringName("removeContext");
 	setTag = StringName("setTag");

src/sentry/android/android_string_names.h

@@ -27,6 +27,9 @@ class AndroidStringNames {
 	_FORCE_INLINE_ static AndroidStringNames *get_singleton() { return singleton; }
 
 	// API methods.
+	StringName init;
+	StringName close;
+	StringName isEnabled;
 	StringName setContext;
 	StringName removeContext;
 	StringName setTag;

src/sentry/cocoa/cocoa_sdk.h

@@ -36,9 +36,9 @@ class CocoaSDK : public InternalSDK {
 
 	virtual void add_attachment(const Ref<SentryAttachment> &p_attachment) override;
 
-	virtual void initialize(const PackedStringArray &p_global_attachments) override;
-
-	bool is_enabled() const;
+	virtual void init(const PackedStringArray &p_global_attachments) override;
+	virtual void close() override;
+	virtual bool is_enabled() const override;
 
 	CocoaSDK();
 	virtual ~CocoaSDK() override;

src/sentry/cocoa/cocoa_sdk.mm

@@ -144,7 +144,7 @@
 	}];
 }
 
-void CocoaSDK::initialize(const PackedStringArray &p_global_attachments) {
+void CocoaSDK::init(const PackedStringArray &p_global_attachments) {
 	[PrivateSentrySDKOnly setSdkName:@"sentry.cocoa.godot"];
 
 	[objc::SentrySDK startWithConfigureOptions:^(objc::SentryOptions *options) {
@@ -200,6 +200,10 @@
 	}];
 }
 
+void CocoaSDK::close() {
+	[objc::SentrySDK close];
+}
+
 bool CocoaSDK::is_enabled() const {
 	return [objc::SentrySDK isEnabled];
 }
@@ -209,9 +213,7 @@
 }
 
 CocoaSDK::~CocoaSDK() {
-	if (is_enabled()) {
-		[objc::SentrySDK close];
-	}
+	close();
 }
 
 } //namespace sentry::cocoa

src/sentry/contexts.cpp

@@ -3,7 +3,6 @@
 #include "gen/sdk_version.gen.h"
 #include "sentry/environment.h"
 #include "sentry/sentry_options.h"
-#include "sentry/uuid.h"
 
 #include <godot_cpp/classes/dir_access.hpp>
 #include <godot_cpp/classes/display_server.hpp>
@@ -50,6 +49,14 @@ String _screen_orientation_as_string(int32_t p_screen) {
 
 namespace sentry::contexts {
 
+bool should_delay_contexts() {
+	// Delay contexts if engine singletons are not ready.
+	return !OS::get_singleton() || !Engine::get_singleton() ||
+			!DisplayServer::get_singleton() || !Time::get_singleton() ||
+			!ProjectSettings::get_singleton() || !Performance::get_singleton() ||
+			!RenderingServer::get_singleton();
+}
+
 Dictionary make_device_context(const Ref<RuntimeConfig> &p_runtime_config) {
 	Dictionary device_context = Dictionary();
 	ERR_FAIL_NULL_V(OS::get_singleton(), device_context);

src/sentry/contexts.h

@@ -10,6 +10,8 @@ using namespace godot;
 
 namespace sentry::contexts {
 
+bool should_delay_contexts();
+
 Dictionary make_device_context(const Ref<RuntimeConfig> &p_runtime_config);
 
 // Returns smaller device context dictionary that only includes values that are

src/sentry/disabled/disabled_sdk.h

@@ -28,7 +28,9 @@ class DisabledSDK : public InternalSDK {
 
 	virtual void add_attachment(const Ref<SentryAttachment> &p_attachment) override {}
 
-	virtual void initialize(const PackedStringArray &p_global_attachments) override {}
+	virtual void init(const PackedStringArray &p_global_attachments) override {}
+	virtual void close() override {}
+	virtual bool is_enabled() const override { return false; }
 };
 
 } // namespace sentry