From 916578249ca114ee4e496d6d826a69edfff824a0 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Tue, 16 Dec 2025 12:31:26 +0100 Subject: [PATCH 1/5] fix(apple): Add all undocumented options --- .../apple/common/configuration/app-hangs.mdx | 2 +- .../apple/common/configuration/options.mdx | 564 +++++++++++++++++- .../configuration/watchdog-terminations.mdx | 4 +- 3 files changed, 564 insertions(+), 6 deletions(-) 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 From 603fd874c7096f6d4a8d1fb7ba949cc658899df9 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Mon, 22 Dec 2025 10:41:49 +0100 Subject: [PATCH 2/5] fixes --- docs/platforms/apple/common/configuration/options.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index a07ecdaa39237..f0e69305574cd 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -652,6 +652,12 @@ Session Replay options allow you to configure how session replays are recorded a 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. + + +We discourage using this option as it can result in incomplete or missing views in session replays, which may make debugging more difficult. Only enable this option if you understand the trade-offs and have thoroughly tested your application. + + + The default is `false`. Learn more about session replay performance in the Performance Overhead documentation. @@ -866,6 +872,8 @@ We recommend only changing this when the default, e.g., in security environments +## Spotlight + Whether to enable Spotlight for local development. Spotlight is a local development tool that allows you to inspect Sentry events locally. From 8af89a4957fb5ba008c4ef9225f7fd93e0811095 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Mon, 22 Dec 2025 13:08:43 +0100 Subject: [PATCH 3/5] remove all mentions of defaults --- .../apple/common/configuration/options.mdx | 100 ++++++++---------- 1 file changed, 43 insertions(+), 57 deletions(-) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index f0e69305574cd..b8c5d030193d0 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -24,7 +24,7 @@ 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`. +Controls whether the SDK should send events to Sentry. When set to `false`, the SDK will not send any events to Sentry. 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. @@ -32,7 +32,7 @@ Note that setting this to `false` doesn't prevent all overhead from Sentry instr -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. +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. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns. @@ -70,19 +70,19 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env -Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. +Configures the sample rate for error events, in the range of `0.0` to `1.0`. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. -This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped. +This variable controls the total amount of breadcrumbs that should be captured. You can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped. -The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. The default is `30`. +The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. @@ -90,8 +90,6 @@ The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/enve When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all log messages. -This option is turned on by default. - Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events. @@ -109,7 +107,7 @@ It's crucial for developers to understand that the OS sends a SIGTERM to their a -When enabled, the SDK sends crashes to Sentry. This option defaults to `true`. If disabled, the SDK will not capture or report crash events. +When enabled, the SDK sends crashes to Sentry. 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. @@ -125,7 +123,7 @@ This option registers the `NSApplicationCrashOnExceptions` UserDefault, so your **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. +This option is available as of SDK version 8.40.0. Learn more in the capturing uncaught exceptions documentation. @@ -133,13 +131,13 @@ The default is `false`. This option is available as of SDK version 8.40.0. Learn -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. +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. -If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. +If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. @@ -147,8 +145,6 @@ If you are using Sentry in your mobile app, read our [frequently asked questions -This option is turned off by default. - If you enable this option, be sure to manually remove what you don't want to send using our features for managing [_Sensitive Data_](../../data-management/sensitive-data/). @@ -157,13 +153,11 @@ 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. +The interval, measured in milliseconds, to end a session after the app goes to the background. 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. @@ -240,15 +234,13 @@ Learn more about enriching events with the view hierarchy in our user interaction transaction will be automatically finished. The transaction will use the end timestamp of the last finished span as the endtime for the transaction. -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. +This feature is not available in `DebugWithoutUIKit` and `ReleaseWithoutUIKit` configurations even when targeting iOS or tvOS platforms. Learn more in the UIViewController Tracing documentation. @@ -256,7 +248,7 @@ The default is `true`. This feature is not available in `DebugWithoutUIKit` and 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. +Learn more in the App Hangs documentation. @@ -279,7 +271,7 @@ If you want to enable or disable network tracking for performance monitoring, us 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. +This feature is enabled by default starting with SDK version 8.0.0. Learn more in the HTTP Client Errors documentation. @@ -287,7 +279,7 @@ The default is `true` starting with SDK version 8.0.0. Learn more in the HTTP Client Errors documentation. +Learn more in the HTTP Client Errors documentation. @@ -303,13 +295,13 @@ The default value automatically captures HTTP Client errors of all outgoing requ When enabled, the SDK extracts the GraphQL operation name from HTTP requests that have `Content-Type: application/json` and contain a JSON body with an `operationName` field. The operation name is then attached to HTTP breadcrumbs and failed request events. -This option defaults to `false`. Learn more in the GraphQL Operation Tracking documentation. +Learn more in the GraphQL Operation Tracking documentation. -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. +When enabled, the SDK sends logs to Sentry. You must explicitly set this option to `true` to enable log capturing. Learn more about structured logging in the logs documentation. @@ -319,7 +311,7 @@ Learn more about structured logging in the logs docume 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. +Learn more in the Watchdog Terminations documentation. @@ -590,7 +582,7 @@ 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. 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`. +The SDK skips adding profiles to increase the chance of keeping the transaction. This feature requires that tracing is enabled via or . @@ -604,7 +596,7 @@ Screenshot options allow you to configure how screenshots are captured and maske 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. +Learn more about screenshot options in the Screenshots documentation. @@ -612,7 +604,7 @@ The default is `true`. Learn more about screenshot options in the Screenshots documentation. +Learn more about screenshot options in the Screenshots documentation. @@ -632,7 +624,7 @@ A list of view class names that should not be masked in screenshots, even if oth 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. +This option is enabled by default starting with SDK version 8.50.0. @@ -640,8 +632,6 @@ 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 @@ -658,7 +648,7 @@ We discourage using this option as it can result in incomplete or missing views -The default is `false`. Learn more about session replay performance in the Performance Overhead documentation. +Learn more about session replay performance in the Performance Overhead documentation. @@ -670,7 +660,7 @@ Profiling options allow you to configure how profiling data is collected. These 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. +Learn more about profiling in the Profiling documentation. @@ -686,7 +676,7 @@ A read-only property that indicates whether tracing is enabled. This property is 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. +Performance Monitoring must be enabled for this flag to take effect. Learn more about Performance Monitoring. @@ -694,7 +684,7 @@ The default is `true`. Performance Monitoring must be enabled for this flag to t 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. +This feature is unavailable for SwiftUI. Learn more in the User Interaction Tracing documentation. @@ -702,7 +692,7 @@ The default is `true`. This feature is unavailable for SwiftUI. Learn more in th 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. +This option is enabled by default starting with SDK version 9.0.0. Learn more in the Prewarmed App Start Tracing documentation. @@ -710,7 +700,7 @@ The default is `true` starting with SDK version 9.0.0. Learn more in the Network Tracking documentation. +Learn more in the Network Tracking documentation. @@ -718,7 +708,7 @@ The default is `true`. Learn more in the File I/O Tracing documentation. +Learn more in the File I/O Tracing documentation. @@ -726,7 +716,7 @@ The default is `true`. Learn more in the Core Data Tracing documentation. +Learn more in the Core Data Tracing documentation. @@ -734,7 +724,7 @@ The default is `true`. Learn more in the Time to Full Display documentation. +Learn more in the Time to Full Display documentation. @@ -756,15 +746,15 @@ Use a custom URLSession with your configuration for sending requests to Sentry. 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. +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. +This option is available with SDK version 8.23.0 and above. Learn more in the Swizzling documentation. @@ -772,7 +762,7 @@ The default is an empty set. This option is available with SDK version 8.23.0 an 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. +Learn more in the File I/O Tracing documentation. @@ -780,7 +770,7 @@ The default is `true`. Learn more in the File I/O Tracing documentation. +This feature is currently experimental and disabled by default. Learn more in the File I/O Tracing documentation. @@ -792,7 +782,7 @@ When enabled, the SDK tracks when the application stops responding for a specifi 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. +App Hang tracking is automatically disabled if a debugger is attached. Learn more in the App Hangs documentation. @@ -802,7 +792,7 @@ The minimum amount of time an app should be unresponsive to be classified as an 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. +Learn more in the App Hangs documentation. @@ -814,7 +804,7 @@ When enabled, the SDK subscribes to MetricKit diagnostic reports and sends MXHan 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. +Learn more in the MetricKit documentation. @@ -824,7 +814,7 @@ When enabled, the SDK adds the raw MXDiagnosticPayloads as an attachment to the This feature is available on SDK version 8.29.0 and up. -The default is `false`. Learn more in the MetricKit documentation. +Learn more in the MetricKit documentation. @@ -834,15 +824,13 @@ The default is `false`. Learn more in the 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. +Please also check the maximum attachment size of relay to make sure your attachments don't get discarded there. @@ -850,8 +838,6 @@ The default is 200 MiB (200 × 1024 × 1024 bytes). Please also check the maximu If enabled, view hierarchy attachment will contain view `accessibilityIdentifier`. Set it to `false` if your project uses `accessibilityIdentifier` for PII. -The default is `true`. - @@ -860,7 +846,7 @@ This feature is only available from Xcode 13 and from macOS 12.0, iOS 15.0, tvOS 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. +Learn more in the Experimental Features documentation. @@ -878,13 +864,13 @@ We recommend only changing this when the default, e.g., in security environments 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. +This option is primarily useful for local development and debugging. -The Spotlight URL for local development. The default is `"http://localhost:8969/stream"`. +The Spotlight URL for local development. This option is only used when is set to `true`. From 0952050f6c8eeb158fa04bf92001801cefc4c613 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Mon, 22 Dec 2025 15:02:42 +0100 Subject: [PATCH 4/5] fix links to screenshot options --- docs/platforms/apple/common/configuration/options.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index b8c5d030193d0..b190d2b773d52 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -592,20 +592,18 @@ This feature requires that tracing is enabled via Screenshots documentation. + When enabled, all text content in screenshots is masked. This helps ensure that no sensitive text data is exposed in screenshots sent to Sentry. -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. -Learn more about screenshot options in the Screenshots documentation. - From ad5483f42504461474012e2a7c4fd030cb0783ff Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Tue, 23 Dec 2025 08:08:02 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Alex Krawiec --- .../apple/common/configuration/options.mdx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index b190d2b773d52..6da5aec7bab98 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -32,7 +32,7 @@ Note that setting this to `false` doesn't prevent all overhead from Sentry instr -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. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns. +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. It's generally not recommended to turn it on in production, though this will not cause any safety concerns. @@ -121,7 +121,7 @@ When enabled, the SDK captures uncaught NSExceptions. As this feature uses swizz 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. +**Warning:** Don't use this in combination with `SentryCrashExceptionApplication`. Having both enabled can lead to duplicated reports. This option is available as of SDK version 8.40.0. Learn more in the capturing uncaught exceptions documentation. @@ -238,9 +238,9 @@ The idle time, measured in ms, to wait until a -When enabled, the SDK tracks performance for UIViewController subclasses. +When enabled, the SDK tracks performance for the UIViewController subclasses. -This feature is not available in `DebugWithoutUIKit` and `ReleaseWithoutUIKit` configurations even when targeting iOS or tvOS platforms. Learn more in the UIViewController Tracing documentation. +This feature is not available in `DebugWithoutUIKit` and `ReleaseWithoutUIKit` configurations, even when targeting iOS or tvOS platforms. Learn more in the UIViewController Tracing documentation. @@ -309,7 +309,7 @@ Learn more about structured logging in the logs docume -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. +When enabled, the SDK tracks watchdog terminations based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst. It only works if the application was in the foreground, and it doesn't track watchdog terminations for unit tests. Learn more in the Watchdog Terminations documentation. @@ -364,7 +364,7 @@ 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. +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 @@ -720,7 +720,7 @@ Learn more in the -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. +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 a `DeadlineExceeded` status. Learn more in the Time to Full Display documentation. @@ -742,7 +742,7 @@ Use a custom URLSession with your configuration for sending requests to Sentry. -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. +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. Learn more in the Swizzling documentation. @@ -750,7 +750,7 @@ Learn more in the Swizzling -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`. +A set of class names to exclude from swizzling. The SDK checks whether the class’s name contains any value in this list. If it does, the class is skipped. For example, if you add `MyUIViewController` to this list, the SDK excludes the following classes from swizzling: `YourApp.MyUIViewController`, `YourApp.MyUIViewControllerA`, `MyApp.MyUIViewController`. This option is available with SDK version 8.23.0 and above. Learn more in the Swizzling documentation. @@ -786,9 +786,9 @@ App Hang tracking is automatically disabled if a debugger is attached. Learn mor -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. +The minimum amount of time an app should be unresponsive to be classified as an App Hang. 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. +Avoid using values below 100 ms, as this can result in a high volume of app hang events being sent. Learn more in the App Hangs documentation. @@ -834,7 +834,7 @@ Please also check the maximum attachment size of relay to make sure your attachm -If enabled, view hierarchy attachment will contain view `accessibilityIdentifier`. Set it to `false` if your project uses `accessibilityIdentifier` for PII. +If enabled, the view hierarchy attachment will contain view `accessibilityIdentifier`. Set it to `false` if your project uses `accessibilityIdentifier` for PII. @@ -842,7 +842,7 @@ If enabled, view hierarchy attachment will contain view `accessibilityIdentifier 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. +This is an experimental feature and may still have bugs. When enabled, the SDK stitches the call to Swift Async functions in one consecutive stack trace. Learn more in the Experimental Features documentation. @@ -852,7 +852,7 @@ Learn more in the Experiment 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. +We recommend only changing this when the default can't be accessed, such as in security environments.