feat(apple): Integrate SentryObjC framework and add metrics support

CHANGELOG.md

@@ -21,6 +21,8 @@
 
 - *Experimental*: C#/.NET support (started in `2.0.0-beta.0`)
   - Add `options.Native.SetBeforeSend` hook to inspect, modify, or drop native events (engine, GDScript, and GDExtension errors) from the .NET layer ([#737](https://github.com/getsentry/sentry-godot/pull/737))
+- Metrics are now generally available and supported on all platforms ([#755](https://github.com/getsentry/sentry-godot/pull/755))
+  - Moved `enable_metrics` and `before_send_metric` from `SentryOptions.experimental` to `SentryOptions`; the experimental properties remain as deprecated aliases, and existing Project Settings are migrated automatically.
 - Add `SentrySDK.bad_code` API for deliberately crashing the application to test crash reporting and native stack traces ([#765](https://github.com/getsentry/sentry-godot/pull/765))
 
 ### Improvements

doc_classes/SentryExperimental.xml

@@ -10,7 +10,7 @@
 	<tutorials>
 	</tutorials>
 	<members>
-		<member name="before_send_metric" type="Callable" setter="set_before_send_metric" getter="get_before_send_metric" default="Callable()">
+		<member name="before_send_metric" type="Callable" setter="set_before_send_metric" getter="get_before_send_metric" default="Callable()" deprecated="Metrics are now generally available. Use [member SentryOptions.before_send_metric] instead.">
 			If assigned, this callback will be called before sending a metric to Sentry. It can be used to modify the metric or prevent it from being sent.
 			[codeblock]
 			func _before_send_metric(metric: SentryMetric) -&gt; SentryMetric:
@@ -22,7 +22,7 @@
 				return metric
 			[/codeblock]
 		</member>
-		<member name="enable_metrics" type="bool" setter="set_enable_metrics" getter="get_enable_metrics" default="true">
+		<member name="enable_metrics" type="bool" setter="set_enable_metrics" getter="get_enable_metrics" default="true" deprecated="Metrics are now generally available. Use [member SentryOptions.enable_metrics] instead.">
 			Enables Sentry metrics functionality. When enabled, you can emit custom metrics using the [SentryMetrics] API available through [member SentrySDK.metrics].
 		</member>
 	</members>

doc_classes/SentryMetric.xml

@@ -4,7 +4,7 @@
 		Metric item in Sentry.
 	</brief_description>
 	<description>
-		[SentryMetric] represents a single metric data point in Sentry Metrics. Metric objects are passed to the [member SentryExperimental.before_send_metric] callback, where they can be inspected, modified, or discarded before being sent to Sentry.
+		[SentryMetric] represents a single metric data point in Sentry Metrics. Metric objects are passed to the [member SentryOptions.before_send_metric] callback, where they can be inspected, modified, or discarded before being sent to Sentry.
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/SentryMetrics.xml

@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		A dedicated API for emitting metrics to Sentry. Access this API through [member SentrySDK.metrics]. [SentryMetrics] provides methods for emitting different metric types: [method count] for incrementing counters, [method gauge] for tracking point-in-time values, and [method distribution] for recording value distributions.
-		[b]Note:[/b] The [member SentryExperimental.enable_metrics] option in [member SentryOptions.experimental] must be enabled for metrics functionality to work.
+		[b]Note:[/b] The [member SentryOptions.enable_metrics] option must be enabled for metrics functionality to work.
 		[codeblock]
 		# Count occurrences
 		SentrySDK.metrics.count("match_started")
@@ -22,7 +22,6 @@
 		[/codeblock]
 		Structured attributes support [code]bool[/code], [code]int[/code], [code]float[/code], and [code]String[/code] data types. Other types will be converted to strings.
 		You can also set global attributes using [method SentrySDK.set_attribute], which are automatically included in all metric entries.
-		[b]Note:[/b] Metrics are currently not supported on Apple platforms.
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/SentryOptions.xml

@@ -72,6 +72,18 @@
 				return log_entry
 			[/codeblock]
 		</member>
+		<member name="before_send_metric" type="Callable" setter="set_before_send_metric" getter="get_before_send_metric" default="Callable()">
+			If assigned, this callback will be called before sending a metric to Sentry. It can be used to modify the metric or prevent it from being sent.
+			[codeblock]
+			func _before_send_metric(metric: SentryMetric) -&gt; SentryMetric:
+				# Drop debug-only metrics in release builds.
+				if not OS.is_debug_build() and metric.name.begins_with("debug."):
+					return null
+				# Enrich with runtime context.
+				metric.set_attribute("current_scene", get_tree().current_scene.name)
+				return metric
+			[/codeblock]
+		</member>
 		<member name="debug" type="bool" setter="set_debug_enabled" getter="is_debug_enabled" default="true">
 			If [code]true[/code], the SDK will print useful debugging information to standard output. These messages do not appear in the Godot console but can be seen when launching Godot from a terminal.
 			You can control the verbosity using the [member diagnostic_level] option.
@@ -94,6 +106,9 @@
 			See [member godot_logger] for options to capture Godot errors as Sentry events or breadcrumbs.
 			For more information, see [url=https://docs.sentry.io/platforms/godot/logs/]Sentry Logs[/url] documentation.
 		</member>
+		<member name="enable_metrics" type="bool" setter="set_enable_metrics" getter="get_enable_metrics" default="true">
+			Enables Sentry metrics functionality. When enabled, you can emit custom metrics using the [SentryMetrics] API available through [member SentrySDK.metrics].
+		</member>
 		<member name="environment" type="String" setter="set_environment" getter="get_environment" default="&quot;{auto}&quot;">
 			Environments indicate where an error occurred, such as in a release export, headless server, QA build, or another deployment. The SDK automatically detects Godot-specific environments, such as [code]headless_server[/code] and [code]export_release[/code], but you can also assign it in a configuration callback using manual initialization (see [method SentrySDK.init]).
 			This option defaults to [code]{auto}[/code], which automatically detects the environment based on the current runtime context and sets it to one of the following values: [code]editor_dev[/code], [code]editor_dev_run[/code], [code]export_debug[/code], [code]export_release[/code], or [code]dedicated_server[/code].

doc_classes/SentrySDK.xml

@@ -188,7 +188,7 @@
 			See [SentryLogger] for more details.
 		</member>
 		<member name="metrics" type="SentryMetrics" setter="" getter="get_metrics">
-			Provides access to Sentry's metrics API. Use this to emit custom metrics to Sentry when [member SentryExperimental.enable_metrics] is enabled.
+			Provides access to Sentry's metrics API. Use this to emit custom metrics to Sentry when [member SentryOptions.enable_metrics] is enabled.
 			See [SentryMetrics] for more details.
 		</member>
 	</members>

modules/sentry-cocoa.SConscript

@@ -88,8 +88,8 @@ def update_cocoa_framework():
             stored_version = version_file.read_text().strip()
             if stored_version == cocoa_version:
                 # Check if framework actually exists
-                xcframework_path = cocoa_dir / "Sentry-Dynamic.xcframework"
-                headers_path = cocoa_dir / "macos_include" / "Sentry"
+                xcframework_path = cocoa_dir / "SentryObjC-Dynamic.xcframework"
+                headers_path = cocoa_dir / "macos_include" / "SentryObjC"
                 if xcframework_path.exists() and headers_path.exists():
                     should_download = False
                     print(f"Detected Sentry Cocoa SDK v{cocoa_version} – up-to-date!")
@@ -104,8 +104,8 @@ def update_cocoa_framework():
         cocoa_dir.mkdir(parents=True, exist_ok=True)
 
         # Download dynamic framework
-        framework_url = f"{cocoa_repo}/releases/download/{cocoa_version}/Sentry-Dynamic.xcframework.zip"
-        zip_path = cocoa_dir / "Sentry-Dynamic.xcframework.zip"
+        framework_url = f"{cocoa_repo}/releases/download/{cocoa_version}/SentryObjC-Dynamic.xcframework.zip"
+        zip_path = cocoa_dir / "SentryObjC-Dynamic.xcframework.zip"
 
         try:
             print(f"Downloading {framework_url}")
@@ -117,17 +117,17 @@ def update_cocoa_framework():
             zip_path.unlink() # delete file
             version_file.write_text(cocoa_version)
 
-            print(f"Successfully fetched Sentry-Dynamic.xcframework {cocoa_version}.")
+            print(f"Successfully fetched SentryObjC-Dynamic.xcframework {cocoa_version}.")
 
         except Exception as e:
             print(f"ERROR: Failed to download Sentry framework: {e}.")
             Exit(1)
 
         # Prepare headers
         print("Preparing headers for macOS...")
-        headers_dest = cocoa_dir / "macos_include" / "Sentry"
+        headers_dest = cocoa_dir / "macos_include" / "SentryObjC"
         headers_dest.mkdir(parents=True, exist_ok=True)
-        macos_framework = cocoa_dir / "Sentry-Dynamic.xcframework" / "macos-arm64_x86_64" / "Sentry.framework"
+        macos_framework = cocoa_dir / "SentryObjC-Dynamic.xcframework" / "macos-arm64_x86_64" / "SentryObjC.framework"
 
         if macos_framework.exists():
             # Copy Headers
@@ -156,10 +156,10 @@ ios_simulator = env.get("ios_simulator", False)
 # Configuring Cocoa framework.
 if platform in ["macos", "ios"]:
     project_root = Path(env.Dir("#").abspath)
-    xcframework_path = project_root / "modules/sentry-cocoa/Sentry-Dynamic.xcframework"
+    xcframework_path = project_root / "modules/sentry-cocoa/SentryObjC-Dynamic.xcframework"
 
     if not xcframework_path.exists():
-        print(f"ERROR: Sentry-Dynamic.xcframework is missing at {xcframework_path}.")
+        print(f"ERROR: SentryObjC-Dynamic.xcframework is missing at {xcframework_path}.")
         Exit(1)
 
     env.Append(
@@ -173,7 +173,7 @@ if platform in ["macos", "ios"]:
     # Add Sentry Cocoa framework to compilation.
 
     if platform == "macos":
-        framework_dir = xcframework_path / "macos-arm64_x86_64/Sentry.framework"
+        framework_dir = xcframework_path / "macos-arm64_x86_64/SentryObjC.framework"
         env.Append(
             CPPPATH=f"{project_root}/modules/sentry-cocoa/macos_include/",
             LIBPATH=f"{project_root}/project/addons/sentry/bin/macos/",
@@ -185,9 +185,9 @@ if platform in ["macos", "ios"]:
         )
     else:
         if ios_simulator:
-            framework_dir = xcframework_path / "ios-arm64_x86_64-simulator/Sentry.framework"
+            framework_dir = xcframework_path / "ios-arm64_x86_64-simulator/SentryObjC.framework"
         else:
-            framework_dir = xcframework_path / "ios-arm64/Sentry.framework"
+            framework_dir = xcframework_path / "ios-arm64/SentryObjC.framework"
 
         if not framework_dir.exists():
             print(f"ERROR: iOS framework slice is missing at {framework_dir}.")
@@ -198,7 +198,7 @@ if platform in ["macos", "ios"]:
         env.Append(
             CPPFLAGS=["-F" + str(framework_container_dir)],
             LINKFLAGS=[
-                "-framework", "Sentry",
+                "-framework", "SentryObjC",
                 "-F" + str(framework_container_dir),
                 # Allow extension to find framework in addons/sentry/ directory.
                 "-Wl,-rpath,@loader_path/..",
@@ -373,7 +373,7 @@ def DeploySentryCocoa(self, target_dir):
 
     platform = env["platform"]
     project_root = Path(env.Dir("#").abspath)
-    source_xcframework = project_root / "modules/sentry-cocoa/Sentry-Dynamic.xcframework"
+    source_xcframework = project_root / "modules/sentry-cocoa/SentryObjC-Dynamic.xcframework"
     target_dir_path = Path(str(target_dir))
 
     commands = []
@@ -396,20 +396,20 @@ def DeploySentryCocoa(self, target_dir):
         # Debug symbols
         commands.append(
             env.Copy(
-                Dir(target_dir_path / "dSYMs" / "Sentry-ios-arm64.framework.dSYM"),
-                Dir(source_xcframework / "ios-arm64" / "dSYMs" / "Sentry.framework.dSYM"),
+                Dir(target_dir_path / "dSYMs" / "SentryObjC-ios-arm64.framework.dSYM"),
+                Dir(source_xcframework / "ios-arm64" / "dSYMs" / "SentryObjC.framework.dSYM"),
             )
         )
 
         commands.append(
             env.Copy(
-                Dir(target_dir_path / "dSYMs" / "Sentry-ios-arm64_x86_64-simulator.framework.dSYM"),
-                Dir(source_xcframework / "ios-arm64_x86_64-simulator" / "dSYMs" / "Sentry.framework.dSYM")
+                Dir(target_dir_path / "dSYMs" / "SentryObjC-ios-arm64_x86_64-simulator.framework.dSYM"),
+                Dir(source_xcframework / "ios-arm64_x86_64-simulator" / "dSYMs" / "SentryObjC.framework.dSYM")
             )
         )
 
     elif platform == "macos":
-        source_framework = source_xcframework / "macos-arm64_x86_64/Sentry.framework"
+        source_framework = source_xcframework / "macos-arm64_x86_64/SentryObjC.framework"
 
         def patch_install_name_action(target, source, env):
             """Patch install name after copy"""
@@ -433,7 +433,7 @@ def DeploySentryCocoa(self, target_dir):
         commands.append(
             env.Command(
                 File(lib_path),
-                File(source_framework / "Versions/A/Sentry"),
+                File(source_framework / "Versions/A/SentryObjC"),
                 [
                     Copy("$TARGET", "$SOURCE"),
                     patch_install_name_action
@@ -445,7 +445,7 @@ def DeploySentryCocoa(self, target_dir):
         commands.append(
             env.Copy(
                 Dir(target_dir_path / "dSYMs" / "libSentry.dylib.dSYM"),
-                Dir(source_xcframework / "macos-arm64_x86_64" / "dSYMs" / "Sentry.framework.dSYM")
+                Dir(source_xcframework / "macos-arm64_x86_64" / "dSYMs" / "SentryObjC.framework.dSYM")
             )
         )
 

project/cli/cli_commands.gd

@@ -204,8 +204,8 @@ func _before_send_log(entry: SentryLog) -> SentryLog:
 ## Captures counter, distribution, and gauge metrics to Sentry.
 func _cmd_metric_capture() -> int:
 	await _init_sentry(func(options: SentryOptions) -> void:
-		options.experimental.enable_metrics = true
-		options.experimental.before_send_metric = _before_send_metric
+		options.enable_metrics = true
+		options.before_send_metric = _before_send_metric
 	)
 	_add_integration_test_context("metric-capture")
 

project/project_main_loop.gd

@@ -30,7 +30,7 @@ func _initialize() -> void:
 		# Set up event callbacks
 		options.before_send = _on_before_send_to_sentry
 		options.before_send_log = _on_before_send_log_to_sentry
-		options.experimental.before_send_metric = _on_before_send_metric_to_sentry
+		options.before_send_metric = _on_before_send_metric_to_sentry
 	)
 
 	# Post-initialize

project/test/isolated/test_metrics.gd

@@ -5,7 +5,7 @@ signal metric_processed(metric: SentryMetric)
 var _discard_metric: bool = false
 
 
-func before(_do_skip := OS.get_name() in ["macOS", "iOS"], _skip_reason := "Metrics are not supported on Apple platforms") -> void:
+func before() -> void:
 	super()
 
 
@@ -16,8 +16,8 @@ func after() -> void:
 
 func init_sdk() -> void:
 	SentrySDK.init(func(options: SentryOptions) -> void:
-		options.experimental.enable_metrics = true
-		options.experimental.before_send_metric = _before_send_metric
+		options.enable_metrics = true
+		options.before_send_metric = _before_send_metric
 	)
 
 

src/register_types.cpp

@@ -45,6 +45,7 @@
 #include "sentry/cocoa/cocoa_breadcrumb.h"
 #include "sentry/cocoa/cocoa_event.h"
 #include "sentry/cocoa/cocoa_log.h"
+#include "sentry/cocoa/cocoa_metric.h"
 #endif // SDK_COCOA
 
 #ifdef SDK_JAVASCRIPT
@@ -122,6 +123,7 @@ void register_runtime_classes() {
 	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaEvent);
 	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaBreadcrumb);
 	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaLog);
+	GDREGISTER_INTERNAL_CLASS(cocoa::CocoaMetric);
 #endif
 
 #ifdef SDK_JAVASCRIPT

src/sentry/android/android_sdk.cpp

@@ -32,8 +32,8 @@ Dictionary _sanitize_attributes(const Dictionary &p_attributes) {
 	if (!p_attributes.is_empty()) {
 		const Array &keys = p_attributes.keys();
 		for (int i = 0; i < keys.size(); i++) {
-			const String &key = keys[i];
-			attributes[key] = _as_attribute(p_attributes[key]);
+			const Variant &key = keys[i];
+			attributes[key.stringify()] = _as_attribute(p_attributes[key]);
 		}
 	}
 	return attributes;
@@ -349,7 +349,7 @@ void AndroidSDK::init() {
 	optionsData["sample_rate"] = SENTRY_OPTIONS()->get_sample_rate();
 	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["enable_metrics"] = SENTRY_OPTIONS()->get_enable_metrics();
 	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();
@@ -359,7 +359,7 @@ void AndroidSDK::init() {
 			optionsData,
 			before_send_handler->get_instance_id(),
 			SENTRY_OPTIONS()->get_before_send_log().is_valid() ? before_send_log_handler->get_instance_id() : 0,
-			SENTRY_OPTIONS()->get_experimental()->get_before_send_metric().is_valid() ? before_send_metric_handler->get_instance_id() : 0);
+			SENTRY_OPTIONS()->get_before_send_metric().is_valid() ? before_send_metric_handler->get_instance_id() : 0);
 
 	if (is_enabled()) {
 		set_user(SentryUser::create_default());

src/sentry/cocoa/cocoa_breadcrumb.h

@@ -9,13 +9,13 @@ class CocoaBreadcrumb : public SentryBreadcrumb {
 	GDCLASS(CocoaBreadcrumb, SentryBreadcrumb);
 
 private:
-	objc::SentryBreadcrumb *cocoa_breadcrumb = nullptr;
+	SentryObjCBreadcrumb *cocoa_breadcrumb = nullptr;
 
 protected:
 	static void _bind_methods() {}
 
 public:
-	_FORCE_INLINE_ objc::SentryBreadcrumb *get_cocoa_breadcrumb() const { return cocoa_breadcrumb; }
+	_FORCE_INLINE_ SentryObjCBreadcrumb *get_cocoa_breadcrumb() const { return cocoa_breadcrumb; }
 
 	virtual void set_message(const String &p_message) override;
 	virtual String get_message() const override;
@@ -34,7 +34,7 @@ class CocoaBreadcrumb : public SentryBreadcrumb {
 	virtual Ref<SentryTimestamp> get_timestamp() override;
 
 	CocoaBreadcrumb();
-	CocoaBreadcrumb(objc::SentryBreadcrumb *p_cocoa_breadcrumb);
+	CocoaBreadcrumb(SentryObjCBreadcrumb *p_cocoa_breadcrumb);
 };
 
 } //namespace sentry::cocoa

src/sentry/cocoa/cocoa_breadcrumb.mm

@@ -51,13 +51,13 @@
 }
 
 CocoaBreadcrumb::CocoaBreadcrumb() :
-		cocoa_breadcrumb([[objc::SentryBreadcrumb alloc] init]) {
+		cocoa_breadcrumb([[SentryObjCBreadcrumb alloc] init]) {
 }
 
-CocoaBreadcrumb::CocoaBreadcrumb(objc::SentryBreadcrumb *p_cocoa_breadcrumb) :
+CocoaBreadcrumb::CocoaBreadcrumb(SentryObjCBreadcrumb *p_cocoa_breadcrumb) :
 		cocoa_breadcrumb(p_cocoa_breadcrumb) {
 	if (!p_cocoa_breadcrumb) {
-		cocoa_breadcrumb = [[objc::SentryBreadcrumb alloc] init];
+		cocoa_breadcrumb = [[SentryObjCBreadcrumb alloc] init];
 		ERR_PRINT_ONCE("Sentry: Internal error - cocoa breadcrumb instance is null");
 	}
 }

src/sentry/cocoa/cocoa_debug_images.mm

@@ -2,6 +2,30 @@
 
 #include "cocoa_includes.h"
 
+// WORKAROUND: The SentryObjC SDK has no public or internal API to look up binary images by address,
+// which we need to symbolicate .NET exceptions.
+// The types that do this are still inside the framework binary, just not declared in any header.
+// We redeclare the few bits we call here so the code compiles and links against them.
+// Remove once the SDK exposes an official API.
+// Upstream issue: https://github.com/getsentry/sentry-cocoa/issues/8039
+
+@interface SentryBinaryImageInfo : NSObject
+@property(nonatomic, readonly) NSString *name;
+@property(nonatomic, readonly) NSString *uuid;
+@property(nonatomic, readonly) uint64_t address;
+@property(nonatomic, readonly) uint64_t size;
+@end
+
+@interface SentryBinaryImageCache : NSObject
+- (SentryBinaryImageInfo *)imageByAddress:(uint64_t)address;
+@end
+
+@interface SentryDependencies : NSObject
+@property(class, nonatomic, readonly) SentryBinaryImageCache *binaryImageCache;
+@end
+
+// END OF WORKAROUND
+
 namespace sentry::cocoa {
 
 Vector<DebugImage> get_debug_images(const int64_t *p_addresses, int32_t p_addresses_count) {