itaybre · Oct 23, 2026
@@ -5,6 +5,7 @@
 ### Features
 
 - Add `options.experimental.metrickit.enabledDiagnosticReports` to choose which MetricKit diagnostic reports the SDK captures, including crash diagnostics. The option is only available from Swift (#9267)
+- Capture MetricKit app launch diagnostics on iOS 16 and later and on visionOS when `options.experimental.metrickit.enabledDiagnosticReports` contains `.appLaunch` (#9441)
 
 ## 9.31.0
 

@@ -51,6 +51,7 @@
 
 - Move session replay and screenshot masking and subtree traversal settings to `options.privacy`. Rendering settings remain on `sessionReplay` and `screenshot` (#9399).
 - Remove `enableMetricKit`; the MetricKit integration is enabled by default and `options.experimental.metrickit.enabledDiagnosticReports` set to an empty set disables it (#9267)
+- Capture MetricKit app launch diagnostics by default (#9441)
 
 ### Fixes
 

@@ -99,6 +99,14 @@ extension SentryMXManager: MXMetricManagerSubscriber {
                     process(hangDiagnostic: diagnostic, timestamp: payload.timeStampBegin)
                 }
             }
+            #if os(iOS) || os(visionOS)
+            if #available(iOS 16.0, *), let diagnostics = payload.appLaunchDiagnostics {
+                SentrySDKLog.info("Received \(diagnostics.count) MetricKit app launch diagnostics")
+                diagnostics.forEach { diagnostic in
+                    process(appLaunchDiagnostic: diagnostic, timestamp: payload.timeStampBegin)
+                }
+            }
+            #endif // os(iOS) || os(visionOS)
         }
     }
 
@@ -181,6 +189,27 @@ extension SentryMXManager: MXMetricManagerSubscriber {
         )
     }
 
+    #if os(iOS) || os(visionOS)
+    @available(iOS 16.0, *)
+    private func process(appLaunchDiagnostic diagnostic: MXAppLaunchDiagnostic, timestamp: Date) {
+        guard enabledDiagnostics.contains(.appLaunch) else {
+            SentrySDKLog.debug("App launch diagnostics are not enabled, skipping payload")
+            return
+        }
+        SentrySDKLog.debug("Processing app launch diagnostic at timestamp: \(timestamp)")
+
+        let launchDuration = measurementFormatter.string(from: diagnostic.launchDuration)
+
+        captureEvent(
+            handled: true,
+            diagnosticReport: .appLaunch,
+            exceptionValue: "MXAppLaunchDiagnostic launchDuration:\(launchDuration)",
+            timeStampBegin: timestamp,
+            diagnostic: diagnostic
+        )
+    }
+    #endif // os(iOS) || os(visionOS)
+
     private func captureEvent(
         handled: Bool,
         diagnosticReport: Diagnostic,

@@ -11,4 +11,8 @@ extension MXCrashDiagnostic: SentryMetricKit.CallStackTreeProviding { }
 extension MXDiskWriteExceptionDiagnostic: SentryMetricKit.CallStackTreeProviding { }
 extension MXCPUExceptionDiagnostic: SentryMetricKit.CallStackTreeProviding { }
 extension MXHangDiagnostic: SentryMetricKit.CallStackTreeProviding { }
+#if os(iOS) || os(visionOS)
+@available(iOS 16.0, *)
+extension MXAppLaunchDiagnostic: SentryMetricKit.CallStackTreeProviding { }
+#endif // os(iOS) || os(visionOS)
 #endif // os(iOS) || os(macOS) || os(visionOS)
@@ -18,6 +18,11 @@ extension SentryMetricKit {
 
         /// A disk write exception, reported by `MXDiskWriteExceptionDiagnostic`.
         case diskWriteException
+
+        /// A slow app launch, reported by `MXAppLaunchDiagnostic`.
+        ///
+        /// - Note: MetricKit only reports app launch diagnostics on iOS 16 and later and on visionOS.
+        case appLaunch
     }
 }
 
