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..ae695db9f6c6a 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 and visionOS, which are 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/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/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 fb4e52304e2f5..f707e948d9d26 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,179 @@ 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 +## Prerequisites - +The examples below use Sentry Cocoa SDK 9.27.0 or later. Minimum OS versions for SDK 9.25.0 and later are: -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/). + + +- iOS 15.0 - + -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). +- macOS 12.0 -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. + -## Install +- 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. -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. + - +## Install -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: +Sentry captures data by using an SDK within your application's runtime. We recommend installing the SDK with Swift Package Manager (SPM). -``` -https://github.com/getsentry/sentry-cocoa.git -``` + - +### Automatic Install - -We recommend installing the SDK through our [Sentry Wizard](https://github.com/getsentry/sentry-wizard) by running the following command inside your project directory: +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 ``` -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). +Review and commit the files the wizard modifies. -- 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 +- Install the Sentry SDK with Swift Package Manager +- 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 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 - + -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: +**Error Monitoring** starts working as soon as you initialize the SDK. - + + +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 configures **Tracing**, **Profiling**, and **Session Replay**, and shows you how to send **Logs**. + + + + + +This guide also configures **Tracing** and **Profiling**, and shows you how to send **Logs**. + + + + + +This guide also configures **Tracing** and shows you how to send **Logs**. + + + + + +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, 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. + +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. + + + +### Initialize the SDK + +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 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 - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs } - return true } ``` @@ -140,203 +193,159 @@ 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 - options.enableLogs = YES; - // ___PRODUCT_OPTION_END___ logs }]; - return YES; } ``` ```swift {tabTitle:SwiftUI with App conformer} import Sentry +import SwiftUI @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 + 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. -```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 +### Initialize the SDK - // 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 +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. - // 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 +```swift {tabTitle:Swift} +import Sentry - options.configureProfiling = { - $0.lifecycle = .trace - $0.sessionSampleRate = 1 - } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.debug = true + options.sendDefaultPii = true + options.enableUncaughtNSExceptionReporting = true - // Enable logs to be sent to Sentry - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs - } + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = 1.0 - return true + // Enable Profiling. + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1.0 + } } ``` ```objc {tabTitle:Objective-C} @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 +[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; + }; +}]; +``` - // Adds IP for users. - // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ - options.sendDefaultPii = YES; +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. - // ___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 +Don't combine this option with `SentryCrashExceptionApplication`, which can cause duplicate reports. See capturing uncaught exceptions for details. - // ___PRODUCT_OPTION_START___ profiling - options.configureProfiling = ^(SentryProfileOptions *profiling) { - profiling.lifecycle = SentryProfileLifecycleTrace; - profiling.sessionSampleRate = 1.f; - }; - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs + - // Enable logs to be sent to Sentry - options.enableLogs = YES; - // ___PRODUCT_OPTION_END___ logs - }]; + - return YES; -} -``` +### Initialize the SDK -```swift {tabTitle:SwiftUI with App conformer} -import Sentry +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. -@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 +Session Replay may run on tvOS, but it's only officially supported on iOS. This guide doesn't configure it on tvOS. - // 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.configureProfiling = { - $0.lifecycle = .trace - $0.sessionSampleRate = 1 - } - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ logs +```swift {tabTitle:Swift} {mdExpandTabs} +import Sentry - // Enable logs to be sent to Sentry - options.enableLogs = true - // ___PRODUCT_OPTION_END___ logs - } +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 } + return 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.tracesSampleRate = @1.0; + }]; + 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 or your SwiftUI `App` initializer. This snippet configures Tracing. ```swift import Sentry @@ -344,95 +353,140 @@ 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 + // Enable Tracing. Reduce this value in production. + options.tracesSampleRate = 1.0 } } ``` + - +### Send a Test Trace -## Uncaught NSExceptions +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: -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. +```swift {tabTitle:Swift} {mdExpandTabs} +let transaction = SentrySDK.startTransaction( + name: "Example Operation", + operation: "task", + bindToScope: true +) -```swift {tabTitle:Swift} -import Sentry +// Perform the operation you want to measure. -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.enableUncaughtNSExceptionReporting = true -} +transaction.finish() ``` + ```objc {tabTitle:Objective-C} -@import Sentry; +id transaction = [SentrySDK startTransactionWithName:@"Example Operation" + operation:@"task" + bindToScope:YES]; -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.enableUncaughtNSExceptionReporting = 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. + -## Verify + -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. +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. - + -To verify crashes, ensure you run your application without a debugger attached. Otherwise, the SDK won't capture the crash. +## Send Logs - +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. + +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} -import Sentry +SentrySDK.logger.info("User example action completed") -do { - try aMethodThatMightFail() -} catch { - SentrySDK.capture(error: error) -} +SentrySDK.logger.warn("Slow operation detected", attributes: [ + "operation": "data_fetch", + "duration": 3500 +]) ``` ```objc {tabTitle:Objective-C} -@import Sentry; +SentryLogger *logger = SentrySDK.logger; +[logger info:@"User example action completed"]; +[logger warn:@"Slow operation detected" attributes:@{ + @"operation": @"data_fetch", + @"duration": @3500 +}]; +``` -NSError *error = nil; -[self aMethodThatMightFail:&error] +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. -if (error) { - [SentrySDK captureError:error]; -} +## Send Application Metrics + +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` 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) + +SentrySDK.metrics.gauge(key: "time_since_refresh", value: 4, unit: .hour) + +SentrySDK.metrics.distribution( + key: "api_latency", + value: 187, + unit: .millisecond, + attributes: ["endpoint": "/api/orders"] +) ``` +## Upload Debug Symbols -## Next Steps +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. -- 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 +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. - + -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. +## Verify Your Setup - +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 + +SentrySDK.capture(error: NSError(domain: "SentryTest", code: 1)) +``` + +```objc {tabTitle:Objective-C} +[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 +- + 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..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.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` 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 04313282bcfb7..38ad2921a0d10 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 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 + +[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: