diff --git a/docs/platforms/apple/common/configuration/app-hangs.mdx b/docs/platforms/apple/common/configuration/app-hangs.mdx
index f860c7e35f87c..ff23e7cc81b4c 100644
--- a/docs/platforms/apple/common/configuration/app-hangs.mdx
+++ b/docs/platforms/apple/common/configuration/app-hangs.mdx
@@ -166,7 +166,7 @@ The SDK sets the `exception.type` to `Fatal App Hang Fully Blocked` or `Fatal Ap
#### Non-Fully Blocking App Hangs
-As stacktraces might not be 100% accurate for non-fully-blocking app hangs, you can disable them with the option `enableReportNonFullyBlockingAppHangs`:
+As stacktraces might not be 100% accurate for non-fully-blocking app hangs, you can disable them with the `enableReportNonFullyBlockingAppHangs` option:
```swift {tabTitle:Swift}
import Sentry
diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx
index 74e3c45eee058..a07ecdaa39237 100644
--- a/docs/platforms/apple/common/configuration/options.mdx
+++ b/docs/platforms/apple/common/configuration/options.mdx
@@ -22,6 +22,14 @@ Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-uti
+
+
+Controls whether the SDK should send events to Sentry. When set to `false`, the SDK will not send any events to Sentry. The default is `true`.
+
+Note that setting this to `false` doesn't prevent all overhead from Sentry instrumentation. To disable Sentry completely, you may need to conditionally call `SentrySDK.start` based on your environment.
+
+
+
Turns debug mode on or off. If debug is enabled SDK will attempt to print out useful debugging information if something goes wrong with sending the event. The default is always `false`. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.
@@ -97,6 +105,36 @@ When enabled, the SDK reports SIGTERM signals to Sentry.
It's crucial for developers to understand that the OS sends a SIGTERM to their app as a prelude to a graceful shutdown, before resorting to a SIGKILL. This SIGKILL, which your app can't catch or ignore, is a direct order to terminate your app's process immediately. Developers should be aware that their app can receive a SIGTERM in various scenarios, such as CPU or disk overuse, watchdog terminations, or when the OS updates your app.
+
+
+
+
+When enabled, the SDK sends crashes to Sentry. This option defaults to `true`. If disabled, the SDK will not capture or report crash events.
+
+Note that disabling this option will also disable watchdog termination tracking, as it prevents false positive watchdog termination reporting for every crash.
+
+
+
+
+
+
+
+When enabled, the SDK captures uncaught NSExceptions. As this feature uses swizzling, disabling `enableSwizzling` also disables this feature.
+
+This option registers the `NSApplicationCrashOnExceptions` UserDefault, so your macOS application crashes when an uncaught exception occurs. As the Cocoa Frameworks are generally not exception-safe on macOS, we recommend this approach because the application could otherwise end up in a corrupted state.
+
+**Warning:** Don't use this in combination with `SentryCrashExceptionApplication`. Either enable this feature or use the `SentryCrashExceptionApplication`. Having both enabled can lead to duplicated reports.
+
+The default is `false`. This option is available as of SDK version 8.40.0. Learn more in the capturing uncaught exceptions documentation.
+
+
+
+
+
+
+
+Controls the flush duration when calling `SentrySDK.close()`. This determines how long the SDK will wait for pending events to be sent before shutting down. The default is `2.0` seconds.
+
@@ -115,10 +153,20 @@ If you enable this option, be sure to manually remove what you don't want to sen
-
+
When set to `true`, the SDK will send session events to Sentry. This is supported in all browser SDKs, emitting one session per pageload and page navigation to Sentry. In mobile SDKs, when the app goes to the background for longer than 30 seconds, sessions are ended.
+The default is `true`.
+
+
+
+
+
+The interval, measured in milliseconds, to end a session after the app goes to the background. The default is `30000` (30 seconds). When the app goes to the background and remains there for longer than this interval, the current session is ended.
+
+Learn more about session tracking in the releases documentation.
+
@@ -196,6 +244,22 @@ The default is `3000`.
+
+
+When enabled, the SDK tracks performance for UIViewController subclasses.
+
+The default is `true`. This feature is not available in `DebugWithoutUIKit` and `ReleaseWithoutUIKit` configurations even when targeting iOS or tvOS platforms. Learn more in the UIViewController Tracing documentation.
+
+
+
+
+
+When enabled, the SDK reports non-fully-blocking app hangs. Non-fully-blocking app hangs occur when the app appears stuck to the user but can still render a few frames. Fully-blocking app hangs are when the main thread is stuck completely and the app can't render a single frame.
+
+This option defaults to `true`. Learn more in the App Hangs documentation.
+
+
+
@@ -211,10 +275,28 @@ When enabled, the SDK adds breadcrumbs for each network request. This feature us
If you want to enable or disable network tracking for performance monitoring, use `enableNetworkTracking` instead.
-
+
Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry.
+The default is `true` starting with SDK version 8.0.0. Learn more in the HTTP Client Errors documentation.
+
+
+
+
+
+The SDK will only capture HTTP Client errors if the HTTP Response status code is within the defined range.
+
+The default is `500-599`. Learn more in the HTTP Client Errors documentation.
+
+
+
+
+
+An array of hosts or regexes that determines if HTTP Client errors will be automatically captured. This array can contain instances of `NSString` which should match the URL (using `contains`), and instances of `NSRegularExpression`, which will be used to check the whole URL.
+
+The default value automatically captures HTTP Client errors of all outgoing requests. Learn more in the HTTP Client Errors documentation.
+
@@ -225,6 +307,22 @@ This option defaults to `false`. Learn more in the
+
+When enabled, the SDK sends logs to Sentry. Logging is disabled by default; you must explicitly set this option to `true` to enable log capturing.
+
+Learn more about structured logging in the logs documentation.
+
+
+
+
+
+When enabled, the SDK tracks watchdog terminations based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst, works only if the application was in the foreground, and doesn't track watchdog terminations for unit tests.
+
+This option defaults to `true`. Learn more in the Watchdog Terminations documentation.
+
+
+
## Integration Configuration
For many platform SDKs integrations can be configured alongside it. On some platforms that happen as part of the `init()` call, in some others, different patterns apply.
@@ -272,6 +370,176 @@ The callback typically gets a second argument (called a "hint") which contains t
+
+
+This function is called with a span object before it is sent to Sentry. You can return a modified span object, or `null` to skip sending the span. This can be used to filter or modify spans before they are sent.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+ options.dsn = "___PUBLIC_DSN___"
+ options.beforeSendSpan = { span in
+ // Filter out spans with certain operations
+ if span.operation == "db.query" {
+ return nil
+ }
+ return span
+ }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+ options.dsn = @"___PUBLIC_DSN___";
+ options.beforeSendSpan = ^SentrySpan * _Nullable(SentrySpan * _Nonnull span) {
+ // Filter out spans with certain operations
+ if ([span.operation isEqualToString:@"db.query"]) {
+ return nil;
+ }
+ return span;
+ };
+}];
+```
+
+
+
+
+
+This function is called with a log object before it is sent to Sentry. You can return a modified log object, or `null` to skip sending the log. This can be used to filter or modify logs before they are sent.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+ options.dsn = "___PUBLIC_DSN___"
+ options.enableLogs = true
+ options.beforeSendLog = { log in
+ // Filter out info level logs
+ if log.level == .info {
+ return nil
+ }
+ return log
+ }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+ options.dsn = @"___PUBLIC_DSN___";
+ options.enableLogs = YES;
+ options.beforeSendLog = ^SentryLog * _Nullable(SentryLog * _Nonnull log) {
+ // Filter out info level logs
+ if (log.level == SentryLogLevelInfo) {
+ return nil;
+ }
+ return log;
+ };
+}];
+```
+
+Learn more about log filtering in the logs documentation.
+
+
+
+
+
+This function is called to decide if the SDK should capture a screenshot. Return `true` to allow screenshot capture, or `false` to prevent it.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+ options.dsn = "___PUBLIC_DSN___"
+ options.attachScreenshot = true
+ options.beforeCaptureScreenshot = {
+ // Prevent screenshots in certain views
+ return !isSensitiveView()
+ }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+ options.dsn = @"___PUBLIC_DSN___";
+ options.attachScreenshot = YES;
+ options.beforeCaptureScreenshot = ^BOOL {
+ // Prevent screenshots in certain views
+ return !isSensitiveView();
+ };
+}];
+```
+
+
+
+
+
+This function is called to decide if the SDK should capture a view hierarchy. Return `true` to allow view hierarchy capture, or `false` to prevent it.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+ options.dsn = "___PUBLIC_DSN___"
+ options.attachViewHierarchy = true
+ options.beforeCaptureViewHierarchy = {
+ // Prevent view hierarchy capture in certain views
+ return !isSensitiveView()
+ }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+ options.dsn = @"___PUBLIC_DSN___";
+ options.attachViewHierarchy = YES;
+ options.beforeCaptureViewHierarchy = ^BOOL {
+ // Prevent view hierarchy capture in certain views
+ return !isSensitiveView();
+ };
+}];
+```
+
+
+
+
+
+A block called after SDK initialization when the last execution terminated with a crash. This callback is invoked synchronously during SDK initialization, so keep any work here minimal.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+ options.dsn = "___PUBLIC_DSN___"
+ options.onCrashedLastRun = {
+ // Perform actions when a crash was detected on last run
+ print("App crashed on last run")
+ }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+ options.dsn = @"___PUBLIC_DSN___";
+ options.onCrashedLastRun = ^{
+ // Perform actions when a crash was detected on last run
+ NSLog(@"App crashed on last run");
+ };
+}];
+```
+
+
+
## Tracing Options
@@ -320,6 +588,296 @@ This feature is experimental and may have bugs. It's available from [version 8.4
-When enabled, the SDK finishes the ongoing transaction bound to the scope and links them to the crash event when your app crashes. The SDK skips adding profiles to increase the chance of keeping the transaction. This option defaults to `false`.
+When enabled, the SDK finishes the ongoing transaction bound to the scope and links them to the crash event when your app crashes. This allows you to see the performance data leading up to a crash, helping you understand what was happening when the crash occurred.
+
+The SDK skips adding profiles to increase the chance of keeping the transaction. This option defaults to `false`.
+
+This feature requires that tracing is enabled via or .
+
+
+
+## Screenshot Options
+
+Screenshot options allow you to configure how screenshots are captured and masked when attached to error events. These options are available under `options.screenshot`.
+
+
+
+When enabled, all text content in screenshots is masked. This helps ensure that no sensitive text data is exposed in screenshots sent to Sentry.
+
+The default is `true`. Learn more about screenshot options in the Screenshots documentation.
+
+
+
+
+
+When enabled, all images in screenshots are masked. This helps ensure that no sensitive image data is exposed in screenshots sent to Sentry.
+
+The default is `true`. Learn more about screenshot options in the Screenshots documentation.
+
+
+
+
+
+A list of view class names that should be masked in screenshots. Views matching these class names will have their content masked.
+
+
+
+
+
+A list of view class names that should not be masked in screenshots, even if other masking options are enabled. Views matching these class names will be shown without masking.
+
+
+
+
+
+When enabled, uses the faster view renderer V2 for capturing screenshots. This renderer reduces the performance impact of screenshot capture.
+
+The default is `true` starting with SDK version 8.50.0.
+
+
+
+
+
+When enabled, uses faster but potentially incomplete view rendering for screenshots. This can improve performance but may result in some views not being fully rendered.
+
+The default is `false`.
+
+
+
+## Session Replay Options
+
+Session Replay options allow you to configure how session replays are recorded and sent to Sentry. These options are available under `options.sessionReplay`.
+
+
+
+When enabled, uses faster but potentially incomplete view rendering for session replays. This can improve performance but may result in some views not being fully rendered in the replay.
+
+The default is `false`. Learn more about session replay performance in the Performance Overhead documentation.
+
+
+
+## Profiling Options
+
+Profiling options allow you to configure how profiling data is collected. These options are available under `options.configureProfiling`.
+
+
+
+When enabled, the profiler starts as early as possible during the app lifecycle, allowing you to profile app startup performance.
+
+The default is `false`. Learn more about profiling in the Profiling documentation.
+
+
+
+## Network & Performance Options
+
+
+
+A read-only property that indicates whether tracing is enabled. This property is `true` when either or is configured.
+
+
+
+
+
+When enabled, the SDK tracks performance for UIViewController subclasses and HTTP requests automatically. It also measures the app start and slow and frozen frames.
+
+The default is `true`. Performance Monitoring must be enabled for this flag to take effect. Learn more about Performance Monitoring.
+
+
+
+
+
+When enabled, the SDK creates transactions for UI events like button clicks, switch toggles, and other UI elements that use UIControl `sendAction:to:forEvent:`.
+
+The default is `true`. This feature is unavailable for SwiftUI. Learn more in the User Interaction Tracing documentation.
+
+
+
+
+
+Report pre-warmed app starts by dropping the first app start spans if pre-warming paused during these steps. This approach will shorten the app start duration, but it represents the duration a user has to wait after clicking the app icon until the app is responsive.
+
+The default is `true` starting with SDK version 9.0.0. Learn more in the Prewarmed App Start Tracing documentation.
+
+
+
+
+
+When enabled, the SDK tracks performance for HTTP requests if auto performance tracking and `enableSwizzling` are enabled.
+
+The default is `true`. Learn more in the Network Tracking documentation.
+
+
+
+
+
+When enabled, the SDK tracks performance for file I/O reads and writes with NSData if auto performance tracking and `enableSwizzling` are enabled.
+
+The default is `true`. Learn more in the File I/O Tracing documentation.
+
+
+
+
+
+When enabled, the SDK tracks the performance of Core Data operations. It requires enabling performance monitoring.
+
+The default is `true`. Learn more in the Core Data Tracing documentation.
+
+
+
+
+
+When enabled, every UIViewController tracing transaction will wait for a call to `SentrySDK.reportFullyDisplayed()`. Use this in conjunction with `enableUIViewControllerTracing`. If `SentrySDK.reportFullyDisplayed()` is not called, the transaction will finish automatically after 30 seconds and the `Time to full display` span will be finished with `DeadlineExceeded` status.
+
+The default is `false`. Learn more in the Time to Full Display documentation.
+
+
+
+
+
+Set as the delegate on the URLSession used for network tasks. This allows you to customize the URLSession behavior while still allowing Sentry to track network requests.
+
+
+
+
+
+Use a custom URLSession with your configuration for sending requests to Sentry. This allows you to use your own URLSession configuration, for example, to configure proxy settings or custom SSL certificates.
+
+
+
+## Swizzling Options
+
+
+
+Whether the SDK should use swizzling or not. When turned off the following features are disabled: breadcrumbs for touch events and navigation with UIViewControllers, automatic instrumentation for UIViewControllers, automatic instrumentation for HTTP requests, automatic instrumentation for file I/O with NSData, and automatically added sentry-trace header to HTTP requests for distributed tracing.
+
+The default is `true`. Learn more in the Swizzling documentation.
+
+
+
+
+
+A set of class names to ignore for swizzling. The SDK checks if a class name of a class to swizzle contains a class name of this array. For example, if you add `MyUIViewController` to this list, the SDK excludes the following classes from swizzling: `YourApp.MyUIViewController`, `YourApp.MyUIViewControllerA`, `MyApp.MyUIViewController`.
+
+The default is an empty set. This option is available with SDK version 8.23.0 and above. Learn more in the Swizzling documentation.
+
+
+
+
+
+When enabled, the SDK tracks performance for file I/O reads and writes with NSData if auto performance tracking and `enableSwizzling` are enabled.
+
+The default is `true`. Learn more in the File I/O Tracing documentation.
+
+
+
+
+
+When enabled, the SDK tracks performance for file I/O operations with NSFileManager if auto performance tracking and `enableSwizzling` are enabled.
+
+The default is `false`. This feature is currently experimental and disabled by default. Learn more in the File I/O Tracing documentation.
+
+
+
+## App Hang Options
+
+
+
+When enabled, the SDK tracks when the application stops responding for a specific amount of time defined by the `appHangTimeoutInterval` option.
+
+On iOS, tvOS and visionOS, the SDK can differentiate between fully-blocking and non-fully-blocking app hangs. A fully-blocking app hang is when the main thread is stuck completely, and the app can't render a single frame. A non-fully-blocking app hang is when the app appears stuck to the user but can still render a few frames.
+
+The default is `true`. App Hang tracking is automatically disabled if a debugger is attached. Learn more in the App Hangs documentation.
+
+
+
+
+
+The minimum amount of time an app should be unresponsive to be classified as an App Hanging. The actual amount may be a little longer.
+
+Avoid using values lower than 100ms, which may cause a lot of app hangs events being transmitted.
+
+The default value is `2.0` seconds. Learn more in the App Hangs documentation.
+
+
+
+## MetricKit Options
+
+
+
+When enabled, the SDK subscribes to MetricKit diagnostic reports and sends MXHangDiagnostic, MXDiskWriteExceptionDiagnostic, and MXCPUExceptionDiagnostic to Sentry.
+
+This feature is available on SDK version 8.14.0 and up. The SDK supports this feature from iOS 15 and up and macOS 12 and up because in these versions, MetricKit delivers diagnostic reports immediately, which allows the Sentry SDK to apply current data from the scope.
+
+The default is `false`. Learn more in the MetricKit documentation.
+
+
+
+
+
+When enabled, the SDK adds the raw MXDiagnosticPayloads as an attachment to the converted SentryEvent. You need to enable `enableMetricKit` for this flag to work.
+
+This feature is available on SDK version 8.29.0 and up.
+
+The default is `false`. Learn more in the MetricKit documentation.
+
+
+
+## Other Options
+
+
+
+When enabled, the SDK adds breadcrumbs for various system events.
+
+The default is `true`.
+
+
+
+
+
+The maximum size for each attachment in bytes.
+
+The default is 200 MiB (200 × 1024 × 1024 bytes). Please also check the maximum attachment size of relay to make sure your attachments don't get discarded there.
+
+
+
+
+
+If enabled, view hierarchy attachment will contain view `accessibilityIdentifier`. Set it to `false` if your project uses `accessibilityIdentifier` for PII.
+
+The default is `true`.
+
+
+
+
+
+This feature is only available from Xcode 13 and from macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0.
+
+This is an experimental feature and may still have bugs. When enabled, stitches the call to Swift Async functions in one consecutive stack trace.
+
+The default is `false`. Learn more in the Experimental Features documentation.
+
+
+
+
+
+The path where the SDK stores data (events, transactions, profiles, etc.). By default, the SDK uses `NSCachesDirectory`. You can specify a custom path if needed.
+
+We recommend only changing this when the default, e.g., in security environments, can't be accessed.
+
+
+
+
+
+Whether to enable Spotlight for local development. Spotlight is a local development tool that allows you to inspect Sentry events locally.
+
+The default is `false`. This option is primarily useful for local development and debugging.
+
+
+
+
+
+The Spotlight URL for local development. The default is `"http://localhost:8969/stream"`.
+
+This option is only used when is set to `true`.
diff --git a/docs/platforms/apple/common/configuration/watchdog-terminations.mdx b/docs/platforms/apple/common/configuration/watchdog-terminations.mdx
index 7e236c5f52891..5cf9c89ee103b 100644
--- a/docs/platforms/apple/common/configuration/watchdog-terminations.mdx
+++ b/docs/platforms/apple/common/configuration/watchdog-terminations.mdx
@@ -38,7 +38,7 @@ When a user launches the app, the SDK checks the following statements and report
If you're interested in the implementation details, you can check out [the code](https://github.com/getsentry/sentry-cocoa/blob/main/Sources/Sentry/SentryWatchdogTerminationLogic.m) to find out more.
-If you'd like to opt out of this feature, you can do so using options:
+If you'd like to opt out of this feature, you can do so using the `enableWatchdogTerminationTracking` option:
```swift {tabTitle:Swift}
@@ -59,7 +59,7 @@ SentrySDK.start { options in
}];
```
-If you disable the `enableCrashHandler` option, the SDK will disable watchdog termination tracking. This will prevent false positive watchdog termination reporting for every crash.
+If you disable the `enableCrashHandler` option, the SDK will disable watchdog termination tracking. This will prevent false positive watchdog termination reporting for every crash.
#### FAQ