feat: Introduce SentryBreadcrumb class

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+### Breaking changes
+
+We've redesigned the breadcrumb API for a cleaner, more intuitive interface. Previously, `add_breadcrumb()` method accepted 5 parameters (3 of which were strings), making it confusing to use. The new approach uses a dedicated `SentryBreadcrumb` class:
+
+```gdscript
+var crumb := SentryBreadcrumb.create("Something happened")
+crumb.type = "info"
+crumb.set_data({"some": "data"})
+SentrySDK.add_breadcrumb(crumb)
+```
+
+For simple breadcrumbs, you can use a one-liner:
+```gdscript
+SentrySDK.add_breadcrumb(SentryBreadcrumb.create("Something happened"))
+```
+
+This change provides better type safety, improved readability, and enables future support for the `before_breadcrumb` callback.
+
 ### Features
 
 - Add support for script context and variables on Apple platforms ([#306](https://github.com/getsentry/sentry-godot/pull/306))
@@ -10,6 +28,7 @@
 ### Improvements
 
 - Improve initialization flow ([#322](https://github.com/getsentry/sentry-godot/pull/322))
+- Introduce `SentryBreadcrumb` class ([#332](https://github.com/getsentry/sentry-godot/pull/332))
 
 ### Fixes
 

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

@@ -43,6 +43,12 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
         }
     }
 
+    private val breadcrumbsByHandle = object : ThreadLocal<MutableMap<Int, Breadcrumb>>() {
+        override fun initialValue(): MutableMap<Int, Breadcrumb> {
+            return mutableMapOf()
+        }
+    }
+
     private fun getEvent(eventHandle: Int): SentryEvent? {
         val event: SentryEvent? = eventsByHandle.get()?.get(eventHandle)
         if (event == null) {
@@ -59,6 +65,14 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
         return exception
     }
 
+    private fun getBreadcrumb(breadcrumbHandle: Int): Breadcrumb? {
+        var crumb: Breadcrumb? = breadcrumbsByHandle.get()?.get(breadcrumbHandle)
+        if (crumb == null) {
+            Log.e(TAG, "Internal Error -- Breadcrumb not found: $breadcrumbHandle")
+        }
+        return crumb
+    }
+
     private fun registerEvent(event: SentryEvent): Int {
         val eventsMap = eventsByHandle.get() ?: run {
             Log.e(TAG, "Internal Error -- eventsByHandle is null")
@@ -89,6 +103,21 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
         return handle
     }
 
+    private fun registerBreadcrumb(crumb: Breadcrumb): Int {
+        val breadcrumbsMap = breadcrumbsByHandle.get() ?: run {
+            Log.e(TAG, "Internal Error -- breadcrumbsByHandle is null")
+            return 0
+        }
+
+        var handle = Random.nextInt()
+        while (breadcrumbsMap.containsKey(handle)) {
+            handle = Random.nextInt()
+        }
+
+        breadcrumbsMap[handle] = crumb
+        return handle
+    }
+
     override fun getPluginName(): String {
         return "SentryAndroidGodotPlugin"
     }
@@ -193,23 +222,8 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
     }
 
     @UsedByGodot
-    fun addBreadcrumb(
-        message: String,
-        category: String,
-        level: Int,
-        type: String,
-        data: Dictionary
-    ) {
-        val crumb = Breadcrumb()
-        crumb.message = message
-        crumb.category = category
-        crumb.level = level.toSentryLevel()
-        crumb.type = type
-
-        for ((k, v) in data) {
-            crumb.data[k] = v
-        }
-
+    fun addBreadcrumb(handle: Int) {
+        val crumb = getBreadcrumb(handle) ?: return
         Sentry.addBreadcrumb(crumb)
     }
 
@@ -442,4 +456,79 @@ class SentryAndroidGodotPlugin(godot: Godot) : GodotPlugin(godot) {
         }
         event.exceptions?.add(exception)
     }
+
+    @UsedByGodot
+    fun createBreadcrumb(): Int {
+        val crumb = Breadcrumb()
+        val handle = registerBreadcrumb(crumb)
+        return handle
+    }
+
+    @UsedByGodot
+    fun releaseBreadcrumb(handle: Int) {
+        val breadcrumbsMap = breadcrumbsByHandle.get() ?: run {
+            Log.e(TAG, "Internal Error -- breadcrumbsByHandle is null")
+            return
+        }
+
+        breadcrumbsMap.remove(handle)
+    }
+
+    @UsedByGodot
+    fun breadcrumbSetMessage(handle: Int, message: String) {
+        getBreadcrumb(handle)?.message = message
+    }
+
+    @UsedByGodot
+    fun breadcrumbGetMessage(handle: Int): String {
+        return getBreadcrumb(handle)?.message ?: ""
+    }
+
+    @UsedByGodot
+    fun breadcrumbSetCategory(handle: Int, category: String) {
+        getBreadcrumb(handle)?.category = category
+    }
+
+    @UsedByGodot
+    fun breadcrumbGetCategory(handle: Int): String {
+        return getBreadcrumb(handle)?.category ?: ""
+    }
+
+    @UsedByGodot
+    fun breadcrumbSetLevel(handle: Int, level: Int) {
+        getBreadcrumb(handle)?.level = level.toSentryLevel()
+    }
+
+    @UsedByGodot
+    fun breadcrumbGetLevel(handle: Int): Int {
+        return getBreadcrumb(handle)?.level?.toInt() ?: SentryLevel.INFO.toInt()
+    }
+
+    @UsedByGodot
+    fun breadcrumbSetType(handle: Int, type: String) {
+       getBreadcrumb(handle)?.type = type
+    }
+
+    @UsedByGodot
+    fun breadcrumbGetType(handle: Int): String {
+        return getBreadcrumb(handle)?.type ?: ""
+    }
+
+    @UsedByGodot
+    fun breadcrumbSetData(handle: Int, data: Dictionary) {
+        val crumb = getBreadcrumb(handle) ?: return
+
+        crumb.data.clear()
+
+        for ((k, v) in data) {
+            crumb.data[k] = v
+        }
+    }
+
+    @UsedByGodot
+    fun breadcrumbGetTimestamp(handle: Int): Long {
+        val crumb = getBreadcrumb(handle) ?: return 0
+        return crumb.timestamp.toMicros()
+    }
+
 }

doc_classes/SentryBreadcrumb.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryBreadcrumb" 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>
+		Sentry breadcrumb for error reporting context.
+	</brief_description>
+	<description>
+		A breadcrumb is a small piece of diagnostic data that records an event or action leading up to an error or crash. These breadcrumbs create a trail that shows what the user and your game was doing right before something went wrong.
+		To create a breadcrumb, use the static [method SentryBreadcrumb.create] method with an optional message parameter. Once created, you can configure additional properties like category, level, type, and data before adding it to Sentry using [method SentrySDK.add_breadcrumb].
+		[codeblock]
+		var crumb := SentryBreadcrumb.create("Level finished!")
+		crumb.type = "info"
+		crumb.category = "level.finished"
+		SentrySDK.add_breadcrumb(crumb)
+		[/codeblock]
+		For more information, check out the [url=https://docs.sentry.io/platforms/godot/enriching-events/breadcrumbs/]Breadcrumbs documentation[/url].
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="create" qualifiers="static">
+			<return type="SentryBreadcrumb" />
+			<param index="0" name="message" type="String" default="&quot;&quot;" />
+			<description>
+			</description>
+		</method>
+		<method name="get_timestamp">
+			<return type="SentryTimestamp" />
+			<description>
+				Returns the timestamp of the breadcrumb.
+			</description>
+		</method>
+		<method name="set_data">
+			<return type="void" />
+			<param index="0" name="data" type="Dictionary" />
+			<description>
+				Sets additional data associated with the breadcrumb. This can be useful for providing more context about the event or action that triggered the breadcrumb.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="category" type="String" setter="set_category" getter="get_category">
+			A category label that shows what type of action this breadcrumb represents. Use dot notation like "ui.click" for a button click or "network.request" for an API call.
+		</member>
+		<member name="level" type="int" setter="set_level" getter="get_level" enum="SentrySDK.Level">
+			The severity level of the breadcrumb. Defaults to [code]LEVEL_INFO[/code]. See [enum SentrySDK.Level].
+		</member>
+		<member name="message" type="String" setter="set_message" getter="get_message">
+			A short description of what happened.
+		</member>
+		<member name="type" type="String" setter="set_type" getter="get_type">
+			The type of breadcrumb that determines how it appears in the Sentry interface. Defaults to [code]default[/code] which renders as a Debug entry. Common types include [code]http[/code] for network requests, [code]navigation[/code] for page/screen changes, [code]user[/code] for user interactions, and [code]error[/code] for error events. See [url=https://develop.sentry.dev/sdk/data-model/event-payloads/breadcrumbs/#breadcrumb-types]Breadcrumb Types[/url] for the complete list.
+		</member>
+	</members>
+</class>

doc_classes/SentrySDK.xml

@@ -23,14 +23,10 @@
 		</method>
 		<method name="add_breadcrumb">
 			<return type="void" />
-			<param index="0" name="message" type="String" />
-			<param index="1" name="category" type="String" />
-			<param index="2" name="level" type="int" enum="SentrySDK.Level" default="1" />
-			<param index="3" name="type" type="String" default="&quot;default&quot;" />
-			<param index="4" name="data" type="Dictionary" default="{}" />
+			<param index="0" name="breadcrumb" type="SentryBreadcrumb" />
 			<description>
-				Adds a breadcrumb to the next event. Sentry uses breadcrumbs to create a trail of events that happened prior to an issue.
-				To learn more, visit [url=https://docs.sentry.io/platforms/godot/enriching-events/breadcrumbs/]Breadcrumbs documentation[/url].
+				Adds a breadcrumb to the future events. You can create a [SentryBreadcrumb] object using the static [method SentryBreadcrumb.create] method with an optional message parameter.
+				Sentry uses breadcrumbs to create a trail of events that happened prior to an issue. For more information, see [SentryBreadcrumb] class.
 			</description>
 		</method>
 		<method name="capture_event">

project/test/suites/test_breadcrumb.gd

@@ -0,0 +1,66 @@
+extends GdUnitTestSuite
+## Test SentryBreadcrumb class properties and methods.
+
+
+## Test string properties accessors and UTF-8 encoding preservation.
+@warning_ignore("unused_parameter")
+func test_string_properties_and_utf8(property: String, test_parameters := [
+		["message"],
+		["category"],
+		["type"],
+]) -> void:
+	var crumb := SentryBreadcrumb.create()
+	crumb.set(property, "Hello, World!")
+	assert_str(crumb.get(property)).is_equal("Hello, World!")
+	crumb.set(property, "Hello 世界! 👋")
+	assert_str(crumb.get(property)).is_equal("Hello 世界! 👋")
+
+
+func test_breadcrumb_create_with_message() -> void:
+	var crumb := SentryBreadcrumb.create("test-message")
+	assert_str(crumb.message).is_equal("test-message")
+
+
+func test_breadcrumb_level() -> void:
+	var crumb := SentryBreadcrumb.create()
+	crumb.level = SentrySDK.LEVEL_DEBUG
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_DEBUG)
+	crumb.level = SentrySDK.LEVEL_INFO
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_INFO)
+	crumb.level = SentrySDK.LEVEL_WARNING
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_WARNING)
+	crumb.level = SentrySDK.LEVEL_ERROR
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_ERROR)
+	crumb.level = SentrySDK.LEVEL_FATAL
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_FATAL)
+
+
+func test_breadcrumb_can_set_data() -> void:
+	var crumb := SentryBreadcrumb.create()
+	crumb.set_data({"biome": "forest", "time_of_day": 0.42})
+
+
+func test_breadcrumb_default_values() -> void:
+	var crumb := SentryBreadcrumb.create()
+	assert_str(crumb.message).is_empty()
+	assert_str(crumb.type).is_empty()
+	assert_int(crumb.level).is_equal(SentrySDK.LEVEL_INFO)
+	assert_bool(crumb.category in ["", "default"]).is_true()
+
+
+func test_breadcrumb_timestamp_is_set_automatically() -> void:
+	var time_before: float = Time.get_unix_time_from_system()
+	await get_tree().process_frame  # small delay to ensure timestamp differs
+
+	var crumb := SentryBreadcrumb.create()
+
+	await get_tree().process_frame
+	var time_after: float = Time.get_unix_time_from_system()
+
+	# Timestamp should be between time_before and time_after
+	var timestamp: SentryTimestamp = crumb.get_timestamp()
+	assert_object(timestamp).is_not_null()
+	var micros: int = timestamp.microseconds_since_unix_epoch
+	var timestamp_unix: float = float(micros) / 1_000_000.0
+	assert_float(timestamp_unix).is_greater_equal(time_before)
+	assert_float(timestamp_unix).is_less_equal(time_after)

project/test/suites/test_breadcrumb.gd.uid

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

project/views/enrich_events.gd

@@ -13,7 +13,9 @@ func _ready() -> void:
 
 
 func _on_add_breadcrumb_button_pressed() -> void:
-	SentrySDK.add_breadcrumb(breadcrumb_message.text, breadcrumb_category.text, SentrySDK.LEVEL_ERROR, "default")
+	var crumb := SentryBreadcrumb.create(breadcrumb_message.text)
+	crumb.category = breadcrumb_category.text
+	SentrySDK.add_breadcrumb(crumb)
 	DemoOutput.print_info("Breadcrumb added.")
 
 

src/register_types.cpp

@@ -6,6 +6,7 @@
 #include "sentry/processing/view_hierarchy_processor.h"
 #include "sentry/runtime_config.h"
 #include "sentry/sentry_attachment.h"
+#include "sentry/sentry_breadcrumb.h"
 #include "sentry/sentry_configuration.h"
 #include "sentry/sentry_event.h"
 #include "sentry/sentry_logger.h"
@@ -18,15 +19,18 @@
 #include <godot_cpp/classes/window.hpp>
 
 #ifdef SDK_NATIVE
+#include "sentry/native/native_breadcrumb.h"
 #include "sentry/native/native_event.h"
 #endif // SDK_NATIVE
 
 #ifdef SDK_ANDROID
+#include "sentry/android/android_breadcrumb.h"
 #include "sentry/android/android_event.h"
 #include "sentry/android/android_sdk.h"
 #endif // SDK_ANDROID
 
 #ifdef SDK_COCOA
+#include "sentry/cocoa/cocoa_breadcrumb.h"
 #include "sentry/cocoa/cocoa_event.h"
 #endif // SDK_COCOA
 
@@ -49,6 +53,7 @@ void register_runtime_classes() {
 	GDREGISTER_CLASS(SentrySDK);
 	GDREGISTER_ABSTRACT_CLASS(SentryAttachment);
 	GDREGISTER_ABSTRACT_CLASS(SentryEvent);
+	GDREGISTER_ABSTRACT_CLASS(SentryBreadcrumb);
 	GDREGISTER_INTERNAL_CLASS(DisabledEvent);
 	GDREGISTER_INTERNAL_CLASS(SentryEventProcessor);
 	GDREGISTER_INTERNAL_CLASS(ScreenshotProcessor);
@@ -57,15 +62,18 @@ void register_runtime_classes() {
 
 #ifdef SDK_NATIVE
 	GDREGISTER_INTERNAL_CLASS(native::NativeEvent);
+	GDREGISTER_INTERNAL_CLASS(native::NativeBreadcrumb);
 #endif
 
 #ifdef SDK_ANDROID
 	GDREGISTER_INTERNAL_CLASS(android::AndroidEvent);
+	GDREGISTER_INTERNAL_CLASS(android::AndroidBreadcrumb);
 	GDREGISTER_INTERNAL_CLASS(android::SentryAndroidBeforeSendHandler);
 #endif
 
 #ifdef SDK_COCOA
 	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaEvent);
+	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaBreadcrumb);
 #endif
 }