From 23ebb6878a93530d1d7db78271dc6fbd2ed33881 Mon Sep 17 00:00:00 2001 From: Alexander Pantiukhov Date: Tue, 17 Nov 2026 16:38:05 +0100 Subject: [PATCH 1/2] feat(ios): Add metricKitHangReportingMode option for MetricKit hang flame graphs sentry-cocoa can attach the aggregated call trees of a MetricKit hang diagnostic as an event.flamegraph attachment, which the backend symbolicates. React Native had no way to turn this on. The new experimental metricKitHangReportingMode option accepts legacy or flamegraphAttachment. React Native passes the options dictionary to the cocoa Options(dictionary:) initializer, which reads metricKitHangReportingMode, so the option needs no native code. It also works when the native SDK starts from sentry.options.json. A Jest test checks that initNativeSdk forwards the option, and Swift tests check that RNSentryStart sets experimental.metrickit.hangReportingMode from it and keeps legacy by default. --- CHANGELOG.md | 15 +++++++++++++++ .../RNSentryStartTests.swift | 17 +++++++++++++++++ packages/core/etc/sentry-react-native.api.md | 1 + packages/core/src/js/options.ts | 18 ++++++++++++++++++ packages/core/test/wrapper.test.ts | 17 +++++++++++++++++ 5 files changed, 68 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ab9e1fa35..e84ca6d789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,21 @@ > make sure you follow our [migration guide](https://docs.sentry.io/platforms/react-native/migration/) first. +## Unreleased + +### Features + +- Report MetricKit hangs on iOS as flame graph attachments with the experimental `metricKitHangReportingMode` option ([#NNNN](https://github.com/getsentry/sentry-react-native/pull/NNNN)) + - With `flamegraphAttachment`, the native SDK attaches the aggregated call trees of a MetricKit hang diagnostic as a flame graph, which the backend symbolicates. The default `legacy` mode reports the flattened call stack tree. + + ```js + Sentry.init({ + dsn: '__DSN__', + enableMetricKit: true, + metricKitHangReportingMode: 'flamegraphAttachment', + }); + ``` + ## 8.36.0 ### Fixes diff --git a/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryStartTests.swift b/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryStartTests.swift index a48974b567..bbda61469c 100644 --- a/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryStartTests.swift +++ b/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryStartTests.swift @@ -24,6 +24,23 @@ final class RNSentryStartTests: XCTestCase { assertReactDefaults(actualOptions) } + func testCreateOptionsSetsMetricKitHangReportingMode() throws { + let options = try RNSentryStart.createOptions(with: [ + "dsn": "https://abcd@efgh.ingest.sentry.io/123456", + "metricKitHangReportingMode": "flamegraphAttachment" + ]) + + XCTAssertEqual(options.experimental.metrickit.hangReportingMode, SentryMetricKitHangReportingMode.flamegraphAttachment) + } + + func testCreateOptionsUsesLegacyMetricKitHangReportingModeByDefault() throws { + let options = try RNSentryStart.createOptions(with: [ + "dsn": "https://abcd@efgh.ingest.sentry.io/123456" + ]) + + XCTAssertEqual(options.experimental.metrickit.hangReportingMode, SentryMetricKitHangReportingMode.legacy) + } + func testAutoStartSetsReactDefaults() throws { try startFromRN(options: [ "dsn": "https://abcd@efgh.ingest.sentry.io/123456" diff --git a/packages/core/etc/sentry-react-native.api.md b/packages/core/etc/sentry-react-native.api.md index 9e90bdfe9f..94b5997230 100644 --- a/packages/core/etc/sentry-react-native.api.md +++ b/packages/core/etc/sentry-react-native.api.md @@ -212,6 +212,7 @@ export interface BaseReactNativeOptions { logsOrigin?: 'all' | 'js' | 'native'; maxCacheItems?: number; maxQueueSize?: number; + metricKitHangReportingMode?: 'legacy' | 'flamegraphAttachment'; ndkAppHangTimeoutIntervalMillis?: number; onNativeLog?: (log: NativeLogEntry) => void; onReady?: (response: { diff --git a/packages/core/src/js/options.ts b/packages/core/src/js/options.ts index a956a3bfd5..7695c04768 100644 --- a/packages/core/src/js/options.ts +++ b/packages/core/src/js/options.ts @@ -396,6 +396,24 @@ export interface BaseReactNativeOptions { */ enableMetricKitRawPayload?: boolean; + /** + * How the native iOS SDK reports MetricKit hang diagnostics. + * + * - `legacy` reports the flattened call stack tree in the event. + * - `flamegraphAttachment` attaches the aggregated call trees as a flame graph, which the + * backend symbolicates. When the SDK cannot create the flame graph, it reports the flattened + * call stack tree. + * + * Only has an effect when `enableMetricKit` is `true`. Other MetricKit diagnostics do not change. + * + * iOS only + * + * @default 'legacy' + * @experimental + * @platform ios + */ + metricKitHangReportingMode?: 'legacy' | 'flamegraphAttachment'; + /** * When enabled, `SentryCrash` reads memory near the crash site while capturing a native crash * (e.g. `EXC_BAD_ACCESS`) and embeds string-based stack contents in the event. This can help diff --git a/packages/core/test/wrapper.test.ts b/packages/core/test/wrapper.test.ts index 24a0b60edf..99eaf5d1ba 100644 --- a/packages/core/test/wrapper.test.ts +++ b/packages/core/test/wrapper.test.ts @@ -316,6 +316,23 @@ describe('Tests Native Wrapper', () => { expect(initParameter.enableMetricKitRawPayload).toBe(true); }); + test('forwards metricKitHangReportingMode to the Native SDK', async () => { + await NATIVE.initNativeSdk({ + dsn: VALID_DSN, + enableNative: true, + autoInitializeNativeSdk: true, + metricKitHangReportingMode: 'flamegraphAttachment', + devServerUrl: undefined, + defaultSidecarUrl: undefined, + mobileReplayOptions: undefined, + }); + + expect(RNSentry.initNativeSdk).toHaveBeenCalled(); + // @ts-expect-error mock value + const initParameter = RNSentry.initNativeSdk.mock.calls[0][0]; + expect(initParameter.metricKitHangReportingMode).toBe('flamegraphAttachment'); + }); + test('forwards enablePreWarmedAppStartTracing to the Native SDK', async () => { await NATIVE.initNativeSdk({ dsn: VALID_DSN, From dfa285d115ebbb1791b024a58ee7acc56874b06f Mon Sep 17 00:00:00 2001 From: Alexander Pantiukhov Date: Tue, 17 Nov 2026 16:38:27 +0100 Subject: [PATCH 2/2] docs(changelog): Link the MetricKit hang flame graph entry to its PR Replace the PR link placeholder in the metricKitHangReportingMode entry with #7059. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e84ca6d789..b889c48b8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ ### Features -- Report MetricKit hangs on iOS as flame graph attachments with the experimental `metricKitHangReportingMode` option ([#NNNN](https://github.com/getsentry/sentry-react-native/pull/NNNN)) +- Report MetricKit hangs on iOS as flame graph attachments with the experimental `metricKitHangReportingMode` option ([#7059](https://github.com/getsentry/sentry-react-native/pull/7059)) - With `flamegraphAttachment`, the native SDK attaches the aggregated call trees of a MetricKit hang diagnostic as a flame graph, which the backend symbolicates. The default `legacy` mode reports the flattened call stack tree. ```js