@@ -32,6 +37,8 @@ extension SentryMetricKit.DiagnosticReport {
             return "MXCPUException"
         case .hang:
             return "MXHangDiagnostic"
+        case .appLaunch:
+            return "MXAppLaunchDiagnostic"
         }
     }
 
@@ -45,6 +52,8 @@ extension SentryMetricKit.DiagnosticReport {
             return "mx_cpu_exception"
         case .hang:
             return "mx_hang_diagnostic"
+        case .appLaunch:
+            return "mx_app_launch_diagnostic"
         }
     }
 

@@ -15,9 +15,10 @@ public final class SentryMetricKitOptions {
     /// An empty set disables the MetricKit integration.
     ///
     /// - Note: Defaults to ``SentryMetricKit/DiagnosticReport/cpuException``,
-    ///   ``SentryMetricKit/DiagnosticReport/diskWriteException`` and
-    ///   ``SentryMetricKit/DiagnosticReport/hang``.
-    public var enabledDiagnosticReports: Set<SentryMetricKit.DiagnosticReport> = [.cpuException, .diskWriteException, .hang]
+    ///   ``SentryMetricKit/DiagnosticReport/diskWriteException``,
+    ///   ``SentryMetricKit/DiagnosticReport/hang`` and
+    ///   ``SentryMetricKit/DiagnosticReport/appLaunch``.
+    public var enabledDiagnosticReports: Set<SentryMetricKit.DiagnosticReport> = [.cpuException, .diskWriteException, .hang, .appLaunch]
     #else
     /// The MetricKit diagnostic reports the SDK captures as events.
     ///

@@ -238,6 +238,7 @@ public enum SentrySDKOverrides: String, CaseIterable {
     public enum MetricKit: String, SentrySDKOverride {
         case disable = "--io.sentry.metric-kit.disable"
         case disableRawPayloads = "--io.sentry.metric-kit.disable-raw-payloads"
+        case slowLaunch = "--io.sentry.metric-kit.slow-launch"
     }
     case metricKit = "MetricKit"
 
@@ -571,7 +572,7 @@ extension SentrySDKOverrides.Crash {
 extension SentrySDKOverrides.MetricKit {
     public var overrideType: OverrideType {
         switch self {
-        case .disable, .disableRawPayloads: return .boolean
+        case .disable, .disableRawPayloads, .slowLaunch: return .boolean
         }
     }
 }
@@ -795,7 +796,15 @@ extension SentrySDKOverrides.Crash {
 }
 
 extension SentrySDKOverrides.MetricKit {
-    public var ignoresDisableEverything: Bool { return false }
+    public var ignoresDisableEverything: Bool {
+        switch self {
+        case .disable, .disableRawPayloads:
+            return false
+        case .slowLaunch:
+            // Disabling everything must not slow down every launch.
+            return true
+        }
+    }
 }
 
 extension SentrySDKOverrides.Metrics {

@@ -169,7 +169,7 @@
            options.sampleRate = NSNumber(value: sampleRate)
        }
        options.attachAllThreads = SentrySDKOverrides.Events.attachAllThreads.boolValue
        options.beforeSendWithHint = { event, hint in
            guard !SentrySDKOverrides.Events.rejectAll.boolValue else { return nil }
            Self.logHint(hint, callback: "beforeSendWithHint")
            return event
@@ -241,7 +241,10 @@
             options.experimental.metrickit.enabledDiagnosticReports = []
         }
 #else
-        options.enableMetricKit = enableMetricKit
+        if enableMetricKit {
+            // Unlike enableMetricKit, the report set also captures app launch diagnostics.
+            options.experimental.metrickit.enabledDiagnosticReports = [.cpuException, .diskWriteException, .hang, .appLaunch]
+        }
 #endif // SDK_V10
         options.experimental.metrickit.hangReportingMode = .flamegraphAttachment
         options.enableMetricKitRawPayload =
@@ -326,7 +329,7 @@
        options.enableSpotlight = SentrySDKOverrides.Spotlight.enable.boolValue
    #endif // targetEnvironment(simulator)

        options.beforeBreadcrumbWithHint = { breadcrumb, hint in
            NotificationCenter.default.post(name: .init("io.sentry.newbreadcrumb"), object: breadcrumb)
            Self.logHint(hint, callback: "beforeBreadcrumbWithHint")
            return breadcrumb
@@ -376,7 +379,7 @@
            !SentrySDKOverrides.Crash.disableUnhandledCPPExceptionsV2.boolValue
        #endif // SDK_V10
        #if !SDK_V10
        options.experimental.enableWatchdogTerminationsV2 =
            !SentrySDKOverrides.WatchdogTerminations.disableV2.boolValue
        #endif // !SDK_V10
 #if os(macOS) && !SENTRY_NO_UI_FRAMEWORK
@@ -511,27 +514,27 @@

 #if !SDK_V10
    func configureFeedbackWidget(config: SentryUserFeedbackWidgetConfiguration) {
        config.autoInject = false
        config.layoutUIOffset = layoutOffset

        guard !SentrySDKOverrides.Feedback.allDefaults.boolValue else { return }

        if Locale.current.languageCode == "ar" { // arabic
            config.labelText = "﷽"
        } else if Locale.current.languageCode == "ur" { // urdu
            config.labelText = "نستعلیق"
        } else if Locale.current.languageCode == "he" { // hebrew
            config.labelText = "עִבְרִית‎"
        } else if Locale.current.languageCode == "hi" { // Hindi
            config.labelText = "नागरि"
        } else {
            config.labelText = "Report Jank"
        }

        if SentrySDKOverrides.Feedback.noWidgetText.boolValue {
            config.labelText = nil
        }
        config.showIcon = !SentrySDKOverrides.Feedback.noWidgetIcon.boolValue
    }
 #endif // !SDK_V10


@@ -106,6 +106,7 @@ schemeTemplates:
         # metric kit
         "--io.sentry.metric-kit.disable": false
         "--io.sentry.metric-kit.disable-raw-payloads": false
+        "--io.sentry.metric-kit.slow-launch": false
 
         # metrics
         "--io.sentry.metrics.enable": true

@@ -39,7 +39,9 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
         enableInitSwizzling.boolValue = true
 
         SentrySDKWrapper.shared.startSentry()
-
+
+        MetricKitAppLaunchStressor.runIfEnabled()
+
         return true
     }
 

@@ -1,4 +1,5 @@
 import Foundation
+import SentrySampleShared
 import SentrySwift
 import UIKit
 
@@ -32,6 +33,53 @@ final class MetricKitViewController: UIViewController {
     }
 }
 
+/// Slows down every launch while `SentrySDKOverrides.MetricKit.slowLaunch` is on, so MetricKit
+/// reports an `MXAppLaunchDiagnostic`.
+enum MetricKitAppLaunchStressor {
+    private static let duration: TimeInterval = 8
+
+    /// Call during launch, before the first frame is drawn.
+    static func runIfEnabled() {
+        guard SentrySDKOverrides.MetricKit.slowLaunch.boolValue else {
+            return
+        }
+
+        guard let imageData = Bundle.main.url(forResource: "Tongariro", withExtension: "jpg")
+            .flatMap({ try? Data(contentsOf: $0) }) else {
+            SentrySDK.logger.error(
+                "MetricKit app launch stressor image could not be loaded",
+                attributes: ["stressor": "app_launch"]
+            )
+            return
+        }
+
+        SentrySDK.logger.info(
+            "MetricKit app launch stressor started",
+            attributes: [
+                "stressor": "app_launch",
+                "duration_seconds": duration,
+                "workload": "image_decoding"
+            ]
+        )
+
+        let endTime = Date().addingTimeInterval(duration)
+        while Date() < endTime {
+            autoreleasepool {
+                _ = UIImage(data: imageData)?.preparingForDisplay()
+            }
+        }
+
+        SentrySDK.logger.info(
+            "MetricKit app launch stressor completed",
+            attributes: [
+                "stressor": "app_launch",
+                "duration_seconds": duration,
+                "workload": "image_decoding"
+            ]
+        )
+    }
+}
+
 private final class MetricKitCPUStressor {
     private static let duration: TimeInterval = 180
 

@@ -66,6 +66,8 @@ class TestMXDiagnosticPayload: MXDiagnosticPayload {
         var cpuDiagnostic: [MXCPUExceptionDiagnostic]?
         var diskWriteDiagnostic: [MXDiskWriteExceptionDiagnostic]?
         var hangDiagnostic: [MXHangDiagnostic]?
+        // MXAppLaunchDiagnostic needs iOS 16, which is newer than the test deployment target.
+        var appLaunchDiagnostics: [MXDiagnostic]?
 
         var timeStampBegin = SentryDependencyContainer.sharedInstance().dateProvider.date()
     }
@@ -87,6 +89,13 @@ class TestMXDiagnosticPayload: MXDiagnosticPayload {
     override var hangDiagnostics: [MXHangDiagnostic]? {
         return overrides.hangDiagnostic
     }
+
+#if os(iOS) || os(visionOS)
+    @available(iOS 16.0, *)
+    override var appLaunchDiagnostics: [MXAppLaunchDiagnostic]? {
+        return overrides.appLaunchDiagnostics as? [MXAppLaunchDiagnostic]
+    }
+#endif // os(iOS) || os(visionOS)
 
     override var timeStampBegin: Date {
         return overrides.timeStampBegin

@@ -20,6 +20,10 @@ final class SentryMetricKitEventTests: XCTestCase {
     func testMXHangDiagnostic_IsMetricKitEvent() {
         XCTAssertTrue(createMetricKitEventWith(mechanismType: "mx_hang_diagnostic").isMetricKitEvent())
     }
+
+    func testIsMetricKitEvent_whenAppLaunchDiagnostic_shouldReturnTrue() {
+        XCTAssertTrue(createMetricKitEventWith(mechanismType: "mx_app_launch_diagnostic").isMetricKitEvent())
+    }
 
 #if os(iOS) || os(tvOS) || os(visionOS)
     func testWatchDogEvent_IsNotMetricKitEvent() {

@@ -95,7 +95,7 @@ final class SentryMetricKitIntegrationInitTests: XCTestCase {
 
         // -- Assert --
 #if SDK_V10
-        XCTAssertEqual(try XCTUnwrap(sut).mxManager.enabledDiagnostics, [.cpuException, .diskWriteException, .hang])
+        XCTAssertEqual(try XCTUnwrap(sut).mxManager.enabledDiagnostics, [.cpuException, .diskWriteException, .hang, .appLaunch])
 #else
         XCTAssertNil(sut)
 #endif

@@ -485,6 +485,61 @@ final class SentryMetricKitIntegrationTests: SentrySDKIntegrationTestsBase {
         XCTAssertEqual([.warning, .warning, .error, .error], invocations.map(\.event.level))
     }
 
+#if os(iOS) || os(visionOS)
+    func testDidReceive_whenAppLaunchDiagnosticEnabled_shouldCaptureEvent() throws {
+        guard #available(iOS 16.0, *) else {
+            throw XCTSkip("MXAppLaunchDiagnostic requires iOS 16")
+        }
+
+        // -- Arrange --
+        givenSDKWithHubWithScope()
+        let options = Options()
+        options.experimental.metrickit.enabledDiagnosticReports = [.appLaunch]
+        let sut = try XCTUnwrap(SentryMetricKitIntegration(with: options, dependencies: SentryDependencyContainer.sharedInstance()))
+
+        let payload = TestMXDiagnosticPayload()
+        let callStackTree = TestMXCallStackTree()
+        callStackTree.overrides.jsonRepresentation = try contentsOfResource("MetricKitCallstacks/per-thread")
+        let appLaunchDiagnostic = TestMXAppLaunchDiagnostic()
+        appLaunchDiagnostic.overrides.callStackTree = callStackTree
+        payload.overrides.appLaunchDiagnostics = [appLaunchDiagnostic]
+        payload.overrides.timeStampBegin = timeStampBegin
+
+        // -- Act --
+        sut.mxManager.didReceive([payload])
+
+        // -- Assert --
+        try assertPerThread(exceptionType: "MXAppLaunchDiagnostic", exceptionValue: "MXAppLaunchDiagnostic launchDuration:3.3 sec", exceptionMechanism: "mx_app_launch_diagnostic")
+        let client = try XCTUnwrap(SentrySDKInternal.currentHub().getClient() as? TestClient)
+        XCTAssertEqual(client.captureEventWithScopeInvocations.first?.event.level, .warning)
+    }
+
+    func testDidReceive_whenAppLaunchDiagnosticNotEnabled_shouldNotCaptureEvent() throws {
+        guard #available(iOS 16.0, *) else {
+            throw XCTSkip("MXAppLaunchDiagnostic requires iOS 16")
+        }
+
+        // -- Arrange --
+        givenSDKWithHubWithScope()
+        let options = Options()
+        options.experimental.metrickit.enabledDiagnosticReports = [.hang]
+        let sut = try XCTUnwrap(SentryMetricKitIntegration(with: options, dependencies: SentryDependencyContainer.sharedInstance()))
+
+        let payload = TestMXDiagnosticPayload()
+        let callStackTree = TestMXCallStackTree()
+        callStackTree.overrides.jsonRepresentation = try contentsOfResource("MetricKitCallstacks/per-thread")
+        let appLaunchDiagnostic = TestMXAppLaunchDiagnostic()
+        appLaunchDiagnostic.overrides.callStackTree = callStackTree
+        payload.overrides.appLaunchDiagnostics = [appLaunchDiagnostic]
+
+        // -- Act --
+        sut.mxManager.didReceive([payload])
+
+        // -- Assert --
+        assertNothingCaptured()
+    }
+#endif // os(iOS) || os(visionOS)
+
     private func capturedHintAttachments() throws -> [Attachment] {
         let client = try XCTUnwrap(SentrySDKInternal.currentHub().getClient() as? TestClient)
         XCTAssertEqual(client.captureEventWithScopeAndHintInvocations.count, 1, "Expected exactly one event captured with a hint.")
@@ -695,6 +750,26 @@ class TestMXHangDiagnostic: MXHangDiagnostic {
     }
 }
 
+#if os(iOS) || os(visionOS)
+@available(iOS 16.0, *)
+class TestMXAppLaunchDiagnostic: MXAppLaunchDiagnostic {
+    struct Override {
+        var callStackTree = TestMXCallStackTree()
+        var launchDuration = Measurement(value: 3.3, unit: UnitDuration.seconds)
+    }
+
+    public var overrides = Override()
+
+    override var callStackTree: MXCallStackTree {
+        return overrides.callStackTree
+    }
+
+    override var launchDuration: Measurement<UnitDuration> {
+        return overrides.launchDuration
+    }
+}
+#endif // os(iOS) || os(visionOS)
+
 @available(tvOS, unavailable)
 @available(watchOS, unavailable)
 class TestMXMetaData: MXMetaData {

@@ -876,7 +876,7 @@ final class SentryClientTests: XCTestCase {
             options.attachAllThreads = true
         })
 
-        for mechanism in ["MXCrashDiagnostic", "mx_disk_write_exception", "mx_cpu_exception", "mx_hang_diagnostic"] {
+        for mechanism in ["MXCrashDiagnostic", "mx_disk_write_exception", "mx_cpu_exception", "mx_hang_diagnostic", "mx_app_launch_diagnostic"] {
             let event = Event(level: .warning)
             let exception = Exception(value: "Diagnostic without a decoded call stack", type: "MetricKit")
             exception.mechanism = Mechanism(type: mechanism)

@@ -34,7 +34,7 @@ final class SentryOptionsTests: XCTestCase {
 
         // -- Assert --
 #if SDK_V10
-        XCTAssertEqual(options.experimental.metrickit.enabledDiagnosticReports, [.cpuException, .diskWriteException, .hang])
+        XCTAssertEqual(options.experimental.metrickit.enabledDiagnosticReports, [.cpuException, .diskWriteException, .hang, .appLaunch])
 #else
         XCTAssertTrue(options.experimental.metrickit.enabledDiagnosticReports.isEmpty)
 #endif