feat(apple): add manual file I/O tracing and experimental swizzling options (#12999)

Author: philprime

docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx

@@ -39,7 +39,6 @@ If another transaction is already bound to the scope (if it's been set manually,
 
 To disable the `UIViewController` Tracing:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -67,7 +66,6 @@ SentrySDK.start { options in
 
 You can deactivate tracing for specific UIViewControllers by configuring <PlatformLink to="/configuration/swizzling#skip-swizzling-for-specific-classes">`swizzleClassNameExcludes`</PlatformLink>:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -91,7 +89,6 @@ SentrySDK.start { options in
 
 [UIViewController]: https://developer.apple.com/documentation/uikit/uiviewcontroller
 
-
 ## App Start Tracing
 
 This feature is available for iOS, tvOS, and Mac Catalyst.
@@ -141,7 +138,6 @@ You can filter for different app start types in [Discover](/product/explore/disc
 
 To enable prewarmed app start tracing:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -178,7 +174,6 @@ Network Tracking is enabled by default once you <PlatformLink to="/tracing/">set
 
 To disable the HTTP instrumentation:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -207,7 +202,6 @@ Sentry adds an extra header with the trace id in the outgoing HTTP requests to c
 You can set the `tracePropagationTarget` option to filter which requests Sentry adds the extra header to.
 For example, to ensure that only your app backend will receive the trace id.
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -234,8 +228,7 @@ If `tracePropagationTargets` is not provided, trace data is attached to every ou
 
 The Sentry SDK adds spans for file I/O operations to ongoing transactions bound to the scope. Currently, the SDK supports operations with [NSData][NSData], but many other APIs like [NSFileManager][NSFileManager], [NSString][NSString] and [NSBundle][NSBundle] uses [NSData][NSData].
 
-Since 8.0.0, this feature has been enabled by default. To disable it:
-
+Since 8.0.0, this feature has been enabled by default to trace `NSData` operations. To disable it:
 
 ```swift {tabTitle:Swift}
 import Sentry
@@ -261,17 +254,114 @@ SentrySDK.start { options in
 }];
 ```
 
+Starting with iOS 18, macOS 15, and tvOS 18, the `NSFileManager` is no longer backed by `NSData` and needs to be swizzled directly.
+This feature is currently experimental and disabled by default.
+To use automatic file I/O tracing for `NSFileManager` you need to enable it:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableFileIOTracing = true
+    options.experimental.enableFileManagerSwizzling = true
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableFileIOTracing = YES;
+    options.experimental.enableFileManagerSwizzling = YES;
+}];
+```
+
+Starting with iOS 18, tvOS 18, and macOS 15 the Swift classes `Data` and `FileManager` are no longer backed by their Objective-C counterparts `NSData` and `NSFileManager` and therefore cannot be instrumented automatically anymore. Instead, please use [Manual File I/O Tracing](#manual-fileio-tracing).
+
 [NSData]: https://developer.apple.com/documentation/foundation/nsdata
 [NSFileManager]: https://developer.apple.com/documentation/foundation/nsfilemanager
 [NSString]: https://developer.apple.com/documentation/foundation/nsstring
 [NSBundle]: https://developer.apple.com/documentation/foundation/nsbundle
 
+### Manual File/IO Tracing
+
+Starting with version 8.48.0, the Sentry SDK offers extensions for the types `Data` and `FileManager` to track reading and writing data, as well as creating, moving, copying, and deleting files.
+
+The method signatures of the extension resemble the ones of the original types, but they add a span to the current transaction:
+
+**Data Operations:**
+
+- `Data.init(contentsOfUrlWithSentryTracing:)` for `Data(contentsOf:)`
+- `data.writeWithSentryTracing(to:options:)` for `data.write(to:)`
+
+```swift {tabTitle:Swift}
+// Read data from a file URL
+let data = Data(contentsOfUrlWithSentryTracing: url)
+
+// Write data to a file URL
+data.writeWithSentryTracing(to: url)
+```
+
+**FileManager Operations:**
+
+- `FileManager.createFileWithSentryTracing(atPath:contents:attributes:)` for `FileManager.createFile(atPath:contents:attributes:)`
+- `FileManager.moveItemWithSentryTracing(at:to:)` for `FileManager.moveItem(at:to:)`
+- `FileManager.moveItemWithSentryTracing(atPath:toPath:)` for `FileManager.moveItem(atPath:toPath:)`
+- `FileManager.copyItemWithSentryTracing(at:to:)` for `FileManager.copyItem(at:to:)`
+- `FileManager.copyItemWithSentryTracing(atPath:toPath:)` for `FileManager.copyItem(atPath:toPath:)`
+- `FileManager.removeItemWithSentryTracing(at:)` for `FileManager.removeItem(at:)`
+- `FileManager.removeItemWithSentryTracing(atPath:)` for `FileManager.removeItem(atPath:)`
+
+```swift {tabTitle:Swift}
+let fileManager = FileManager.default
+
+// Create a file with given content
+fileManager.createFileWithSentryTracing(atPath: path, contents: data)
+
+// Move a file or directory
+try fileManager.moveItemWithSentryTracing(at: sourceUrl, to: destinationUrl)
+try fileManager.moveItemWithSentryTracing(atPath: sourcePath, toPath: destinationPath)
+
+// Copy a file or directory
+try fileManager.copyItemWithSentryTracing(at: sourceUrl, to: destinationUrl)
+try fileManager.copyItemWithSentryTracing(atPath: sourcePath, toPath: destinationPath)
+
+// Remove a file or directory
+try fileManager.removeItemWithSentryTracing(at: url)
+try fileManager.removeItemWithSentryTracing(atPath: path)
+```
+
+We recommend you disable the swizzling of `NSData` and `NSFileManager` when using manual file I/O tracing, as the internal behavior of these classes differs between platform versions and can cause duplicate spans in your traces.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___";
+    options.enableFileIOTracing = true
+    options.experimental.enableDataSwizzling = false
+    options.experimental.enableFileManagerSwizzling = false
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.enableFileIOTracing = YES;
+    options.experimental.enableDataSwizzling = NO;
+    options.experimental.enableFileManagerSwizzling = NO;
+}];
+```
+
 ## Core Data Tracing
 
 The Sentry SDK adds spans for Core Data operations to ongoing transactions bound to the scope. Currently, the SDK supports fetch and save operations with [NSManagedObjectContext](https://developer.apple.com/documentation/coredata/nsmanagedobjectcontext).
 Since 8.0.0, this feature has been enabled by default. To disable it:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -300,7 +390,6 @@ SentrySDK.start { options in
 
 User interaction tracing, once enabled, captures transactions for clicks. This feature is unavailable for SwiftUI. Since 8.0.0, this feature has been enabled by default. To disable it:
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -381,10 +470,8 @@ By adding a span for a view controller when it's loaded, time to full display (T
 
 Since Cocoa SDK version 8.33.0, the SDK doesn't create [time to initial display (TTID)](#time-to-initial-display) and time to full display (TTFD) spans for UIViewControllers presented in the background, because the logic requires UI frames to be drawn.
 
-
 _Time to full display is disabled by default, but you can enable it by setting:_
 
-
 ```swift {tabTitle:Swift}
 import Sentry
 
@@ -427,15 +514,14 @@ _(New in version 8.18.0), stable since 8.42.0._
 
 We're working to update our **Performance** product offering in order to be able to provide better insights and highlight specific actions you can take to improve your mobile app's overall performance. The `performanceV2` option changes the following behavior:
 
-* The app start duration will now finish when the first frame is drawn instead of when the OS posts the `UIWindowDidBecomeVisibleNotification`.
+- The app start duration will now finish when the first frame is drawn instead of when the OS posts the `UIWindowDidBecomeVisibleNotification`.
 
 This change will be the default in the next major version.
 
 ## Opt Out
 
 You can opt out of all automatic instrumentations using the options:
 
-
 ```swift {tabTitle:Swift}
 import Sentry