From 80726113be91913a8f075a9d11761f98bcee2544 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 15 Oct 2026 01:12:59 +0000 Subject: [PATCH 1/5] feat(docs): Apply new quick start template to Apple quick start guides Co-Authored-By: Shannon Anahata --- includes/apple-platform-getting-started.mdx | 410 ++++++++------------ 1 file changed, 163 insertions(+), 247 deletions(-) diff --git a/includes/apple-platform-getting-started.mdx b/includes/apple-platform-getting-started.mdx index fb4e52304e2f5..80c54a70eda87 100644 --- a/includes/apple-platform-getting-started.mdx +++ b/includes/apple-platform-getting-started.mdx @@ -1,10 +1,10 @@ -On this page, we get you up and running with Sentry's Apple SDK, which will automatically report errors and exceptions in your application. +On this page, you'll set up Sentry's Apple SDK to report errors and exceptions in your application. -If you don't already have an account and Sentry project established, head over to [sentry.io](https://sentry.io/signup/), then return to this page. +If you don't already have a Sentry account and project, [create them](https://sentry.io/signup/) before you continue. @@ -12,126 +12,110 @@ If you don't already have an account and Sentry project established, head over t -The support for [visionOS](https://developer.apple.com/visionos/) is currently experimental, which means it may have bugs. We recognize the irony. +Support for [visionOS](https://developer.apple.com/visionos/) is experimental and may have bugs. -## Features + - +## Install -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also collect and analyze performance profiles from real users with [profiling](/product/profiling/). +Sentry captures data by using an SDK within your application's runtime. We recommend installing the SDK with Swift Package Manager (SPM). In Xcode, open **File > Add Packages**, then enter this repository URL: - +``` +https://github.com/getsentry/sentry-cocoa.git +``` - + -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). +For iOS, you can install and configure the SDK with the [Sentry Wizard](https://github.com/getsentry/sentry-wizard). Run this command from your project directory: - +```bash +brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios +``` -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. +The wizard patches your project with the SDK configuration and adds the patched files to your version control. To set up the SDK manually, see Manual Setup or continue below. -## Install + - +- Install the Sentry SDK with Swift Package Manager +- Update your `AppDelegate` or SwiftUI app initializer with the default Sentry configuration and an example error +- Add an `Upload Debug Symbols` phase to your `xcodebuild` build script +- Create `.sentryclirc` with an auth token for uploading debug symbols (the file is added to `.gitignore`) +- Add a Fastlane lane for uploading debug symbols if you're using Fastlane - + - + - +To use another installation method, see the installation options. +## Configure -Sentry captures data by using an SDK within your application's runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works. + - +**Error Monitoring** starts working as soon as you initialize the SDK. -We recommend installing the SDK with Swift Package Manager (SPM), but we also support alternate [installation methods](install/). To integrate Sentry into your Xcode project, open your App in Xcode and open **File > Add Packages**. Then add the SDK by entering the git repo url in the top right search field: + -``` -https://github.com/getsentry/sentry-cocoa.git -``` + - +watchOS doesn't support crash detection. Use the snippet in [Verify Your Setup](#verify-your-setup) to capture handled errors. - -We recommend installing the SDK through our [Sentry Wizard](https://github.com/getsentry/sentry-wizard) by running the following command inside your project directory: + -```bash -brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios -``` + -This will patch your project and configure the SDK. You'll only need to patch the project once, then you'll be able to add the patched files to your version control system. -If you prefer, you can also [set up the SDK manually](/platforms/apple/guides/ios/manual-setup/) or follow the instructions below to adapt the [configuration](#configure). +This guide also enables **Tracing** on iOS, macOS, tvOS, and visionOS. The snippets enable **Profiling** on iOS and macOS, **Session Replay** on iOS, and **Logs** on iOS, macOS, tvOS, and visionOS. Logs require an explicit option; Application Metrics are enabled by default and don't need extra configuration. See [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-) to use them. - + -- Install the Sentry SDK via Swift Package Manager -- Update your `AppDelegate` or SwiftUI App Initializer with the default Sentry configuration and an example error -- Add a new `Upload Debug Symbols` phase to your `xcodebuild` build script -- Create `.sentryclirc` with an auth token to upload debug symbols (this file is automatically added to `.gitignore`) -- If you're using Fastlane, a lane for uploading debug symbols to Sentry will be added + - +Application Metrics are enabled by default. watchOS doesn't support Tracing, Profiling, Session Replay, or Logs. -## Configure +The snippets set `sendDefaultPii` to include IP addresses. Remove that option if you don't want to send this data. Remove other options for features you don't need. - + -To capture all errors, we recommend to initialize the SDK on the main thread as soon as possible, such as in your `AppDelegate` `application:didFinishLaunchingWithOptions` method: +### Initialize the SDK - - - +To capture errors, initialize the SDK as early as possible, such as in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method or your SwiftUI `App` initializer. Session Replay is available on iOS 16+ with Sentry Cocoa SDK 8.31.1+; UI Profiling requires SDK 8.49.0+. ```swift {tabTitle:Swift} {mdExpandTabs} import Sentry func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { - SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.debug = true // Enabled debug when first installing is always helpful - - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.debug = true options.sendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1 - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = 1.0 + // Enable Profiling. options.configureProfiling = { $0.lifecycle = .trace - $0.sessionSampleRate = 1 + $0.sessionSampleRate = 1.0 } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ session-replay - // Record session replays for 100% of errors and 10% of sessions + // Enable Session Replay. options.sessionReplay.onErrorSampleRate = 1.0 options.sessionReplay.sessionSampleRate = 0.1 - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ logs - // Enable logs to be sent to Sentry + // Enable Logs. options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs } - return true } ``` @@ -140,40 +124,27 @@ func application(_ application: UIApplication, @import Sentry; - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { - [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.debug = YES; // Enabled debug when first installing is always helpful - - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.debug = YES; options.sendDefaultPii = YES; - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = @1.f; - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = @1.0; + // Enable Profiling. options.configureProfiling = ^(SentryProfileOptions *profiling) { profiling.lifecycle = SentryProfileLifecycleTrace; - profiling.sessionSampleRate = 1.f; + profiling.sessionSampleRate = 1.0; }; - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ session-replay - // Record session replays for 100% of errors and 10% of sessions + // Enable Session Replay. options.sessionReplay.onErrorSampleRate = 1.0; options.sessionReplay.sessionSampleRate = 0.1; - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ logs - // Enable logs to be sent to Sentry + // Enable Logs. options.enableLogs = YES; - // ___PRODUCT_OPTION_END___ logs }]; - return YES; } ``` @@ -182,161 +153,127 @@ func application(_ application: UIApplication, import Sentry @main -struct SwiftUIApp: App { +struct ExampleApp: App { init() { SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.debug = true // Enabled debug when first installing is always helpful - - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.debug = true options.sendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1 - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - + options.tracesSampleRate = 1.0 options.configureProfiling = { $0.lifecycle = .trace - $0.sessionSampleRate = 1 + $0.sessionSampleRate = 1.0 } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ session-replay - // Record session replays for 100% of errors and 10% of sessions options.sessionReplay.onErrorSampleRate = 1.0 options.sessionReplay.sessionSampleRate = 0.1 - // ___PRODUCT_OPTION_END___ session-replay - - // ___PRODUCT_OPTION_START___ logs - // Enable logs to be sent to Sentry options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs } } } ``` + - + -```swift {tabTitle:Swift} {mdExpandTabs} -import Sentry +### Initialize the SDK -func application(_ application: UIApplication, - didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { +Initialize the SDK as early as possible when your application starts. The snippet enables Tracing, Profiling, and Logs. UI Profiling requires Sentry Cocoa SDK 8.49.0+. macOS doesn't support Session Replay. - SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.debug = true // Enabled debug when first installing is always helpful +```swift {tabTitle:Swift} +import Sentry - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ - options.sendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.debug = true + options.sendDefaultPii = true + options.enableUncaughtNSExceptionReporting = true - // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1 - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = 1.0 - options.configureProfiling = { - $0.lifecycle = .trace - $0.sessionSampleRate = 1 - } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs - - // Enable logs to be sent to Sentry - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs + // Enable Profiling. + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1.0 } - return true + // Enable Logs. + options.enableLogs = true } ``` ```objc {tabTitle:Objective-C} @import Sentry; -- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.debug = YES; + options.sendDefaultPii = YES; + options.enableUncaughtNSExceptionReporting = YES; + options.tracesSampleRate = @1.0; + options.configureProfiling = ^(SentryProfileOptions *profiling) { + profiling.lifecycle = SentryProfileLifecycleTrace; + profiling.sessionSampleRate = 1.0; + }; + options.enableLogs = YES; +}]; +``` - [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.debug = YES; // Enabled debug when first installing is always helpful +On macOS, the SDK can't capture uncaught exceptions without additional configuration. The snippets enable `enableUncaughtNSExceptionReporting`. For other options, see capturing uncaught exceptions. - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ - options.sendDefaultPii = YES; + - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = @1.f; - // ___PRODUCT_OPTION_END___ performance + - // ___PRODUCT_OPTION_START___ profiling - options.configureProfiling = ^(SentryProfileOptions *profiling) { - profiling.lifecycle = SentryProfileLifecycleTrace; - profiling.sessionSampleRate = 1.f; - }; - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs +### Initialize the SDK - // Enable logs to be sent to Sentry - options.enableLogs = YES; - // ___PRODUCT_OPTION_END___ logs - }]; +Initialize the SDK as early as possible, such as in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method. The snippets enable Tracing and Logs. Profiling isn't available on tvOS or visionOS. - return YES; -} -``` + -```swift {tabTitle:SwiftUI with App conformer} -import Sentry +Session Replay may run on tvOS 16+, but it's only officially supported on iOS. This guide doesn't configure it on tvOS. -@main -struct SwiftUIApp: App { - init() { - SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.debug = true // Enabled debug when first installing is always helpful + - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ - options.sendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance +```swift {tabTitle:Swift} {mdExpandTabs} +import Sentry - // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1 - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling +func application(_ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { + SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.debug = true + options.sendDefaultPii = true + options.tracesSampleRate = 1.0 + options.enableLogs = true + } + return true +} +``` - options.configureProfiling = { - $0.lifecycle = .trace - $0.sessionSampleRate = 1 - } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs +```objc {tabTitle:Objective-C} +@import Sentry; - // Enable logs to be sent to Sentry - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs - } - } +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.debug = YES; + options.sendDefaultPii = YES; + options.tracesSampleRate = @1.0; + options.enableLogs = YES; + }]; + return YES; } ``` + - +### Initialize the SDK -To capture all errors, we recommend to initialize the SDK on the main thread as soon as possible such as in your `WKExtensionDelegate.applicationDidFinishLaunching` method: +Initialize the SDK in your `WKExtensionDelegate.applicationDidFinishLaunching` method. watchOS doesn't support crash detection, most performance monitoring features, Profiling, Session Replay, or Logs. ```swift import Sentry @@ -344,95 +281,74 @@ import Sentry func applicationDidFinishLaunching() { SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.debug = true // Enabled debug when first installing is always helpful - - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.debug = true options.sendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1 - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ logs - - // Enable logs to be sent to Sentry - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs } } ``` + - + -## Uncaught NSExceptions +## Send Logs -On macOS, the Sentry Apple SDK can't capture uncaught exceptions out of the box, therefore we recommend enabling `enableUncaughtNSExceptionReporting` in your `SentryOptions`. Alternatively, you can use the `SentryCrashExceptionApplication` class. Please visit capturing uncaught exceptions for more information. +Logs for Apple platforms require Sentry Cocoa SDK 8.55.0 or later. Starting with version 9.0.0, set `options.enableLogs = true` in the SDK initialization snippet above. For earlier versions, use `options.experimental.enableLogs = true` instead. See Set Up Logs for all logging methods and options. ```swift {tabTitle:Swift} -import Sentry +SentrySDK.logger.info("User example action completed") -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.enableUncaughtNSExceptionReporting = true -} +SentrySDK.logger.warn("Slow operation detected", attributes: [ + "operation": "data_fetch", + "duration": 3500 +]) ``` -```objc {tabTitle:Objective-C} -@import Sentry; -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.enableUncaughtNSExceptionReporting = YES; +```objc {tabTitle:Objective-C} +SentryLogger *logger = SentrySDK.logger; +[logger info:@"User example action completed"]; +[logger warn:@"Slow operation detected" attributes:@{ + @"operation": @"data_fetch", + @"duration": @3500 }]; ``` -## Verify +## Send Application Metrics -Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes. +Application Metrics are enabled by default. In Sentry Cocoa SDK 9.12.0 and later, use `SentrySDK.metrics` to send counters, gauges, and distributions. Metrics were experimental in versions 9.4.0–9.11.x. The metrics API is currently Swift-only. See Set Up Metrics for details. - - -To verify crashes, ensure you run your application without a debugger attached. Otherwise, the SDK won't capture the crash. +```swift {tabTitle:Swift} +SentrySDK.metrics.count(key: "checkout.failed", value: 1) - +SentrySDK.metrics.gauge(key: "time_since_refresh", value: 4, unit: .hour) -```swift {tabTitle:Swift} {mdExpandTabs} -import Sentry - -do { - try aMethodThatMightFail() -} catch { - SentrySDK.capture(error: error) -} +SentrySDK.metrics.distribution( + key: "api_latency", + value: 187, + unit: .millisecond, + attributes: ["endpoint": "/api/orders"] +) ``` -```objc {tabTitle:Objective-C} -@import Sentry; +## Verify Your Setup -NSError *error = nil; -[self aMethodThatMightFail:&error] +Capture a test error to confirm that your app is sending events to Sentry. You should see it in your project within a few minutes. -if (error) { - [SentrySDK captureError:error]; -} +```swift {tabTitle:Swift} +SentrySDK.capture(error: NSError(domain: "SentryTest", code: 1)) ``` +```objc {tabTitle:Objective-C} +[SentrySDK captureError:[NSError errorWithDomain:@"SentryTest" code:1 userInfo:nil]]; +``` ## Next Steps +At this point, you've integrated Sentry into your Apple application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn more about Sentry's Apple SDK features - Add readable stack traces to errors -- Add Apple Privacy manifest -## FAQ - - - -Yes, you can initialize the SDK from a background thread, but this is **not recommended**. Some initialization steps, like collecting view hierarchy information, must still run on the main thread. Initializing on the main thread also ensures reliable detection of app launch crashes. - - + From bed9c5c0f74b679dc1b81fba29f7a60950bb1649 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 15 Oct 2026 01:25:33 +0000 Subject: [PATCH 2/5] fix(docs): scope Apple quick-start features by platform Co-Authored-By: Shannon Anahata --- includes/apple-platform-getting-started.mdx | 27 +++++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/includes/apple-platform-getting-started.mdx b/includes/apple-platform-getting-started.mdx index 80c54a70eda87..bdc3c79ced186 100644 --- a/includes/apple-platform-getting-started.mdx +++ b/includes/apple-platform-getting-started.mdx @@ -66,22 +66,36 @@ To use another installation method, see the install -watchOS doesn't support crash detection. Use the snippet in [Verify Your Setup](#verify-your-setup) to capture handled errors. +On watchOS, Error Monitoring captures handled errors; crash detection isn't available. Use the snippet in [Verify Your Setup](#verify-your-setup) to capture a handled error. - + + +This guide also enables **Tracing**, **Profiling**, **Session Replay**, and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). + + -This guide also enables **Tracing** on iOS, macOS, tvOS, and visionOS. The snippets enable **Profiling** on iOS and macOS, **Session Replay** on iOS, and **Logs** on iOS, macOS, tvOS, and visionOS. Logs require an explicit option; Application Metrics are enabled by default and don't need extra configuration. See [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-) to use them. + + +This guide also enables **Tracing**, **Profiling**, and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). + + + + + +This guide also enables **Tracing** and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). -Application Metrics are enabled by default. watchOS doesn't support Tracing, Profiling, Session Replay, or Logs. +This guide also enables **Tracing**. Logs capturing isn't available on watchOS; see the watchOS feature limitations. +**Application Metrics** are enabled by default and don't need extra configuration. See [Send Application Metrics](#send-application-metrics-) to use them. + The snippets set `sendDefaultPii` to include IP addresses. Remove that option if you don't want to send this data. Remove other options for features you don't need. @@ -273,7 +287,7 @@ func application(_ application: UIApplication, ### Initialize the SDK -Initialize the SDK in your `WKExtensionDelegate.applicationDidFinishLaunching` method. watchOS doesn't support crash detection, most performance monitoring features, Profiling, Session Replay, or Logs. +Initialize the SDK in your `WKExtensionDelegate.applicationDidFinishLaunching` method. This snippet enables Tracing. ```swift import Sentry @@ -283,6 +297,9 @@ func applicationDidFinishLaunching() { options.dsn = "___PUBLIC_DSN___" options.debug = true options.sendDefaultPii = true + + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = 1.0 } } ``` From 0f97740fedf064a6e4234764026c4d8ea9076ff2 Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Wed, 28 Oct 2026 17:28:23 -0700 Subject: [PATCH 3/5] fix(docs): Correct Apple quickstart SDK guidance Document wizard omissions and return readers to the remaining setup steps. Align Apple quickstarts and linked feature, logging, and metrics guidance with the Cocoa SDK, and add tracing, symbol upload, and verification steps. --- .../apple/common/configuration/options.mdx | 10 +- .../platforms/apple/common/features/index.mdx | 7 +- .../apple/common/logs/cocoalumberjack.mdx | 3 +- docs/platforms/apple/common/logs/pulse.mdx | 3 +- .../platforms/apple/common/logs/swift-log.mdx | 3 +- .../apple/common/logs/swiftybeaver.mdx | 3 +- .../apple/guides/ios/features/index.mdx | 4 +- .../apple/guides/ios/manual-setup.mdx | 15 +- .../apple/guides/macos/features/index.mdx | 12 +- .../apple/guides/tvos/features/index.mdx | 6 +- .../apple/guides/visionos/features/index.mdx | 2 +- .../apple/guides/watchos/features/index.mdx | 4 +- includes/apple-platform-getting-started.mdx | 209 ++++++++++++++---- platform-includes/logs/options/apple.mdx | 59 +---- platform-includes/logs/requirements/apple.mdx | 2 + platform-includes/logs/setup/apple.mdx | 38 +--- platform-includes/metrics/options/apple.mdx | 23 +- .../metrics/requirements/apple.mdx | 2 +- platform-includes/metrics/usage/apple.mdx | 18 +- 19 files changed, 246 insertions(+), 177 deletions(-) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index 23897caff8c84..e6f2993048545 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -377,7 +377,9 @@ Learn more in the -When enabled, the SDK sends logs to Sentry. You must explicitly set this option to `true` to enable log capturing. +In SDK 9.0.0–9.26.x, set this option to `true` to send logs to Sentry. + +Since SDK 9.27.0, this option is deprecated and no longer gates calls to `SentrySDK.logger` or integrations that forward to it. Setting it to `false` doesn't drop those logs. Use `beforeSendLog` to filter logs instead. Learn more about structured logging in the logs documentation. @@ -1289,6 +1291,8 @@ This option is only used when is s When enabled, the SDK can send metrics to Sentry. Note that metrics are not collected automatically — you must manually call the `SentrySDK.metrics` API to record counters, gauges, and distributions. +Since SDK 9.27.0, this option is deprecated and no longer gates manual metric capture. To drop metrics, return `nil` from . + Learn more in the Metrics documentation. @@ -1361,13 +1365,13 @@ When enabled, the SDK uses a more efficient mechanism for detecting watchdog ter - + **Removed in version 9.12.0** — Metrics has graduated to GA. Use the top-level option instead. See [sentry-cocoa#7842](https://github.com/getsentry/sentry-cocoa/pull/7842). - + **Removed in version 9.12.0** — Metrics has graduated to GA. Use the top-level option instead. See [sentry-cocoa#7842](https://github.com/getsentry/sentry-cocoa/pull/7842). diff --git a/docs/platforms/apple/common/features/index.mdx b/docs/platforms/apple/common/features/index.mdx index c894573918c10..f8c9b3a926c30 100644 --- a/docs/platforms/apple/common/features/index.mdx +++ b/docs/platforms/apple/common/features/index.mdx @@ -56,9 +56,10 @@ All features listed below are **enabled by default** unless otherwise noted. Som - Release health tracks crash-free users and sessions - Session tracking automatically tracks user sessions for release health metrics -- Session Replay (only available on iOS 16+ and tvOS 16+) +- Session Replay (officially supported on iOS) - Requires SDK version 8.31.1 or later - - tvOS is not officially supported + - Supports the iOS versions supported by the SDK; no iOS 16 requirement + - May run on tvOS, which is not officially supported ## Event Enrichment @@ -77,7 +78,7 @@ All features listed below are **enabled by default** unless otherwise noted. Som ## Platform-Specific Features - MetricKit integration (only available on iOS 15+ and macOS 12+, requires enabling `enableMetricKit` option) -- Logs capturing (requires `enableLogs` option, only available on iOS, tvOS, visionOS, and macOS) +- Logs via `SentrySDK.logger` on all supported Apple platforms, including watchOS. SDK 9.27.0+ doesn't require an enable flag; earlier versions require configuration. ## Data Management diff --git a/docs/platforms/apple/common/logs/cocoalumberjack.mdx b/docs/platforms/apple/common/logs/cocoalumberjack.mdx index 92a3510e5216b..17ecd35fd599d 100644 --- a/docs/platforms/apple/common/logs/cocoalumberjack.mdx +++ b/docs/platforms/apple/common/logs/cocoalumberjack.mdx @@ -35,7 +35,7 @@ dependencies: [ ## Configure -Initialize the Sentry SDK with logs enabled, then add `SentryCocoaLumberjackLogger` to CocoaLumberjack: +Initialize the Sentry SDK, then add `SentryCocoaLumberjackLogger` to CocoaLumberjack. SDK 9.27.0+ doesn't require an enable flag for logs forwarded by this integration: ```swift import Sentry @@ -44,7 +44,6 @@ import SentryCocoaLumberjack SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true } // Only logs at .info level and above will be sent to Sentry diff --git a/docs/platforms/apple/common/logs/pulse.mdx b/docs/platforms/apple/common/logs/pulse.mdx index 806cff3e97f65..cc7501597c13b 100644 --- a/docs/platforms/apple/common/logs/pulse.mdx +++ b/docs/platforms/apple/common/logs/pulse.mdx @@ -35,7 +35,7 @@ dependencies: [ ## Configure -Initialize the Sentry SDK with logs enabled, then start the Pulse integration: +Initialize the Sentry SDK, then start the Pulse integration. SDK 9.27.0+ doesn't require an enable flag for logs forwarded by this integration: ```swift import Sentry @@ -44,7 +44,6 @@ import SentryPulse SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true } SentryPulse.start() diff --git a/docs/platforms/apple/common/logs/swift-log.mdx b/docs/platforms/apple/common/logs/swift-log.mdx index 0d530daeb8cf0..9a0917176e8e1 100644 --- a/docs/platforms/apple/common/logs/swift-log.mdx +++ b/docs/platforms/apple/common/logs/swift-log.mdx @@ -35,7 +35,7 @@ dependencies: [ ## Configure -Initialize the Sentry SDK with logs enabled, then register `SentryLogHandler` as your SwiftLog bootstrap: +Initialize the Sentry SDK, then register `SentryLogHandler` as your SwiftLog bootstrap. SDK 9.27.0+ doesn't require an enable flag for logs forwarded by this integration: ```swift import Sentry @@ -44,7 +44,6 @@ import SentrySwiftLog SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true } LoggingSystem.bootstrap { _ in diff --git a/docs/platforms/apple/common/logs/swiftybeaver.mdx b/docs/platforms/apple/common/logs/swiftybeaver.mdx index fbd67b0cdea5e..cf47a9e34c3df 100644 --- a/docs/platforms/apple/common/logs/swiftybeaver.mdx +++ b/docs/platforms/apple/common/logs/swiftybeaver.mdx @@ -35,7 +35,7 @@ dependencies: [ ## Configure -Initialize the Sentry SDK with logs enabled, then add `SentryDestination` to SwiftyBeaver: +Initialize the Sentry SDK, then add `SentryDestination` to SwiftyBeaver. SDK 9.27.0+ doesn't require an enable flag for logs forwarded by this integration: ```swift import Sentry @@ -44,7 +44,6 @@ import SentrySwiftyBeaver SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true } let log = SwiftyBeaver.self diff --git a/docs/platforms/apple/guides/ios/features/index.mdx b/docs/platforms/apple/guides/ios/features/index.mdx index 3193376e5953b..1a9c764848809 100644 --- a/docs/platforms/apple/guides/ios/features/index.mdx +++ b/docs/platforms/apple/guides/ios/features/index.mdx @@ -34,7 +34,7 @@ iOS supports comprehensive error detection: ## Logs -Logs capturing is available and requires the `enableLogs` option to be enabled. +Send logs with `SentrySDK.logger`. SDK 9.27.0+ doesn't require an enable flag; earlier versions require configuration. ## Performance Features Available on iOS @@ -51,7 +51,7 @@ iOS supports all performance monito Session Replay records user sessions for visual debugging, helping you understand what happened before, during, and after an error. -- Available on iOS 16+ +- Supports the iOS versions supported by the SDK; no iOS 16 requirement - Requires SDK version 8.31.1 or later - Enabled by setting `options.sessionReplay.sessionSampleRate` and/or `options.sessionReplay.onErrorSampleRate` to a value greater than `0` diff --git a/docs/platforms/apple/guides/ios/manual-setup.mdx b/docs/platforms/apple/guides/ios/manual-setup.mdx index 06854c1e5f13e..1a22751d9a244 100644 --- a/docs/platforms/apple/guides/ios/manual-setup.mdx +++ b/docs/platforms/apple/guides/ios/manual-setup.mdx @@ -16,7 +16,7 @@ We recommend installing the SDK with SPM, but we also support alternate [install https://github.com/getsentry/sentry-cocoa.git ``` -The Package has a few products you can depend on, but the recommended one is `Sentry`. For more details see the full docs on using [Swift Package Manager](/platforms/apple/guides/ios/install/swift-package-manager/). +Add one SDK product to your application target: `SentrySPM` to build from source (recommended), or `Sentry` to use the prebuilt static framework. Both use `import Sentry`. See [Swift Package Manager](/platforms/apple/guides/ios/install/swift-package-manager/) for more options. ## Configuration @@ -83,6 +83,7 @@ If you're using SwiftUI and your app doesn't implement an app delegate, initiali ```swift import Sentry +import SwiftUI @main struct SwiftUIApp: App { @@ -96,5 +97,17 @@ struct SwiftUIApp: App { options.tracesSampleRate = 1.0 } } + + var body: some Scene { + WindowGroup { + SentryTracedView("Home") { + Text("Hello, world!") + } + } + } } ``` + +Keep your existing app content inside `WindowGroup`. See [SwiftUI Instrumentation](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/) for view tracing options. + +These snippets configure Error Monitoring and Tracing. Continue with the [quickstart](/platforms/apple/guides/ios/#configure) to add Profiling, Session Replay, Logs, and Application Metrics, upload debug symbols, and verify your setup. Merge additional options into your existing SDK initialization rather than starting the SDK again. diff --git a/docs/platforms/apple/guides/macos/features/index.mdx b/docs/platforms/apple/guides/macos/features/index.mdx index dc51e9e11460d..97e69d529a357 100644 --- a/docs/platforms/apple/guides/macos/features/index.mdx +++ b/docs/platforms/apple/guides/macos/features/index.mdx @@ -5,7 +5,9 @@ sidebar_hidden: true description: "Learn about Sentry's Apple SDK features for macOS." --- -Sentry's Apple SDK for macOS enables automatic reporting of errors and exceptions, and identifies performance issues in your application. The minimum supported macOS version is 10.14. All features listed below are **enabled by default** unless otherwise noted. +Sentry's Apple SDK for macOS enables automatic reporting of errors and exceptions, and identifies performance issues in your application. + +SDK 9.25.0 and later require macOS 12 or later. Use an earlier SDK release if your app supports older macOS versions. All features listed below are **enabled by default** unless otherwise noted. @@ -54,7 +56,11 @@ For a complete list of all available features, see the performance monitoring: +macOS supports performance monitoring for operations you instrument in your app. + +Start a transaction around the operation you want to measure and bind it to the scope so automatic instrumentation can attach child spans. macOS apps don't automatically create UIKit screen-load transactions. See Custom Instrumentation or SwiftUI Instrumentation. + +Automatic child spans include: - Network request monitoring for HTTP request performance - File I/O performance tracking for file operations @@ -87,7 +93,7 @@ For macOS apps using UIKit (Mac Catalyst), the following features are also avail ## Other Features - Swift Async/Await support for automatically stitching together stack traces of Swift concurrency code -- Logs capturing available (requires `enableLogs` option) +- Logs via `SentrySDK.logger` (no enable flag required in SDK 9.27.0+) - Offline caching when a device is unable to connect; we send a report once we receive another event ## macOS Limitations diff --git a/docs/platforms/apple/guides/tvos/features/index.mdx b/docs/platforms/apple/guides/tvos/features/index.mdx index 76eb45b6b8bbf..d8e838fb66856 100644 --- a/docs/platforms/apple/guides/tvos/features/index.mdx +++ b/docs/platforms/apple/guides/tvos/features/index.mdx @@ -30,11 +30,11 @@ tvOS has some limitations compared to iOS: -Session Replay works on tvOS 16+, but it is only officially supported on iOS. While the feature may function on tvOS, we cannot guarantee its reliability or provide full support for tvOS-specific issues. +Session Replay may run on tvOS, but it is only officially supported on iOS. While the feature may function on tvOS, we cannot guarantee its reliability or provide full support for tvOS-specific issues. -- Works on tvOS 16+ (not officially supported) +- May run on tvOS (not officially supported) - Requires SDK version 8.31.1 or later ### Performance Monitoring @@ -72,7 +72,7 @@ tvOS supports comprehensive error detection: - Release health tracks crash-free users and sessions - Offline caching when a device is unable to connect; we send a report once we receive another event - Swift Async/Await support for automatically stitching together stack traces of Swift concurrency code -- Logs capturing available (requires `enableLogs` option) +- Logs via `SentrySDK.logger` (no enable flag required in SDK 9.27.0+) - User Feedback via programmatic API (no UI available) For configuration options and detailed documentation, see the Configuration section. diff --git a/docs/platforms/apple/guides/visionos/features/index.mdx b/docs/platforms/apple/guides/visionos/features/index.mdx index e5c46af0da4f1..d69ca9f5ed0f5 100644 --- a/docs/platforms/apple/guides/visionos/features/index.mdx +++ b/docs/platforms/apple/guides/visionos/features/index.mdx @@ -66,7 +66,7 @@ visionOS supports comprehensive error detection: - Release health tracks crash-free users and sessions - Offline caching when a device is unable to connect; we send a report once we receive another event - Swift Async/Await support for automatically stitching together stack traces of Swift concurrency code -- Logs capturing available (requires `enableLogs` option) +- Logs via `SentrySDK.logger` (no enable flag required in SDK 9.27.0+) - User Feedback via programmatic API (no UI available) For configuration options and detailed documentation, see the Configuration section. diff --git a/docs/platforms/apple/guides/watchos/features/index.mdx b/docs/platforms/apple/guides/watchos/features/index.mdx index 045b2f1278477..0b97c8f6cdffe 100644 --- a/docs/platforms/apple/guides/watchos/features/index.mdx +++ b/docs/platforms/apple/guides/watchos/features/index.mdx @@ -28,7 +28,6 @@ watchOS has significant limitations due to platform restrictions: - View Hierarchy capture not available - Profiling not available - MetricKit integration not available -- Logs capturing not available - Most performance monitoring features not available - Limited symbolication support @@ -59,6 +58,9 @@ Despite the limitations, watchOS still supports several useful features: ### Other Features +- Logs via `SentrySDK.logger` (no enable flag required in SDK 9.27.0+) +- Application Metrics via `SentrySDK.metrics` (stable since SDK 9.12.0) +- Manual tracing for operations you instrument in your app - Swift Async/Await support for automatically stitching together stack traces of Swift concurrency code (when applicable) - User Feedback via programmatic API (no UI available) diff --git a/includes/apple-platform-getting-started.mdx b/includes/apple-platform-getting-started.mdx index bdc3c79ced186..140f10e9bac57 100644 --- a/includes/apple-platform-getting-started.mdx +++ b/includes/apple-platform-getting-started.mdx @@ -18,44 +18,98 @@ Support for [visionOS](https://developer.apple.com/visionos/) is experimental an +## Prerequisites + +The examples below use Sentry Cocoa SDK 9.27.0 or later. Minimum OS versions for SDK 9.25.0 and later are: + + + +- iOS 15.0 + + + + + +- macOS 12.0 + + + + + +- tvOS 15.0 + + + + + +- visionOS 1.0 + + + + + +- watchOS 9.0 + + + +If your app supports older OS versions, use a compatible earlier SDK release. See the migration guides for version-specific requirements. + ## Install -Sentry captures data by using an SDK within your application's runtime. We recommend installing the SDK with Swift Package Manager (SPM). In Xcode, open **File > Add Packages**, then enter this repository URL: - -``` -https://github.com/getsentry/sentry-cocoa.git -``` +Sentry captures data by using an SDK within your application's runtime. We recommend installing the SDK with Swift Package Manager (SPM). -For iOS, you can install and configure the SDK with the [Sentry Wizard](https://github.com/getsentry/sentry-wizard). Run this command from your project directory: +### Automatic Install + +The [Sentry Wizard](https://github.com/getsentry/sentry-wizard) installs the SDK and adds an initial configuration. Run this command from your project directory: ```bash brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios ``` -The wizard patches your project with the SDK configuration and adds the patched files to your version control. To set up the SDK manually, see Manual Setup or continue below. +Review and commit the files the wizard modifies. - Install the Sentry SDK with Swift Package Manager -- Update your `AppDelegate` or SwiftUI app initializer with the default Sentry configuration and an example error -- Add an `Upload Debug Symbols` phase to your `xcodebuild` build script +- Update your `AppDelegate` or SwiftUI app initializer with the initial Sentry configuration and an example message +- Add an `Upload Debug Symbols` build phase to your Xcode target - Create `.sentryclirc` with an auth token for uploading debug symbols (the file is added to `.gitignore`) - Add a Fastlane lane for uploading debug symbols if you're using Fastlane - +**Return to this guide after running the wizard to complete setup.** The wizard doesn't configure Session Replay, instrument your SwiftUI views, or add application-specific logs and metrics. + +Continue with [Configure](#configure), merge the settings into the existing `SentrySDK.start` call, and follow the remaining steps to send and verify your data. + +Wizard 9.0.0 also needs these corrections when used with the SDK versions in this guide: + +- Remove `options.experimental.enableLogs` if the wizard adds it. SDK 9.27.0+ sends logs through `SentrySDK.logger` without an enable flag. +- In Objective-C, replace `SentryProfilingLifecycleTrace` with `SentryProfileLifecycleTrace`. - +### Manual Install -To use another installation method, see the installation options. +To install without the wizard, follow the SPM instructions below. If you used the wizard, skip to [Configure](#configure). For more detail, see Manual Setup. +In Xcode, open **File > Add Package Dependencies**, then enter this repository URL: + +``` +https://github.com/getsentry/sentry-cocoa.git +``` + +Select a compatible SDK version and add **one** SDK product to your application target: + +- **SentrySPM** builds the SDK from source and is the recommended choice. +- **Sentry** uses the prebuilt static framework. + +Both products use `import Sentry`. See Swift Package Manager for other products, or the installation options for other installation methods. + ## Configure @@ -72,40 +126,43 @@ On watchOS, Error Monitoring captures handled errors; crash detection isn't avai -This guide also enables **Tracing**, **Profiling**, **Session Replay**, and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). +This guide also configures **Tracing**, **Profiling**, and **Session Replay**, and shows you how to send **Logs**. -This guide also enables **Tracing**, **Profiling**, and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). +This guide also configures **Tracing** and **Profiling**, and shows you how to send **Logs**. -This guide also enables **Tracing** and **Logs**. Logs require an explicit option; see [Send Logs](#send-logs). +This guide also configures **Tracing** and shows you how to send **Logs**. -This guide also enables **Tracing**. Logs capturing isn't available on watchOS; see the watchOS feature limitations. +This guide also configures **Tracing** and shows you how to send **Logs**. See the watchOS feature limitations for other platform restrictions. -**Application Metrics** are enabled by default and don't need extra configuration. See [Send Application Metrics](#send-application-metrics-) to use them. +**Application Metrics** are enabled by default, but aren't collected automatically. See [Send Application Metrics](#send-application-metrics-) to record your own metrics. The snippets set `sendDefaultPii` to include IP addresses. Remove that option if you don't want to send this data. Remove other options for features you don't need. +Initialize the SDK **on the main thread**, as early as possible. Set `debug` to `false` or remove it after setup, and reduce sampling rates before using the configuration in production. + ### Initialize the SDK -To capture errors, initialize the SDK as early as possible, such as in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method or your SwiftUI `App` initializer. Session Replay is available on iOS 16+ with Sentry Cocoa SDK 8.31.1+; UI Profiling requires SDK 8.49.0+. +Initialize the SDK in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method or your SwiftUI `App` initializer. Session Replay requires Sentry Cocoa SDK 8.31.1+ and supports the iOS versions supported by that SDK; it doesn't require iOS 16. UI Profiling requires SDK 8.49.0+. ```swift {tabTitle:Swift} {mdExpandTabs} import Sentry +import UIKit func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { @@ -126,9 +183,6 @@ func application(_ application: UIApplication, // Enable Session Replay. options.sessionReplay.onErrorSampleRate = 1.0 options.sessionReplay.sessionSampleRate = 0.1 - - // Enable Logs. - options.enableLogs = true } return true } @@ -155,9 +209,6 @@ func application(_ application: UIApplication, // Enable Session Replay. options.sessionReplay.onErrorSampleRate = 1.0; options.sessionReplay.sessionSampleRate = 0.1; - - // Enable Logs. - options.enableLogs = YES; }]; return YES; } @@ -165,6 +216,7 @@ func application(_ application: UIApplication, ```swift {tabTitle:SwiftUI with App conformer} import Sentry +import SwiftUI @main struct ExampleApp: App { @@ -180,19 +232,28 @@ struct ExampleApp: App { } options.sessionReplay.onErrorSampleRate = 1.0 options.sessionReplay.sessionSampleRate = 0.1 - options.enableLogs = true + } + } + + var body: some Scene { + WindowGroup { + SentryTracedView("Home") { + Text("Hello, world!") + } } } } ``` +For SwiftUI, keep your existing app content inside `WindowGroup` and wrap the views you want to measure with `SentryTracedView`, as shown above. See SwiftUI Instrumentation for more options. + ### Initialize the SDK -Initialize the SDK as early as possible when your application starts. The snippet enables Tracing, Profiling, and Logs. UI Profiling requires Sentry Cocoa SDK 8.49.0+. macOS doesn't support Session Replay. +Initialize the SDK in your app delegate's `applicationDidFinishLaunching(_:)` method or your SwiftUI `App` initializer. The snippet configures Tracing and Profiling. UI Profiling requires Sentry Cocoa SDK 8.49.0+. macOS doesn't support Session Replay. ```swift {tabTitle:Swift} import Sentry @@ -211,9 +272,6 @@ SentrySDK.start { options in $0.lifecycle = .trace $0.sessionSampleRate = 1.0 } - - // Enable Logs. - options.enableLogs = true } ``` @@ -230,11 +288,12 @@ SentrySDK.start { options in profiling.lifecycle = SentryProfileLifecycleTrace; profiling.sessionSampleRate = 1.0; }; - options.enableLogs = YES; }]; ``` -On macOS, the SDK can't capture uncaught exceptions without additional configuration. The snippets enable `enableUncaughtNSExceptionReporting`. For other options, see capturing uncaught exceptions. +On macOS, the SDK can't capture uncaught exceptions without additional configuration. The snippets enable `enableUncaughtNSExceptionReporting`, which also sets `NSApplicationCrashOnExceptions` so the app crashes on an uncaught exception. + +Don't combine this option with `SentryCrashExceptionApplication`, which can cause duplicate reports. See capturing uncaught exceptions for details. @@ -242,16 +301,17 @@ On macOS, the SDK can't capture uncaught exceptions without additional configura ### Initialize the SDK -Initialize the SDK as early as possible, such as in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method. The snippets enable Tracing and Logs. Profiling isn't available on tvOS or visionOS. +Initialize the SDK in your app delegate's `application(_:didFinishLaunchingWithOptions:)` method or your SwiftUI `App` initializer. The snippets configure Tracing. Profiling isn't available on tvOS or visionOS. -Session Replay may run on tvOS 16+, but it's only officially supported on iOS. This guide doesn't configure it on tvOS. +Session Replay may run on tvOS, but it's only officially supported on iOS. This guide doesn't configure it on tvOS. ```swift {tabTitle:Swift} {mdExpandTabs} import Sentry +import UIKit func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { @@ -260,7 +320,6 @@ func application(_ application: UIApplication, options.debug = true options.sendDefaultPii = true options.tracesSampleRate = 1.0 - options.enableLogs = true } return true } @@ -275,7 +334,6 @@ func application(_ application: UIApplication, options.debug = YES; options.sendDefaultPii = YES; options.tracesSampleRate = @1.0; - options.enableLogs = YES; }]; return YES; } @@ -287,7 +345,7 @@ func application(_ application: UIApplication, ### Initialize the SDK -Initialize the SDK in your `WKExtensionDelegate.applicationDidFinishLaunching` method. This snippet enables Tracing. +Initialize the SDK in your `WKExtensionDelegate.applicationDidFinishLaunching` method or your SwiftUI `App` initializer. This snippet configures Tracing. ```swift import Sentry @@ -306,13 +364,53 @@ func applicationDidFinishLaunching() { - +### Send a Test Trace + +Sampling settings determine which transactions to send; they don't create transactions. Start a transaction around an operation in your app and finish it when the operation completes: + +```swift {tabTitle:Swift} {mdExpandTabs} +let transaction = SentrySDK.startTransaction( + name: "Example Operation", + operation: "task", + bindToScope: true +) + +// Perform the operation you want to measure. + +transaction.finish() +``` + +```objc {tabTitle:Objective-C} +id transaction = [SentrySDK startTransactionWithName:@"Example Operation" + operation:@"task" + bindToScope:YES]; + +// Perform the operation you want to measure. + +[transaction finish]; +``` + +For asynchronous work, finish the transaction in the completion handler. Binding a transaction to the scope lets automatic instrumentation, such as HTTP tracing, attach child spans to it. + + + +macOS and watchOS don't automatically create UIKit screen-load or app-start transactions. Add transactions around operations you want to measure, as shown above, or instrument your views with SwiftUI Instrumentation. + + + + + +With the `.trace` profiling lifecycle used above, profiling runs while sampled root spans are active. Configure and start a transaction to collect profiles; setting a profile sample rate alone doesn't start the profiler. See Set Up Apple Profiling for other lifecycles. + + ## Send Logs -Logs for Apple platforms require Sentry Cocoa SDK 8.55.0 or later. Starting with version 9.0.0, set `options.enableLogs = true` in the SDK initialization snippet above. For earlier versions, use `options.experimental.enableLogs = true` instead. See Set Up Logs for all logging methods and options. +Use `SentrySDK.logger` after initializing the SDK to send logs on all supported Apple platforms, including watchOS. In SDK 9.27.0+, these calls don't require an enable flag. -```swift {tabTitle:Swift} +For SDK 9.0.0–9.26.x, set `options.enableLogs = true` during initialization. For SDK 8.55.0–8.x, use `options.experimental.enableLogs = true`. See Set Up Logs for logging methods and options. + +```swift {tabTitle:Swift} {mdExpandTabs} SentrySDK.logger.info("User example action completed") SentrySDK.logger.warn("Slow operation detected", attributes: [ @@ -330,11 +428,13 @@ SentryLogger *logger = SentrySDK.logger; }]; ``` - +To stop sending logs, remove the logging calls or filter them with `beforeSendLog`. In SDK 9.27.0+, setting `enableLogs` to `false` doesn't drop logs sent through this API. ## Send Application Metrics -Application Metrics are enabled by default. In Sentry Cocoa SDK 9.12.0 and later, use `SentrySDK.metrics` to send counters, gauges, and distributions. Metrics were experimental in versions 9.4.0–9.11.x. The metrics API is currently Swift-only. See Set Up Metrics for details. +Application Metrics are enabled by default, but you must record them explicitly. In Sentry Cocoa SDK 9.12.0 and later, use `SentrySDK.metrics` to send counters, gauges, and distributions. Metrics were experimental in versions 9.2.0–9.11.x. + +`SentrySDK.metrics` is a Swift API. Objective-C projects can use `SentryObjCSDK.metrics` through the separate `SentryObjC` integration, available since SDK 9.16.0. See Set Up Metrics for usage and filtering options. ```swift {tabTitle:Swift} SentrySDK.metrics.count(key: "checkout.failed", value: 1) @@ -349,11 +449,24 @@ SentrySDK.metrics.distribution( ) ``` +## Upload Debug Symbols + +Upload your app's debug symbols (dSYMs) so Sentry can show function names and source locations in stack traces. Follow Uploading Debug Symbols to configure uploads for your builds. + + + +If you used the wizard, it already added an upload build phase. Check that uploads succeed, and set `SENTRY_AUTH_TOKEN` in your CI environment so CI builds can upload symbols too. + + + ## Verify Your Setup -Capture a test error to confirm that your app is sending events to Sentry. You should see it in your project within a few minutes. +Capture a handled test error after initializing the SDK. You should see it in your Sentry project's Issues page within a few minutes. + +```swift {tabTitle:Swift} {mdExpandTabs} +import Foundation +import Sentry -```swift {tabTitle:Swift} SentrySDK.capture(error: NSError(domain: "SentryTest", code: 1)) ``` @@ -361,11 +474,19 @@ SentrySDK.capture(error: NSError(domain: "SentryTest", code: 1)) [SentrySDK captureError:[NSError errorWithDomain:@"SentryTest" code:1 userInfo:nil]]; ``` + + +This verifies handled-error delivery. To test crash reporting, run your app **without a debugger attached**, trigger a test crash, then relaunch the app so the SDK can send the report. See Capturing Errors for more ways to capture events. + + + ## Next Steps At this point, you've integrated Sentry into your Apple application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Add readable stack traces to errors +- + Explore the SDK's features and platform limitations + diff --git a/platform-includes/logs/options/apple.mdx b/platform-includes/logs/options/apple.mdx index 3f3401c4c8f34..86904adb99d3f 100644 --- a/platform-includes/logs/options/apple.mdx +++ b/platform-includes/logs/options/apple.mdx @@ -4,7 +4,7 @@ To filter logs, or update them before they are sent to Sentry, you can use the ` -Starting with version 9.0.0, structured logging is no longer experimental. The option moved from `options.experimental.enableLogs` to `options.enableLogs`. +In SDK 9.27.0+, manual logging doesn't require an enable flag. To drop logs, return `nil` from `beforeSendLog`; setting `enableLogs` to `false` doesn't drop them. For older SDKs, also enable logging as described in [Setup](#setup). @@ -13,7 +13,6 @@ import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true options.beforeSendLog = { log in if log.level == .info { @@ -30,7 +29,6 @@ SentrySDK.start { options in [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.enableLogs = YES; options.beforeSendLog = ^SentryLog* (SentryLog *log) { if (log.level == SentryLogLevelInfo) { @@ -47,10 +45,9 @@ SentrySDK.start { options in [SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.enableLogs = YES; - options.beforeSendLog = ^SentryLog* (SentryLog *log) { - if (log.level == SentryLogLevelInfo) { + options.beforeSendLog = ^SentryObjCLog* (SentryObjCLog *log) { + if (log.level == SentryObjCLogLevelInfo) { // Filter out all info logs return nil; } @@ -59,56 +56,6 @@ SentrySDK.start { options in }]; ``` -Before 9.0.0: - -```swift {tabTitle:Swift} -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.experimental.enableLogs = true - - options.beforeSendLog = { log in - if log.level == .info { - return nil - } - return log - } -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.experimental.enableLogs = YES; - - options.beforeSendLog = ^SentryLog* (SentryLog *log) { - if (log.level == SentryLogLevelInfo) { - return nil; - } - return log; - }; -}]; -``` - -```objc {tabTitle:Objective-C (SentryObjC)} -#import - -[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.experimental.enableLogs = YES; - - options.beforeSendLog = ^SentryLog* (SentryLog *log) { - if (log.level == SentryLogLevelInfo) { - return nil; - } - return log; - }; -}]; -``` - The `beforeSendLog` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `nil` if you want to discard it. The log object has the following properties: diff --git a/platform-includes/logs/requirements/apple.mdx b/platform-includes/logs/requirements/apple.mdx index c7e52e3d3acad..20a636f76eeb6 100644 --- a/platform-includes/logs/requirements/apple.mdx +++ b/platform-includes/logs/requirements/apple.mdx @@ -1 +1,3 @@ Logs for Apple platforms are supported in Sentry Cocoa SDK version `8.55.0` and above. Starting with version `9.0.0`, structured logging is no longer experimental and is part of the stable API. + +Manual logging is available on all supported Apple platforms, including watchOS. Starting with SDK `9.27.0`, calls to `SentrySDK.logger` don't require an enable flag. Earlier versions require the option described in [Setup](#setup). diff --git a/platform-includes/logs/setup/apple.mdx b/platform-includes/logs/setup/apple.mdx index 331c97b8ae366..f04b3f7a8f8c6 100644 --- a/platform-includes/logs/setup/apple.mdx +++ b/platform-includes/logs/setup/apple.mdx @@ -1,11 +1,10 @@ -To enable logging, set the `enableLogs` option to `true`. +Initialize the SDK, then use `SentrySDK.logger` to send logs. In SDK 9.27.0 and later, manual logging doesn't require an enable flag. ```swift {tabTitle:Swift} import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableLogs = true } ``` @@ -14,7 +13,6 @@ SentrySDK.start { options in [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.enableLogs = YES; }]; ``` @@ -23,36 +21,14 @@ SentrySDK.start { options in [SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.enableLogs = YES; }]; ``` -Before 9.0.0, this option was experimental: +For older SDK versions, add the appropriate option inside the initialization block: -```swift {tabTitle:Swift} -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - // Enable logs to be sent to Sentry - options.experimental.enableLogs = true -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.experimental.enableLogs = YES; -}]; -``` +| SDK Version | Swift | Objective-C | +| ------------ | ---------------------------------------- | ---------------------------------------- | +| 9.0.0–9.26.x | `options.enableLogs = true` | `options.enableLogs = YES;` | +| 8.55.0–8.x | `options.experimental.enableLogs = true` | `options.experimental.enableLogs = YES;` | -```objc {tabTitle:Objective-C (SentryObjC)} -#import - -[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.experimental.enableLogs = YES; -}]; -``` +In SDK 9.27.0+, `enableLogs` is deprecated. Setting it to `false` doesn't drop logs sent through `SentrySDK.logger` or integrations that forward to it. Use `beforeSendLog` to filter logs. diff --git a/platform-includes/metrics/options/apple.mdx b/platform-includes/metrics/options/apple.mdx index 3414915419119..8daad4f90e945 100644 --- a/platform-includes/metrics/options/apple.mdx +++ b/platform-includes/metrics/options/apple.mdx @@ -1,36 +1,33 @@ The Sentry Cocoa SDK provides several options to configure how metrics are captured and sent to Sentry. -### Enabling/Disabling Metrics +### Enabling and Disabling Metrics -Metrics are enabled by default, but are not collected automatically. You must manually call the `SentrySDK.metrics` API to record metrics. If you need to disable metrics entirely, set `options.enableMetrics` to `false` when initializing the SDK: +Metrics are enabled by default, but are not collected automatically. Call the `SentrySDK.metrics` API to record metrics. + +Starting with SDK 9.27.0, manual metric calls aren't gated by `enableMetrics`; the option is deprecated. To stop sending metrics, remove the recording calls or drop them with `beforeSendMetric`: ```swift {tabTitle:Swift} import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableMetrics = false // Metrics are enabled by default + options.beforeSendMetric = { _ in nil } } ``` -```objc {tabTitle:Objective-C} -@import Sentry; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.enableMetrics = NO; // Metrics are enabled by default -}]; -``` - ```objc {tabTitle:Objective-C (SentryObjC)} #import [SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.enableMetrics = NO; // Metrics are enabled by default + options.beforeSendMetric = ^SentryObjCMetric *(SentryObjCMetric *metric) { + return nil; + }; }]; ``` +For SDK 9.12.0–9.26.x, `options.enableMetrics = false` disables metrics. Before 9.12.0, use `options.experimental.enableMetrics = false`. + ### Filtering and Modifying Metrics Use the `beforeSendMetric` callback to filter or modify metrics before they're sent to Sentry. This is useful for: diff --git a/platform-includes/metrics/requirements/apple.mdx b/platform-includes/metrics/requirements/apple.mdx index 297bd79607598..dc04706727411 100644 --- a/platform-includes/metrics/requirements/apple.mdx +++ b/platform-includes/metrics/requirements/apple.mdx @@ -1 +1 @@ -Metrics are supported in Sentry Cocoa SDK version `9.12.0` and above (previously experimental since `9.4.0`). +Metrics are supported in Sentry Cocoa SDK version `9.12.0` and above (previously experimental since `9.2.0`). Objective-C projects can use the separate `SentryObjC` integration in SDK `9.16.0` and above. diff --git a/platform-includes/metrics/usage/apple.mdx b/platform-includes/metrics/usage/apple.mdx index 04313282bcfb7..405f36acb7e05 100644 --- a/platform-includes/metrics/usage/apple.mdx +++ b/platform-includes/metrics/usage/apple.mdx @@ -2,9 +2,15 @@ Once the SDK is initialized, you can send metrics using the `SentrySDK.metrics` The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge` and `distribution`. - -Objective-C support for metrics is not currently available. If you need Objective-C support, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues) to show demand for this feature. - +`SentrySDK.metrics` is a Swift API. For Objective-C, install the separate SentryObjC integration, available since SDK 9.16.0, and initialize it with `SentryObjCSDK`. Then record metrics through its wrapper API: + +```objc {tabTitle:Objective-C (SentryObjC)} +#import + +[SentryObjCSDK.metrics countWithKey:@"checkout.failed" value:1]; +[SentryObjCSDK.metrics gaugeWithKey:@"queue_depth" value:42.0]; +[SentryObjCSDK.metrics distributionWithKey:@"api_latency" value:187.0]; +``` ### Counter @@ -20,11 +26,10 @@ import Sentry // Simple counter SentrySDK.metrics.count(key: "button_click", value: 1) -// Counter with unit and attributes +// Counter with attributes SentrySDK.metrics.count( key: "network.request.count", value: 1, - unit: .generic("request"), attributes: ["endpoint": "/api/users", "method": "POST"] ) ``` @@ -96,7 +101,6 @@ import Sentry SentrySDK.metrics.count( key: "button_click", value: 1, - unit: nil, attributes: [ "browser": "Firefox", // String - passed directly "app_version": "1.0.0", // String - passed directly @@ -113,7 +117,7 @@ The `SentryAttributeValue` protocol ensures that all these types are automatical ### Specifying Units -All metric types (`count`, `gauge`, and `distribution`) support the optional `unit` parameter. Units help Sentry display metric values in a human-readable format. +Gauges and distributions support the optional `unit` parameter. Counters don't support units. Units help Sentry display metric values in a human-readable format. The SDK provides the `SentryUnit` enum with type-safe unit values: From 9540908082a8f923c10ac4ef9a4149d2628039cd Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Mon, 2 Nov 2026 13:19:00 -0800 Subject: [PATCH 4/5] Update docs/platforms/apple/common/features/index.mdx Co-authored-by: Philip Niedertscheider --- docs/platforms/apple/common/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/features/index.mdx b/docs/platforms/apple/common/features/index.mdx index f8c9b3a926c30..ae695db9f6c6a 100644 --- a/docs/platforms/apple/common/features/index.mdx +++ b/docs/platforms/apple/common/features/index.mdx @@ -59,7 +59,7 @@ All features listed below are **enabled by default** unless otherwise noted. Som - Session Replay (officially supported on iOS) - Requires SDK version 8.31.1 or later - Supports the iOS versions supported by the SDK; no iOS 16 requirement - - May run on tvOS, which is not officially supported + - May run on tvOS and visionOS, which are not officially supported ## Event Enrichment From 1037b08645df6d13fa4086aedebc16ac3959ff3c Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Tue, 3 Nov 2026 13:36:51 -0800 Subject: [PATCH 5/5] fix(docs): Address Apple quickstart review feedback Restore the background-thread initialization FAQ in troubleshooting and link it from the quickstarts. Remove redundant UIKit imports and describe SentryObjC as a framework. --- docs/platforms/apple/common/troubleshooting/index.mdx | 6 ++++++ includes/apple-platform-getting-started.mdx | 8 ++++---- platform-includes/metrics/requirements/apple.mdx | 2 +- platform-includes/metrics/usage/apple.mdx | 2 +- 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/platforms/apple/common/troubleshooting/index.mdx b/docs/platforms/apple/common/troubleshooting/index.mdx index 497546accd699..a6347e3013cdd 100644 --- a/docs/platforms/apple/common/troubleshooting/index.mdx +++ b/docs/platforms/apple/common/troubleshooting/index.mdx @@ -5,6 +5,12 @@ sidebar_order: 9000 sidebar_section: configuration --- +## Can I Initialize the SDK From a Background Thread? + +Yes, but we recommend initializing the SDK on the main thread as early as possible. When you call `SentrySDK.start` from a background thread, the SDK starts asynchronously on the main thread because some initialization steps, such as collecting view hierarchy information, require it. + +Initializing early also helps capture app launch crashes on platforms that support crash reporting. + ## "Missing API declaration" after App Store review Starting May 1, 2024, Apple requires all apps submitted to the App Store to provide a list of privacy-related APIs they use, including the reasons under which they use it. If you received an email from Apple with the message "ITMS-91053: Missing API declaration", your app doesn't fulfill the requirements. To solve this, follow our [Apple Privacy Manifest](/platforms/apple/data-management/apple-privacy-manifest/) guide. diff --git a/includes/apple-platform-getting-started.mdx b/includes/apple-platform-getting-started.mdx index 140f10e9bac57..f707e948d9d26 100644 --- a/includes/apple-platform-getting-started.mdx +++ b/includes/apple-platform-getting-started.mdx @@ -152,7 +152,9 @@ This guide also configures **Tracing** and shows you how to send **Logs**. See t The snippets set `sendDefaultPii` to include IP addresses. Remove that option if you don't want to send this data. Remove other options for features you don't need. -Initialize the SDK **on the main thread**, as early as possible. Set `debug` to `false` or remove it after setup, and reduce sampling rates before using the configuration in production. +We recommend initializing the SDK **on the main thread**, as early as possible. See the background-thread initialization FAQ for details. + +Set `debug` to `false` or remove it after setup, and reduce sampling rates before using the configuration in production. @@ -162,7 +164,6 @@ Initialize the SDK in your app delegate's `application(_:didFinishLaunchingWithO ```swift {tabTitle:Swift} {mdExpandTabs} import Sentry -import UIKit func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { @@ -311,7 +312,6 @@ Session Replay may run on tvOS, but it's only officially supported on iOS. This ```swift {tabTitle:Swift} {mdExpandTabs} import Sentry -import UIKit func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { @@ -434,7 +434,7 @@ To stop sending logs, remove the logging calls or filter them with Set Up Metrics for usage and filtering options. +`SentrySDK.metrics` is a Swift API. Objective-C projects can use `SentryObjCSDK.metrics` through the separate `SentryObjC` framework, available since SDK 9.16.0. See Set Up Metrics for usage and filtering options. ```swift {tabTitle:Swift} SentrySDK.metrics.count(key: "checkout.failed", value: 1) diff --git a/platform-includes/metrics/requirements/apple.mdx b/platform-includes/metrics/requirements/apple.mdx index dc04706727411..1b31506ed941e 100644 --- a/platform-includes/metrics/requirements/apple.mdx +++ b/platform-includes/metrics/requirements/apple.mdx @@ -1 +1 @@ -Metrics are supported in Sentry Cocoa SDK version `9.12.0` and above (previously experimental since `9.2.0`). Objective-C projects can use the separate `SentryObjC` integration in SDK `9.16.0` and above. +Metrics are supported in Sentry Cocoa SDK version `9.12.0` and above (previously experimental since `9.2.0`). Objective-C projects can use the separate `SentryObjC` framework in SDK `9.16.0` and above. diff --git a/platform-includes/metrics/usage/apple.mdx b/platform-includes/metrics/usage/apple.mdx index 405f36acb7e05..38ad2921a0d10 100644 --- a/platform-includes/metrics/usage/apple.mdx +++ b/platform-includes/metrics/usage/apple.mdx @@ -2,7 +2,7 @@ Once the SDK is initialized, you can send metrics using the `SentrySDK.metrics` The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge` and `distribution`. -`SentrySDK.metrics` is a Swift API. For Objective-C, install the separate SentryObjC integration, available since SDK 9.16.0, and initialize it with `SentryObjCSDK`. Then record metrics through its wrapper API: +`SentrySDK.metrics` is a Swift API. For Objective-C, install the separate SentryObjC framework, available since SDK 9.16.0, and initialize it with `SentryObjCSDK`. Then record metrics through its wrapper API: ```objc {tabTitle:Objective-C (SentryObjC)} #import