feat: defer UIViewController swizzling to first init (#8687)

Adds the experimental option enableUIViewControllerInitSwizzling (off by default). Instead of scanning the app's binary images at SDK start and swizzling every UIViewController subclass found, the SDK swizzles each subclass the first time an instance of it is created.

Author: philipphofmann

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add experimental option `enableUIViewControllerInitSwizzling` that defers `UIViewController` swizzling to first instantiation instead of eagerly discovering and swizzling all subclasses at SDK start. This avoids realizing `@available`-gated `UIViewController` subclasses on OS versions below their gate, which crashes apps on start (#8687).
+
 ## 9.25.0
 
 > [!WARNING]

Samples/SentrySampleShared/SentrySampleShared/SentrySDKOverrides.swift

@@ -196,6 +196,7 @@ public enum SentrySDKOverrides: String, CaseIterable {
 
     public enum UIViewControllerTracing: String, SentrySDKOverride {
         case disable = "--io.sentry.uiviewcontroller-tracing.disable"
+        case enableInitSwizzling = "--io.sentry.uiviewcontroller-tracing.init-swizzling"
     }
     case uiViewControllerTracing = "UIViewController Tracing"
 
@@ -512,7 +513,7 @@ extension SentrySDKOverrides.UIEventTracking {
 extension SentrySDKOverrides.UIViewControllerTracing {
     public var overrideType: OverrideType {
         switch self {
-        case .disable: return .boolean
+        case .disable, .enableInitSwizzling: return .boolean
         }
     }
 }
@@ -761,7 +762,12 @@ extension SentrySDKOverrides.UIEventTracking {
 }
 
 extension SentrySDKOverrides.UIViewControllerTracing {
-    public var ignoresDisableEverything: Bool { return false }
+    public var ignoresDisableEverything: Bool {
+        switch self {
+        case .disable: return false
+        case .enableInitSwizzling: return true
+        }
+    }
 }
 
 extension SentrySDKOverrides.FileIO {

Samples/SentrySampleShared/SentrySampleShared/SentrySDKWrapper.swift

@@ -203,6 +203,7 @@ public struct SentrySDKWrapper {
         options.enablePreWarmedAppStartTracing = !isBenchmarking && !SentrySDKOverrides.AppStart.disablePrewarmedTracing.boolValue
         options.experimental.enableStandaloneAppStartTracing = SentrySDKOverrides.AppStart.enableStandaloneTracing.boolValue
         options.enableUIViewControllerTracing = !SentrySDKOverrides.UIViewControllerTracing.disable.boolValue
+        options.experimental.enableUIViewControllerInitSwizzling = SentrySDKOverrides.UIViewControllerTracing.enableInitSwizzling.boolValue
 
         // -- Screenshot Options --
         options.attachScreenshot = !SentrySDKOverrides.Screenshot.disableAttachment.boolValue

Samples/iOS-Swift/App/Sources/AppDelegate.swift

@@ -34,14 +34,11 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
         SentrySDKWrapper.spanCaptureHandler = { LaunchVCTransactionCapture.shared.capture($0) }
 
-        // Without these excludes the sample cannot launch below iOS 17: the SDK crashes on the
-        // gated fixtures in SubClassFinderRegressionViewController. Remove them to reproduce
-        // GH-8152.
-        SentrySDKWrapper.swizzleClassNameExcludes = [
-            "GatedIOS17ViewController",
-            "GatedIOS26OnlyViewController",
-            "GatedObsoletedOnIOS26ViewController"
-        ]
+        // Required: this sample has @available-gated UIViewController subclasses that would crash
+        // at launch without deferred swizzling. Also acts as a safety gate for the feature itself,
+        // since this sample's UI tests cover automatic transactions/instrumentation. (GH-8548)
+        var enableInitSwizzling = SentrySDKOverrides.UIViewControllerTracing.enableInitSwizzling
+        enableInitSwizzling.boolValue = true
 
         SentrySDKWrapper.shared.startSentry()
 

Sources/Sentry/SentryUIViewControllerSwizzlingHelper.m

@@ -2,6 +2,7 @@
 
 #if SENTRY_HAS_UIKIT
 
+#    import "SentryInternalDefines.h"
 #    import "SentrySwift.h"
 #    import "SentrySwizzle.h"
 #    import <UIKit/UIKit.h>
@@ -10,6 +11,10 @@
 @implementation SentryUIViewControllerSwizzlingHelper
 
 static __weak SentryUIViewControllerPerformanceTracker *_tracker = nil;
+
+// Weak, like _tracker: a strong reference here would outlive the caller that installed the funnel.
+static __weak id<SentryUIViewControllerInitSwizzlingDelegate> _initSwizzlingDelegate = nil;
+
 #    if SENTRY_TEST || SENTRY_TEST_CI
 static BOOL swizzlingIsActive = FALSE;
 #    endif
@@ -21,6 +26,9 @@ @implementation SentryUIViewControllerSwizzlingHelper
 
 + (void)swizzleUIViewControllerWithTracker:(SentryUIViewControllerPerformanceTracker *)tracker
 {
+    SENTRY_ASSERT([NSThread isMainThread],
+        @"swizzleUIViewControllerWithTracker: must be called on the main thread.");
+
     _tracker = tracker;
 #    if SENTRY_TEST || SENTRY_TEST_CI
     swizzlingIsActive = TRUE;
@@ -39,8 +47,96 @@ + (void)swizzleUIViewControllerWithTracker:(SentryUIViewControllerPerformanceTra
         SentrySwizzleModeOncePerClassAndSuperclasses, (void *)selector);
 }
 
+/**
+ * Swizzles the two base @c UIViewController designated initializers and notifies @c delegate after
+ * each one, so the caller can defer its own swizzling to first instantiation.
+ *
+ * Every @c UIViewController is created through one of the two: a subclass's designated init calls
+ * super, a convenience init routes through a designated init, and @c -init routes through
+ * @c initWithNibName:bundle:.
+ *
+ * The initializers are swizzled only on the base class, so that part REPLACES UIKit's own
+ * implementation rather than adding a method. That does not mean the funnel only mutates the base
+ * class: the handler runs @c swizzleViewControllerSubClass: on the concrete subclass, and
+ * @c class_replaceMethod ADDS a lifecycle method when the subclass doesn't implement one — while
+ * still inside the outermost initializer frame. That is the same mechanism GH-1361 blamed for the
+ * GH-1355 convenience-initializer crash, so this funnel does not eliminate the condition. We tried
+ * to reproduce GH-1355 on simulators and on real iOS 15 devices in SauceLabs (#8667) and could not.
+ * The option therefore ships opt-in and off by default, so we can validate the approach in the wild
+ * — see PR #8687's description.
+ *
+ * Ordering inside the replacement is load-bearing:
+ *   1. Call the original initializer FIRST, and never touch @c self before it. The pre-GH-1361
+ *      code messaged @c self and mutated the class before the original ran.
+ *   2. Read the concrete class from the RETURNED object via @c object_getClass, a C runtime call
+ *      rather than a message. This handles an init returning a different instance, or nil.
+ *   3. Invoke the handler synchronously, so lifecycle methods are swizzled before the instance
+ *      can reach its first @c viewDidLoad.
+ *   4. Return the result verbatim, adding no retain, so ARC's return handshake stays balanced.
+ *
+ * Step 3 must not hop through @c dispatch_async(dispatch_get_main_queue(), …) to escape the
+ * initializer frame. UIKit calls initializers on the main thread, so a dispatch from the main
+ * thread cannot run until the current run loop turn finishes — by which point the caller already
+ * holds a fully initialized instance and may have driven it into @c viewDidLoad, or released it.
+ * That opens a window where a live view controller is uninstrumented, and it reorders the swizzle
+ * against that instance's own first lifecycle callbacks, so the first appearance of a screen is
+ * silently missed. Swizzling synchronously keeps the mutation ordered against the very first
+ * callback. It is also why everything here is main-thread-only and unlocked: the delegate hand-off
+ * happens on whichever thread ran the initializer, and swizzling off the main thread would race
+ * both this file's static state and the ObjC runtime mutations in @c swizzleViewControllerSubClass:
+ * (background swizzling already caused GH-1366). The delegate therefore ignores initializers that
+ * run on a background thread rather than locking.
+ *
+ * We use the ObjC @c SentrySwizzleInstanceMethod macro rather than the typed Swift API that
+ * develop-docs/SWIZZLING.md prefers (@c SentryTypedSwizzle, #8524): its object-returning overloads
+ * model +0 autoreleased returns, while an initializer returns +1, which Swift cannot express
+ * through an @c \@convention(block) object return without passing @c Unmanaged across the
+ * boundary. @c SentryNSDataSwizzlingHelper.m uses this same macro path for
+ * @c -[NSData initWithContentsOfFile:options:error:], another +1 initializer. The retain
+ * handshake is covered by @c testInitFunnel_whenViewControllersInstantiated_doesNotOverRetainThem.
+ *
+ * @warning Experimental and opt-in, disabled by default. See GH-8548.
+ */
++ (void)swizzleUIViewControllerInitsWithDelegate:
+    (id<SentryUIViewControllerInitSwizzlingDelegate>)delegate
+{
+    SENTRY_ASSERT([NSThread isMainThread],
+        @"swizzleUIViewControllerInitsWithDelegate: must be called on the main thread.");
+
+    _initSwizzlingDelegate = delegate;
+
+    SEL nibSelector = NSSelectorFromString(@"initWithNibName:bundle:");
+    SentrySwizzleInstanceMethod(UIViewController.class, nibSelector, SentrySWReturnType(id),
+        SentrySWArguments(NSString * nibName, NSBundle * bundle), SentrySWReplacement({
+            id<SentryUIViewControllerInitSwizzlingDelegate> delegate = _initSwizzlingDelegate;
+            id result = SentrySWCallOriginal(nibName, bundle);
+            Class resultClass = object_getClass(result);
+            if (resultClass != Nil) {
+                [delegate viewControllerInitialized:resultClass];
+            }
+            return result;
+        }),
+        SentrySwizzleModeOncePerClassAndSuperclasses, (void *)nibSelector);
+
+    SEL coderSelector = NSSelectorFromString(@"initWithCoder:");
+    SentrySwizzleInstanceMethod(UIViewController.class, coderSelector, SentrySWReturnType(id),
+        SentrySWArguments(NSCoder * coder), SentrySWReplacement({
+            id<SentryUIViewControllerInitSwizzlingDelegate> delegate = _initSwizzlingDelegate;
+            id result = SentrySWCallOriginal(coder);
+            Class resultClass = object_getClass(result);
+            if (resultClass != Nil) {
+                [delegate viewControllerInitialized:resultClass];
+            }
+            return result;
+        }),
+        SentrySwizzleModeOncePerClassAndSuperclasses, (void *)coderSelector);
+}
+
 + (void)swizzleViewControllerSubClass:(Class)class
 {
+    SENTRY_ASSERT([NSThread isMainThread],
+        @"swizzleViewControllerSubClass: must be called on the main thread.");
+
     // This are the five main functions related to UI creation in a view controller.
     // We are swizzling it to track anything that happens inside one of this functions.
     [self swizzleViewLayoutSubViews:class];
@@ -174,7 +270,10 @@ + (void)swizzleViewLayoutSubViews:(Class)class
 
 + (void)stop
 {
+    SENTRY_ASSERT([NSThread isMainThread], @"stop must be called on the main thread.");
+
     _tracker = nil;
+    _initSwizzlingDelegate = nil;
 #    if SENTRY_TEST || SENTRY_TEST_CI
     [self unswizzle];
 #    endif
@@ -183,16 +282,25 @@ + (void)stop
 #    if SENTRY_TEST || SENTRY_TEST_CI
 + (void)unswizzle
 {
+    SENTRY_ASSERT([NSThread isMainThread], @"unswizzle must be called on the main thread.");
+
     swizzlingIsActive = FALSE;
 
     // Unswizzling is only supported in test targets as it is considered unsafe for production.
-    // Only unswizzle the base UIViewController.loadView since that's the only method swizzled
-    // on the base class. Other lifecycle methods are swizzled per-subclass and we don't track
-    // which subclasses were swizzled, so we can't safely unswizzle them.
-    // The stop method sets _tracker = nil which makes all swizzled methods no-ops anyway.
+    // Restores everything swizzled on the base UIViewController: loadView and the two init funnel
+    // initializers. Leaving the funnel installed would leak it into every later test suite in the
+    // same run, because a live base-class IMP outlives the handler that stop clears. Lifecycle
+    // methods are swizzled per-subclass and we don't track which subclasses were swizzled, but
+    // those are harmless because stop sets _tracker to nil, making them pass-throughs.
     SEL loadViewSelector = NSSelectorFromString(@"loadView");
     SentryUnswizzleInstanceMethod(
         UIViewController.class, loadViewSelector, (void *)loadViewSelector);
+
+    SEL nibSelector = NSSelectorFromString(@"initWithNibName:bundle:");
+    SentryUnswizzleInstanceMethod(UIViewController.class, nibSelector, (void *)nibSelector);
+
+    SEL coderSelector = NSSelectorFromString(@"initWithCoder:");
+    SentryUnswizzleInstanceMethod(UIViewController.class, coderSelector, (void *)coderSelector);
 }
 
 + (BOOL)swizzlingActive

Sources/Sentry/include/SentryUIViewControllerSwizzlingHelper.h

@@ -5,8 +5,13 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- * Helper class that performs the actual method swizzling for UIViewController tracking.
- * This class is used by the Swift SentryUIViewControllerSwizzling class.
+ * Performs the method swizzling for UIViewController tracking on behalf of the Swift
+ * SentryUIViewControllerSwizzling class.
+ *
+ * @warning Main thread only, and deliberately unsynchronized. Everything here swizzles
+ * @c UIViewController lifecycle and initializer methods, which UIKit only calls on the main thread,
+ * so the shared state below needs no locking. Calling any of this from a background thread races
+ * that state and the ObjC runtime mutations.
  */
 @interface SentryUIViewControllerSwizzlingHelper : NSObject
 
@@ -23,6 +28,19 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (void)swizzleViewControllerSubClass:(Class)class;
 
+/**
+ * Swizzles the base @c UIViewController designated initializers and notifies @c delegate after each
+ * one, so the caller can defer its own swizzling to first instantiation. Deferring avoids realizing
+ * @c \@available -gated subclasses below their gate: a class is only reached once an instance
+ * exists, which means the OS already realized it safely.
+ *
+ * @warning Experimental. Only installed when
+ * @c options.experimental.enableUIViewControllerInitSwizzling is enabled, which is off by default.
+ * See GH-8548.
+ */
++ (void)swizzleUIViewControllerInitsWithDelegate:
+    (SENTRY_SWIFT_MIGRATION_ID(SentryUIViewControllerInitSwizzlingDelegate))delegate;
+
 + (void)stop;
 
 #    if SENTRY_TEST || SENTRY_TEST_CI

Sources/SentryObjC/Public/SentryObjCExperimentalOptions.h

@@ -21,6 +21,27 @@ NS_ASSUME_NONNULL_BEGIN
 /// When enabled, the SDK uses a more efficient mechanism for detecting watchdog terminations.
 @property (nonatomic) BOOL enableWatchdogTerminationsV2;
 
+/**
+ * Reduces SDK start overhead by swizzling each @c UIViewController subclass lazily, the first time
+ * an instance of it is created, instead of eagerly discovering and swizzling every subclass when
+ * the SDK starts.
+ *
+ * By default, the SDK scans loaded binary images for all @c UIViewController subclasses at start
+ * and swizzles them up front. This realizes every subclass to inspect it, so the cost grows with
+ * the number of view controllers in the app - including ones it never uses - and it realizes
+ * @c \@available -gated subclasses that reference newer-framework types, which crashes on OS
+ * versions below the gate.
+ *
+ * With this option, only classes the app actually instantiates are touched: a class that can't
+ * exist on the current OS is never instantiated, so it's never realized or swizzled. This cuts
+ * start-up work and avoids the gated-subclass crash while producing the same @c ui.load
+ * auto-instrumentation transactions.
+ *
+ * @warning This is an experimental feature and is therefore disabled by default.
+ * @see https://github.com/getsentry/sentry-cocoa/issues/8548
+ */
+@property (nonatomic) BOOL enableUIViewControllerInitSwizzling;
+
 /// Initializes experimental options with default values.
 - (instancetype)init;
 

Sources/SentryObjCCompat/SentryObjCExperimentalOptions.swift

@@ -26,6 +26,11 @@ import Foundation
         get { wrapped.enableWatchdogTerminationsV2 }
         set { wrapped.enableWatchdogTerminationsV2 = newValue }
     }
+
+    @objc public var enableUIViewControllerInitSwizzling: Bool {
+        get { wrapped.enableUIViewControllerInitSwizzling }
+        set { wrapped.enableUIViewControllerInitSwizzling = newValue }
+    }
 }
 
 // swiftlint:enable missing_docs