diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index 9996039ea66b1..cf58caac0fcee 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -106,8 +106,7 @@ You can also override this option on a per-call basis by passing the `attachAllT When enabled, the SDK reports SIGTERM signals to Sentry. -It's crucial for developers to understand that the OS sends a SIGTERM to their app as a prelude to a graceful shutdown, before resorting to a SIGKILL. This SIGKILL, which your app can't catch or ignore, is a direct order to terminate your app's process immediately. Developers should be aware that their app can receive a SIGTERM in various scenarios, such as CPU or disk overuse, watchdog terminations, or when the OS updates your app. - +It's crucial for developers to understand that the OS sends a SIGTERM to their app as a prelude to a graceful shutdown, before resorting to a SIGKILL. This SIGKILL, which your app can't catch or ignore, is a direct order to terminate your app's process immediately. Developers should be aware that their app can receive a SIGTERM in various scenarios, such as CPU or disk overuse, watchdog terminations, or when the OS updates your app. @@ -205,7 +204,6 @@ This option can be overridden using . A block that configures the initial scope when starting the SDK. - ```swift import Sentry @@ -301,6 +299,7 @@ Set this boolean to `false` to disable sending of client reports. Client reports When enabled, the SDK adds breadcrumbs for each network request. This feature uses swizzling, so disabling `enableSwizzling` also disables this feature. If you want to enable or disable network tracking for performance monitoring, use `enableNetworkTracking` instead. + @@ -640,7 +639,6 @@ If is not provided, trace - If set to `true`, the SDK will only continue a trace if the organization ID of the incoming trace found in the `baggage` header matches the organization ID of the current Sentry client. @@ -673,7 +671,6 @@ Use to control which reque - This feature is experimental and may have bugs. It's available from [version 8.41.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8410). @@ -852,8 +849,6 @@ When enabled, request and response bodies are captured for URLs matching `networ Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. - - @@ -1108,6 +1103,7 @@ Learn more in the Experiment The path where the SDK stores data before sending it to Sentry. By default, the SDK uses `NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, true)`, which resolves to: + - `~/Library/Caches/` for non-sandboxed macOS apps - `~/Library/Containers/{BundleID}/Data/Library/Caches/` for sandboxed macOS apps - `~/Library/Caches/` (within the app's sandbox) for iOS apps @@ -1186,6 +1182,15 @@ Learn more in the + +When enabled, the SDK sends app start data as a standalone `app.start` transaction instead of attaching it as spans to the first UIViewController transaction. This makes app starts easier to find, sample, and analyze independently. + +Learn more in the Standalone App Start Tracing documentation. + + + + **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/experimental-features.mdx b/docs/platforms/apple/common/features/experimental-features.mdx index a154350639d08..8c2102ee60254 100644 --- a/docs/platforms/apple/common/features/experimental-features.mdx +++ b/docs/platforms/apple/common/features/experimental-features.mdx @@ -26,6 +26,12 @@ Enable App Launch Profili Enable Continuous Profiling to get full coverage of your app's execution. +## Performance Features + +### Standalone App Start Tracing + +Enable `enableStandaloneAppStartTracing` to send app start data as a dedicated transaction instead of attaching it to the first UIViewController transaction. You can use a custom `tracesSampler` to set a dedicated sample rate for app start transactions by checking for the `app.start` operation. + ## Crash & Error Handling ### Persisting Traces When Crashing diff --git a/docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx index 740471d5e8c11..5cd97a021df8b 100644 --- a/docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -134,6 +134,7 @@ SentrySDK.start { options in options.enableAutoPerformanceTracing = false } ``` + ```objc {tabTitle:Objective-C} @import Sentry; @@ -166,6 +167,7 @@ The Cocoa SDK creates the following app start spans: ![App Start Transaction](./img/app-start-transaction.png) Cold and warm start are Mobile Vitals, which you can learn about in the [full documentation](/product/dashboards/sentry-dashboards/mobile/mobile-vitals). + ### Prewarmed App Start Tracing Starting with iOS 15, the operating system might [prewarm](https://developer.apple.com/documentation/uikit/app_and_environment/responding_to_the_launch_of_your_app/about_the_app_launch_sequence#3894431) your app by creating the process before the user opens it. Starting with SDK version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0), the `enablePreWarmedAppStartTracing` is enabled by default. @@ -201,6 +203,70 @@ SentrySDK.start { options in }]; ``` +### Standalone App Start Tracing + + + +This feature is experimental and available since [version 9.14.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#9140). + + + +By default, the SDK attaches app start data as spans to the first UIViewController transaction. With standalone app start tracing enabled, the SDK sends a dedicated `app.start` transaction instead. This gives app starts their own transaction, making them easier to find, sample, and analyze independently. + +![Standalone App Start Transaction](./img/standalone-app-start.png) + +To enable standalone app start tracing: + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.experimental.enableStandaloneAppStartTracing = true +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.experimental.enableStandaloneAppStartTracing = YES; +}]; +``` + +Since standalone app start transactions use the `app.start` operation, you can use a custom `tracesSampler` to set a dedicated sample rate for app starts without increasing your overall sample rate: + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.experimental.enableStandaloneAppStartTracing = true + options.tracesSampler = { context in + if context.transactionContext.operation == "app.start" { + return 1.0 + } + return 0.1 + } +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.experimental.enableStandaloneAppStartTracing = YES; + options.tracesSampler = ^NSNumber * _Nullable(SentrySamplingContext * context) { + if ([context.transactionContext.operation isEqualToString:@"app.start"]) { + return @1.0; + } + return @0.1; + }; +}]; +``` + ## Slow and Frozen Frames This feature is available for iOS, tvOS, and Mac Catalyst. @@ -361,6 +427,7 @@ Starting with version 8.48.0, the Sentry SDK offers extensions for the types `Da The method signatures of these extensions resemble those of the original types, but they add a span to the current transaction. These methods can be used even when the Sentry SDK is not enabled—they will fall back to the original methods in that case. **Behavior:** + - The SDK only creates spans when there is an active transaction on the scope - Only file URLs are tracked (non-file URLs like HTTP URLs are ignored, as they are handled by network tracing) - File size is automatically tracked for read and write operations diff --git a/docs/platforms/apple/common/tracing/instrumentation/img/standalone-app-start.png b/docs/platforms/apple/common/tracing/instrumentation/img/standalone-app-start.png new file mode 100644 index 0000000000000..6bc608f119a06 Binary files /dev/null and b/docs/platforms/apple/common/tracing/instrumentation/img/standalone-app-start.png differ