diff --git a/docs/platforms/dart/common/configuration/filtering.mdx b/docs/platforms/dart/common/configuration/filtering.mdx index 48590f48f863c..49da0aecd848d 100644 --- a/docs/platforms/dart/common/configuration/filtering.mdx +++ b/docs/platforms/dart/common/configuration/filtering.mdx @@ -1,7 +1,7 @@ --- title: Filtering sidebar_order: 60 -description: "Learn more about how to configure your Sentry Dart SDK to filter events reported to Sentry." +description: 'Learn more about how to configure your Sentry Dart SDK to filter events reported to Sentry.' --- When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume. @@ -115,7 +115,7 @@ Use the configuration option to m If you want to drop spans, use [](#using-ignore-spans). ```dart -options.beforeSendSpan = (span) { +options.beforeSendSpan = (span, hint) { span.removeAttribute('http.request.body'); }; ``` diff --git a/docs/platforms/dart/common/configuration/options.mdx b/docs/platforms/dart/common/configuration/options.mdx index f8695fce560e9..5d4723f7c395c 100644 --- a/docs/platforms/dart/common/configuration/options.mdx +++ b/docs/platforms/dart/common/configuration/options.mdx @@ -1,6 +1,6 @@ --- title: Options -description: "Learn more about how the Sentry Dart SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized." +description: 'Learn more about how the Sentry Dart SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized.' sidebar_order: 1 --- @@ -8,7 +8,7 @@ sidebar_order: 1 ## Core Options - + Options that can be read from an environment variable (`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`) are read automatically. @@ -64,7 +64,7 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env -Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. +Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. In v10, sampling happens after event processors and `beforeSend`, so these callbacks also run for events that are later sampled out. @@ -74,11 +74,11 @@ This variable controls the total amount of breadcrumbs that should be captured. - + When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all log messages. -This option is turned off by default. +This option is enabled by default. Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events. @@ -206,12 +206,12 @@ Only available in stream mode -This function is called with a span event object `SentrySpanV2` and can return a modified span object. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. +In SDK v10, this function receives a `SentrySpanV2` and a `Hint`. Modify the span in place; the callback returns `void` or `Future`. On SDK v9, it takes only the span parameter. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. ```dart -options.beforeSendSpan = (span) { +options.beforeSendSpan = (span, hint) { span.removeAttribute('http.request.body'); }; ``` diff --git a/docs/platforms/dart/common/tracing/streamed-spans/index.mdx b/docs/platforms/dart/common/tracing/streamed-spans/index.mdx index 2646f3f1ba6a6..afa799a50509a 100644 --- a/docs/platforms/dart/common/tracing/streamed-spans/index.mdx +++ b/docs/platforms/dart/common/tracing/streamed-spans/index.mdx @@ -1,6 +1,6 @@ --- title: Streamed Spans -description: "Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner." +description: 'Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner.' sidebar_order: 10 new: true --- @@ -40,8 +40,7 @@ Trace You need: -- Tracing configured in - your app +- Tracing configured in your app - Sentry SDK `>=9.23.0` ## Migrate from Transaction Mode @@ -90,14 +89,13 @@ Use only the APIs for the tracing mode you choose. Calls to APIs from the other - In `stream` mode, transaction APIs (`Sentry.startTransaction`, `ISentrySpan.startChild`) are ignored. - In `static` mode, the new span APIs (`Sentry.startSpan`, `Sentry.startSpanSync`, and `Sentry.startInactiveSpan`) are ignored. - - Auto-instrumentations switch to the correct API automatically based on this - setting. + + Auto-instrumentations switch to the correct API automatically based on this setting. - - Auto-instrumentations switch to the correct API automatically based on this - setting. This includes Flutter's frames tracking, app start, TTID/TTFD, - navigation, user interaction, HTTP, database, and GraphQL instrumentations. + + Auto-instrumentations switch to the correct API automatically based on this setting. + This includes Flutter's frames tracking, app start, TTID/TTFD, navigation, user + interaction, HTTP, database, and GraphQL instrumentations. @@ -420,7 +418,7 @@ To modify or redact span data before it's sent, use `beforeSendSpan`: ```dart -options.beforeSendSpan = (span) { +options.beforeSendSpan = (span, hint) { span.removeAttribute('http.request.body'); }; ``` diff --git a/docs/platforms/dart/common/tracing/streamed-spans/migration-guide.mdx b/docs/platforms/dart/common/tracing/streamed-spans/migration-guide.mdx index 70650ea112b7a..84fbc8257aa43 100644 --- a/docs/platforms/dart/common/tracing/streamed-spans/migration-guide.mdx +++ b/docs/platforms/dart/common/tracing/streamed-spans/migration-guide.mdx @@ -1,7 +1,7 @@ --- title: Migrate to Stream Mode sidebar_order: 10 -description: "Learn how to migrate your custom instrumentation from transaction mode to stream mode." +description: 'Learn how to migrate your custom instrumentation from transaction mode to stream mode.' --- Stream mode replaces the transaction-based APIs with new span APIs. If you use custom instrumentation (creating transactions manually, setting span data, or filtering spans) you'll need to update that code before switching to stream mode. This guide walks through the changes. @@ -131,7 +131,7 @@ Manual assignment is only needed to override the automatic default. - // scrub sensitive data, drop transactions by name, etc. - return transaction; - }; -+ options.beforeSendSpan = (span) { ++ options.beforeSendSpan = (span, hint) { + span.removeAttribute('http.request.body'); + }; + options.ignoreSpans = [ diff --git a/docs/platforms/dart/guides/flutter/configuration/filtering.mdx b/docs/platforms/dart/guides/flutter/configuration/filtering.mdx index 6b6728ba55a14..ebdace879c040 100644 --- a/docs/platforms/dart/guides/flutter/configuration/filtering.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/filtering.mdx @@ -1,7 +1,7 @@ --- title: Filtering sidebar_order: 60 -description: "Learn more about how to configure your Sentry Flutter SDK to filter events reported to Sentry." +description: 'Learn more about how to configure your Sentry Flutter SDK to filter events reported to Sentry.' --- When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume. @@ -145,7 +145,7 @@ Use the configuration option to m If you want to drop spans, use [](#using-ignore-spans). ```dart -options.beforeSendSpan = (span) { +options.beforeSendSpan = (span, hint) { span.removeAttribute('http.request.body'); }; ``` diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx index ae5e68bd4371d..9585d08e2f67b 100644 --- a/docs/platforms/dart/guides/flutter/configuration/options.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/options.mdx @@ -1,6 +1,6 @@ --- title: Options -description: "Learn more about how the Sentry Flutter SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized." +description: 'Learn more about how the Sentry Flutter SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized.' sidebar_order: 1 --- @@ -8,7 +8,7 @@ sidebar_order: 1 ## Core Options - + Options that can be read from an environment variable (`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`) are read automatically. @@ -64,7 +64,7 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env -Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. +Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. In v10, sampling happens after event processors and `beforeSend`, so these callbacks also run for events that are later sampled out. @@ -84,7 +84,7 @@ The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/enve When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all log messages. -This option is turned off by default. +This option is enabled by default. Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events. @@ -114,12 +114,6 @@ Most SDKs will attempt to auto-discover this value. - - -When set to `true`, the SDK will send session events to Sentry. This is supported in all browser SDKs, emitting one session per pageload and page navigation to Sentry. In mobile SDKs, when the app goes to the background for longer than 30 seconds, sessions are ended. - - - Configures whether stack trace frames are considered as in app frames by default. @@ -131,7 +125,7 @@ This value is used only if Sentry can not find the origin of the frame. - + A list of string prefixes of module names that belong to the app. This option takes precedence over `in-app-exclude`. @@ -139,11 +133,11 @@ Sentry differentiates stack frames that are directly related to your application - + A list of string prefixes of module names that do not belong to the app, but rather to third-party packages. Modules considered not part of the app will be hidden from stack traces by default. -This option can be overridden using . +This option can be overridden using . @@ -233,12 +227,12 @@ Only available in stream mode -This function is called with a span event object `SentrySpanV2` and can return a modified span object. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. +In SDK v10, this function receives a `SentrySpanV2` and a `Hint`. Modify the span in place; the callback returns `void` or `Future`. On SDK v9, it takes only the span parameter. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. ```dart -options.beforeSendSpan = (span) { +options.beforeSendSpan = (span, hint) { span.removeAttribute('http.request.body'); }; ``` @@ -344,22 +338,16 @@ Controls whether the SDK should propagate the W3C `traceparent` HTTP header alon - - -Set this boolean to `true` to report the app start as its own `app.start` transaction instead of attaching it to the first `ui.load` transaction. Requires tracing to be enabled and is only supported on Android and iOS. This option is experimental. Learn more in our App Start Instrumentation docs. +App start is automatically reported as a standalone `app.start` root on Android and iOS when tracing is enabled. See App Start Instrumentation for sampling and extension APIs. - - -## Experimental Features +## Hybrid SDK Options - + -An optional property that configures which features are in experimental mode. This property is either an `Object Type` with properties or a key/value `TypedDict`, depending the language. Experimental features are still in-progress and may have bugs. We recognize the irony. +Set this option to `true` to capture failed HTTP requests made by the native iOS and macOS SDK's network instrumentation. It is independent of `captureFailedRequests`, which controls Dart-side capture through `SentryHttpClient` and `sentry_dio`. The option is non-nullable in v10 and no longer falls back to `captureFailedRequests`. -## Hybrid SDK Options - Set this boolean to `false` to disable the auto initialization of the native layer SDK. Doing so means you will need to initialize the native SDK manually. Do not use this to disable the native layer. @@ -380,9 +368,9 @@ Set this boolean to `false` to disable the [release health](/product/releases/he - + -Set this to change the default interval to end a session (release health) if the app goes to the background. Default is 30,000. +Sets how long the app can remain in the background before the SDK ends the session. For example, use `options.autoSessionTrackingInterval = const Duration(seconds: 60);` for a one-minute interval. diff --git a/docs/platforms/dart/guides/flutter/configuration/releases.mdx b/docs/platforms/dart/guides/flutter/configuration/releases.mdx index 3e291f616dd01..caf69de4f9c1b 100644 --- a/docs/platforms/dart/guides/flutter/configuration/releases.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/releases.mdx @@ -1,6 +1,6 @@ --- title: Releases & Health -description: "Learn how to configure your Sentry Flutter SDK to tell Sentry about your releases." +description: 'Learn how to configure your Sentry Flutter SDK to tell Sentry about your releases.' sidebar_order: 40 --- @@ -33,6 +33,10 @@ In order to monitor release health, the SDK sends session data. ### Sessions -A session represents the interaction between the user and the application. Sessions contain a timestamp, a status (if the session was OK or if it crashed), and are always linked to a release. Most Sentry SDKs can manage sessions automatically. +A session represents the interaction between the user and the application. Sessions include timestamps and health information and are linked to a release. The SDK manages sessions automatically by default. + +On Android, iOS, and macOS, v10 records unhandled Flutter errors as unhandled, non-terminating errors instead of marking the session as crashed. Native crashes that terminate the process are still crashes. Unhandled Flutter errors dropped by `sampleRate` also update release health, so reducing the error sample rate does not hide those errors from session health. Events dropped by your event processors or `beforeSend` do not follow this sampling path. + +Account for this change when comparing crash-free metrics before and after upgrading. diff --git a/docs/platforms/dart/guides/flutter/configuration/sampling.mdx b/docs/platforms/dart/guides/flutter/configuration/sampling.mdx index f2d6c5885842a..f923d14a1b744 100644 --- a/docs/platforms/dart/guides/flutter/configuration/sampling.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/sampling.mdx @@ -1,7 +1,7 @@ --- title: Sampling sidebar_order: 50 -description: "Learn how to configure the volume of error and transaction events sent to Sentry using the Flutter SDK." +description: 'Learn how to configure the volume of error and transaction events sent to Sentry using the Flutter SDK.' --- Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. @@ -12,7 +12,9 @@ To send a representative sample of your errors to Sentry, set the -The error sample rate defaults to `1`, meaning all errors are sent to Sentry. +The error sample rate defaults to `1`, meaning all errors are sent to Sentry. In v10, the sampling decision runs after event processors and `beforeSend`. These callbacks still run for events that are later sampled out. + +On Android, iOS, and macOS, unhandled errors dropped by `sampleRate` still update release health. @@ -45,8 +47,8 @@ The Sentry SDKs have two configuration options to control the volume of transact 2. Sampling function () which: - Samples different transactions/service spans at different rates - - Filters out - some transactions entirely + - Filters out some + transactions entirely - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior By default, none of these options are set, meaning no transactions/service spans will be sent to Sentry. You must set either one of the options to start sending them. diff --git a/docs/platforms/dart/guides/flutter/data-management/data-collected.mdx b/docs/platforms/dart/guides/flutter/data-management/data-collected.mdx index 53e1081fbfae4..db6914f2cbe4e 100644 --- a/docs/platforms/dart/guides/flutter/data-management/data-collected.mdx +++ b/docs/platforms/dart/guides/flutter/data-management/data-collected.mdx @@ -1,6 +1,6 @@ --- title: Data Collected -description: "See what data is collected by the Sentry Flutter SDK." +description: 'See what data is collected by the Sentry Flutter SDK.' sidebar_order: 1 --- @@ -42,7 +42,7 @@ The request body of incoming HTTP requests can be sent to Sentry. Whether it's s - **The type of the request body:** - JSON and form bodies are sent -- **The size of the request body:** There's a maxRequestBodySize option that's set to `NONE` by default. This means by default no request body is sent to Sentry. +- **The size of the request body:** There's a maxRequestBodySize option that's set to `MaxRequestBodySize.never` by default. This means by default no request body is sent to Sentry. ## Source Context @@ -67,19 +67,21 @@ If you want to send the device name, set `sendDefaultPii = true`, additional runtime details are collected: + - Executable path e.g `flutter` - Resolved executable locations e.g `/system/bin/app_process64` - Script path e.g `file:///main.dart` ## SQL Queries -While SQL queries are sent to Sentry, neither the full SQL query (`UPDATE app_user SET password='supersecret' WHERE id=1;`), nor the values of its parameters will ever be sent. A parameterized version of the query (`UPDATE app_user SET password=? WHERE id=?;`) is sent instead. +Database integrations can send SQL statements to Sentry. Use parameterized queries, such as `UPDATE app_user SET password=? WHERE id=?;`, to keep values out of the statement. Values embedded directly in SQL strings can appear in the captured query; the SDK doesn't automatically replace them with placeholders. ## User Interaction Data By default, the SDK collects basic UI interaction data while protecting sensitive information by excluding text content. This means button clicks and UI interactions are tracked, but without any text or labels that could contain personal or sensitive data. When `sendDefaultPii = true`, the SDK will additionally collect text content from UI elements including: + - Text content from buttons (for example, "Submit" or "Cancel" button labels) - Semantic labels that help describe UI elements for accessibility - Tooltip messages that appear when hovering over UI elements @@ -89,4 +91,6 @@ This additional text content can be useful for debugging and understanding user ## Session Replay -By default, our Session Replay SDK masks all text content, images, webviews, and user input. This helps ensure that no sensitive data is exposed. You can find more details in the Session Replay documentation. +By default, Session Replay masks text, user input, and non-asset images. Asset images are visible unless you enable `maskAssetImages`. Third-party widgets, including webviews, may need manual masking. + +In v10, widgets marked as sensitive with Flutter's `SensitiveContent` widget are also masked by default. Review your app's replay output and configure Replay privacy settings for your content. diff --git a/docs/platforms/dart/guides/flutter/features/index.mdx b/docs/platforms/dart/guides/flutter/features/index.mdx index fa1dd06a366f7..018f79455f5f4 100644 --- a/docs/platforms/dart/guides/flutter/features/index.mdx +++ b/docs/platforms/dart/guides/flutter/features/index.mdx @@ -10,7 +10,7 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i **Features:** - Under the hood the SDK relies on Sentry's Dart SDK: - - You need at least Dart `3.5.0` and Flutter `3.24.0`. + - You need at least Dart `3.12.0` and Flutter `3.44.0`. - This SDK includes all the Features of Sentry's Dart SDK. - Automatic native crash error tracking (using both Android and iOS), including: - Java, Kotlin, C, and C++ code for Android. @@ -23,15 +23,12 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i - via the Native SDKs Automatic Breadcrumbs for Android and Automatic Breadcrumbs for iOS. - as well as `http` with the Dart SDK. - Integrations for sqflite, routing and more. For a complete list, see integrations. -- Release Health tracks crash free - users and sessions. +- Release Health tracks crash free users and + sessions. - Attachments - that can enrich your event by storing additional files, such as config or log - files. + that can enrich your event by storing additional files, such as config or log files. - Tracing that can track - - app start time - + app start time , Time to Initial Display and Time to Full Display @@ -49,27 +46,19 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i automatic instrumentations . -- User Feedback, providing the - ability to collect user feedback when an unexpected event occurs. +- User Feedback, providing the ability to + collect user feedback when an unexpected event occurs. - Screenshot and - - View Hierarchy - + View Hierarchy attachments for errors. -- Profiling collects detailed - information about your code at the function level. Profiling is currently - supported on **iOS** and **macOS**, and captures profiles across multiple - language layers, including native languages (such as Swift and Objective-C) as - well as Dart. - Source Context shows snippets of code around the location of stack frames. -- Sentry Dart Plugin makes - uploading debug symbols easy and automatic. -- Metrics allow you to send counters, - gauges, and distributions to track application health alongside errors and - traces. +- Sentry Dart Plugin makes uploading debug + symbols easy and automatic. +- Metrics allow you to send counters, gauges, + and distributions to track application health alongside errors and traces. **Web Limitations:** @@ -84,7 +73,6 @@ Sentry supports Flutter Web as well, with the following limitations: Sentry supports Flutter on Linux and Windows as well, with the following limitations: -- Native crashes are not supported on Windows. - [Release Health](/product/releases/health/) isn't supported. -When running on macOS, you can expect the same feature set as on iOS. +macOS supports native crash reporting and release health. Session Replay and native app-start measurements are available on iOS and Android only. diff --git a/docs/platforms/dart/guides/flutter/index.mdx b/docs/platforms/dart/guides/flutter/index.mdx index a8328e525e891..c6e7fde205d55 100644 --- a/docs/platforms/dart/guides/flutter/index.mdx +++ b/docs/platforms/dart/guides/flutter/index.mdx @@ -76,6 +76,8 @@ npx @sentry/wizard@latest -i flutter +After running the wizard, check the generated configuration for v10 compatibility. Remove `options.enableLogs` and `options.profilesSampleRate` assignments if present: logs need no enable flag, and Flutter profiling is no longer supported. Do not select profiling when prompted. For a v10-compatible initialization example and Apple build requirements, follow Manual Setup. + This will patch your project and configure the SDK. You only need to patch the project once, then you can add the patched files to your version control system. If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flutter/manual-setup/). @@ -83,7 +85,7 @@ If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flu - Update your `pubspec.yaml` with the `sentry_flutter` and `sentry_dart_plugin` packages. - Create a `sentry.properties` file (gitignored) with a Sentry CLI auth token. -- Prompt you to enable Tracing, Session Replay, Logs, and (on iOS/macOS) Profiling, then patch `main.dart` with `SentryFlutter.init`. +- Prompt you for optional features and patch `main.dart` with `SentryFlutter.init`. Review the generated options using the v10 guidance above. - Add a sample exception that is captured when the app starts so you can verify the setup. @@ -91,7 +93,7 @@ If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flu The wizard will prompt you to enable optional features. Select the same options here so this guide can show you how to verify them: diff --git a/docs/platforms/dart/guides/flutter/manual-setup.mdx b/docs/platforms/dart/guides/flutter/manual-setup.mdx index 8c26e2d50a8bf..f2fa2c25f9c1d 100644 --- a/docs/platforms/dart/guides/flutter/manual-setup.mdx +++ b/docs/platforms/dart/guides/flutter/manual-setup.mdx @@ -1,7 +1,7 @@ --- title: Manual Setup sidebar_order: 1 -description: "Learn how to set up the Sentry Flutter SDK manually." +description: 'Learn how to set up the Sentry Flutter SDK manually.' --- If you can't (or prefer not to) run the [automatic setup](/platforms/dart/guides/flutter/#install), you can follow the instructions below to configure your application manually. @@ -30,19 +30,34 @@ dependencies: +### Apple Platform Setup + +The v10 Flutter plugin installs the native Sentry SDK through Swift Package Manager. CocoaPods is no longer supported for this plugin. + +Flutter 3.44 enables Swift Package Manager by default and migrates the Xcode project when you run your app. If you previously disabled it, remove any project-level `enable-swift-package-manager: false` setting and run: + +```bash +flutter config --enable-swift-package-manager +flutter pub get +``` + +Set your Xcode deployment targets to iOS 15.0 or macOS 12.0 or later. For custom targets, flavors, or manual migration, follow [Flutter's Swift Package Manager guide](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers/). + +Keep CocoaPods if other plugins still require it. Flutter can use both dependency managers in the same application. + ## Configure Choose the features you want to configure, and this guide will show you how: ### Initialize the Sentry SDK -Configuration should happen as **early as possible** in your application's lifecycle. +Configuration should happen as **early as possible** in your application's lifecycle. Logs and metrics are always enabled in v10; use `Sentry.logger` and `Sentry.metrics` after initialization without an enable flag. diff --git a/docs/platforms/dart/guides/flutter/native-init.mdx b/docs/platforms/dart/guides/flutter/native-init.mdx index 113e0de92c627..33f127c27c2b3 100644 --- a/docs/platforms/dart/guides/flutter/native-init.mdx +++ b/docs/platforms/dart/guides/flutter/native-init.mdx @@ -20,12 +20,13 @@ Next, initialize the native SDKs as specified in the guides below. - [Android](/platforms/android/manual-setup/#configuration-via-sentryoptions) - [iOS](/platforms/apple/guides/ios/manual-setup/) +- [macOS](/platforms/apple/guides/macos/) - [Browser](/platforms/javascript/#configure) For Web you will need to install the JavaScript SDK by injecting the loader script manually into your HTML's `` tag. -The Android and iOS SDKs are already packaged with the Flutter SDK. +The Android, iOS, and macOS SDKs are already packaged with the Flutter SDK. v10 installs the Apple SDK through Swift Package Manager. Use the bundled native SDK version rather than adding an incompatible version separately. For native Swift or Objective-C customizations, review the [Cocoa v8-to-v9 migration guide](/platforms/apple/migration/v8-to-v9/). - \ No newline at end of file + diff --git a/docs/platforms/dart/guides/flutter/overhead/index.mdx b/docs/platforms/dart/guides/flutter/overhead/index.mdx index 8eecdb1395b43..fd86db79f85e1 100644 --- a/docs/platforms/dart/guides/flutter/overhead/index.mdx +++ b/docs/platforms/dart/guides/flutter/overhead/index.mdx @@ -29,7 +29,10 @@ If your app raises many errors in a tight loop, it can become too much to proces ## Breadcrumbs -Breadcrumbs are collected through automated integrations or by manually adding them. To have them readily available for every event generated by the SDK, they are continuously persisted, and managed in a performant buffer. This shouldn't impact user experience. +Breadcrumbs are collected +through automated integrations or by manually adding them. To have them readily available +for every event generated by the SDK, they are continuously persisted, and managed in a +performant buffer. This shouldn't impact user experience. Capturing excessive numbers of breadcrumbs (for example, creating breadcrumbs for all log messages) can cause significant performance overhead. To mitigate this, review and adapt your app's usage of breadcrumbs. For example, increase the min-level of log messages that create breadcrumbs from `warn` to `error`. @@ -39,10 +42,6 @@ Note that increasing the max number of breadcrumbs **does not** improve performa As stated in our product docs on the topic, Tracing adds some overhead, but should have minimal impact on the performance of your application. In typical scenarios, the expected overhead is less than 3% of the app's resource utilization. -## Profiling - -As stated in our product docs on the topic, Profiling adds some overhead, but should have minimal impact on the performance of your application. In typical scenarios, the expected overhead is less than 5% of the app's resource utilization. - ## SDK Size The Sentry SDK for Flutter adds approximately 1-1.5 MB to an app's binary size. The exact impact depends on multiple factors, including the device architecture. diff --git a/docs/platforms/dart/guides/flutter/profiling/index.mdx b/docs/platforms/dart/guides/flutter/profiling/index.mdx index c701d93f809ab..081831a305a03 100644 --- a/docs/platforms/dart/guides/flutter/profiling/index.mdx +++ b/docs/platforms/dart/guides/flutter/profiling/index.mdx @@ -1,11 +1,18 @@ --- -title: Set Up Profiling -sidebar_title: Profiling -description: "Learn how to enable profiling in your app using the Sentry Flutter SDK if it is not already set up." +title: Profiling in SDK v9 +sidebar_title: Profiling (SDK v9) +description: 'Learn about profiling support in Sentry Flutter SDK v9 and its removal in v10.' sidebar_order: 5000 +sidebar_hidden: true sidebar_section: features --- + + +Profiling is not supported in Sentry Flutter SDK v10. Remove `options.profilesSampleRate` when upgrading. Use Tracing to measure operation durations and mobile vitals. The instructions below apply only to SDK v9. + + + @@ -23,7 +30,7 @@ Profiling depends on Sentry’s Tracing product being enabled beforehand. To ena ```dart {diff} SentryFlutter.init( - (options) => { + (options) { options.dsn = '___PUBLIC_DSN___'; + // We recommend adjusting this value in production: + options.tracesSampleRate = 1.0; @@ -40,7 +47,7 @@ To enable profiling, set the `profilesSampleRate`: ```dart {diff} SentryFlutter.init( - (options) => { + (options) { options.dsn = '___PUBLIC_DSN___'; // We recommend adjusting this value in production: options.tracesSampleRate = 1.0; diff --git a/docs/platforms/dart/guides/flutter/profiling/troubleshooting/index.mdx b/docs/platforms/dart/guides/flutter/profiling/troubleshooting/index.mdx index e8d61cdf3461e..24da76ecf288b 100644 --- a/docs/platforms/dart/guides/flutter/profiling/troubleshooting/index.mdx +++ b/docs/platforms/dart/guides/flutter/profiling/troubleshooting/index.mdx @@ -1,9 +1,16 @@ --- title: Troubleshooting -description: "Learn how to troubleshoot your profiling setup." +description: 'Troubleshoot profiling in Sentry Flutter SDK v9. Profiling is not supported in v10.' +sidebar_hidden: true sidebar_order: 9000 --- + + +Sentry Flutter SDK v10 does not capture profiles. The checks below apply only to SDK v9. For v10, use Tracing to investigate operation durations. + + + If you don't see any profiling data in [sentry.io](https://sentry.io), you can try the following: - Ensure that Tracing is enabled. diff --git a/docs/platforms/dart/guides/flutter/session-replay/index.mdx b/docs/platforms/dart/guides/flutter/session-replay/index.mdx index 1dfba46cba63b..b01dfbbc5f0f0 100644 --- a/docs/platforms/dart/guides/flutter/session-replay/index.mdx +++ b/docs/platforms/dart/guides/flutter/session-replay/index.mdx @@ -4,7 +4,7 @@ sidebar_title: Session Replay sidebar_order: 5500 sidebar_section: features notSupported: -description: "Learn how to enable Session Replay in your mobile app." +description: 'Learn how to enable Session Replay in your mobile app.' --- @@ -15,7 +15,7 @@ Flutter Session Replay is available on **iOS** and **Android**. [Session Replay](/product/session-replay/) helps you get to the root cause of an error or latency issue faster by providing you with a reproduction of what was happening in the user's device before, during, and after the issue. You can rewind and replay your application's state and see key user interactions, like taps, swipes, network requests, and console entries, in a single UI. -By default, our Session Replay SDK masks all text content, images, and user input, giving you heightened confidence that no sensitive data will leave the device. To learn more, see [product docs](/product/session-replay/). +By default, the SDK masks text, user input, and non-asset images. Images bundled as assets are not masked unless you set `options.privacy.maskAssetImages = true`. Review privacy settings for `SensitiveContent` and custom widgets. ## Pre-requisites @@ -24,7 +24,7 @@ You can update your `pubspec.yaml` to the matching version: ```yaml dependencies: - sentry_flutter: ^9.0.0 + sentry_flutter: ^{{@inject packages.version('sentry.dart.flutter') }} ``` ## Setup @@ -45,6 +45,7 @@ await SentryFlutter.init( ), ); ``` + For more details on the available properties, see the [SentryReplayOptions](https://pub.dev/documentation/sentry_flutter/latest/sentry_flutter/SentryReplayOptions-class.html), which is part of [SentryFlutterOptions](https://pub.dev/documentation/sentry_flutter/latest/sentry_flutter/SentryFlutterOptions-class.html). ## Verify diff --git a/docs/platforms/dart/guides/flutter/tracing/index.mdx b/docs/platforms/dart/guides/flutter/tracing/index.mdx index b2035f8d56dae..cf28ea1bc4271 100644 --- a/docs/platforms/dart/guides/flutter/tracing/index.mdx +++ b/docs/platforms/dart/guides/flutter/tracing/index.mdx @@ -1,7 +1,7 @@ --- title: Set Up Tracing sidebar_title: Tracing -description: "Learn how to enable tracing in your app using the Sentry Flutter SDK and discover valuable performance insights of your application." +description: 'Learn how to enable tracing in your app using the Sentry Flutter SDK and discover valuable performance insights of your application.' sidebar_order: 4000 sidebar_section: features --- @@ -43,22 +43,9 @@ While you're testing, set to `1 ## Standalone App Start Tracing - +On Android and iOS, v10 automatically reports startup as a separate `App Start` root with the `app.start` operation when tracing is enabled. It has its own sampling decision and is independent of the first screen's `ui.load` transaction. -This feature is experimental and available since [version 9.26.0](https://github.com/getsentry/sentry-dart/blob/main/CHANGELOG.md#9260). The API is subject to change and may introduce breaking changes in future releases. - - - -By default, app start data is attached to the first `ui.load` transaction in your app. Standalone app start tracing sends the app start as its own transaction instead, which gives you more accurate app start measurements because they no longer depend on a screen transaction being started. It's supported on Android and iOS. - -```dart -await SentryFlutter.init((options) { - options.tracesSampleRate = 1.0; - options.enableStandaloneAppStartTracing = true; -}); -``` - -For more details, including how to extend the app start past the first frame, see App Start Instrumentation. +No extra enable flag is needed. For sampling examples and APIs to extend startup past the first frame, see App Start Instrumentation. ## Next Steps diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 70f38ae673c78..c02b41cf5e5e8 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -1,6 +1,6 @@ --- title: Troubleshooting -description: "Troubleshoot and resolve edge cases regarding known limitations and bundling." +description: 'Troubleshoot and resolve edge cases regarding known limitations and bundling.' sidebar_order: 9000 --- @@ -16,7 +16,7 @@ When errors occur in your Flutter app, you might notice that some error reports Sentry automatically captures error details and stack traces using Flutter and Dart's built-in error handling such as `FlutterError.onError`. However, sometimes the stack trace information is not available or becomes incomplete, especially when using `async` and `await` in your code. -When this happens, Sentry does its best to give you *some* debugging information, for example by calling `StackTrace.current` if there is none given by the `onError` hook, but it might not give you the complete picture. +When this happens, Sentry does its best to give you _some_ debugging information, for example by calling `StackTrace.current` if there is none given by the `onError` hook, but it might not give you the complete picture. ### Example of the Problem @@ -57,6 +57,7 @@ This happens because Dart's async/await implementation can cause stack trace inf ### What Can You Do? In order to get better debugging information for these cases you can: + - Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/enriching-events/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/enriching-events/breadcrumbs/) for critical paths in your application - Consider using [Sentry's Structured Logs](/platforms/dart/logs/) to capture additional debugging data alongside your errors @@ -170,27 +171,18 @@ If you encounter any issues, you can set the `SENTRY_NATIVE_BACKEND` environment On Linux, compiling your Flutter Desktop app with the crashpad backend can fail if your clang toolchain is out of date. - - Update your clang to at least version 13, then try again. - - If you still encounter errors, please file an issue on our [Sentry Dart GitHub repository](https://github.com/getsentry/sentry-dart/issues/). - -### Java or JNI Errors when compiling on Flutter Desktop - -Since Sentry Flutter SDK version `9.0.0`, we improved how the SDK works on Android by switching from method channels to JNI (Java Native Interface) for certain operations. +- Update your clang to at least version 13, then try again. +- If you still encounter errors, please file an issue on our [Sentry Dart GitHub repository](https://github.com/getsentry/sentry-dart/issues/). -However, there's a current limitation: Flutter automatically compiles the Dart JNI plugin for all platforms (iOS, Android, etc.), even when you're only building for one platform. +### JNI Dependency Conflicts -For example on Windows it will compile components such as `dartjni.dll` which requires a JDK (Java Development Kit) to be installed on your system. +Sentry Flutter SDK v10 requires `jni >=1.0.0 <1.1.0`. If dependency resolution fails after upgrading, check whether another package or a `dependency_overrides` entry requires an older JNI version. Update that dependency rather than overriding Sentry to use an incompatible JNI version. -Ideally it is possible to compile only for the chosen target platform to avoid unnecessary work, but this is currently blocked by [this Dart JNI issue](https://github.com/dart-lang/native/issues/1023). +For Android build errors, use Flutter 3.44 or later. The Sentry plugin relies on Flutter's Kotlin support and no longer applies its own Kotlin Gradle Plugin. -If you run into problems, make sure you have a JDK installed on your computer. We recommend using version 17. +### Apple Dependency Resolution - - -This does not affect your end users. Since we only use JNI code on Android, users on other platforms do not need Java installed. -The JDK is only necessary as the developer because the Flutter tooling will compile the Dart JNI plugin for all platforms. - - +Sentry Flutter SDK v10 requires Swift Package Manager on iOS and macOS. CocoaPods cannot install the v10 Sentry Flutter plugin. Enable Swift Package Manager and set the deployment targets to iOS 15.0 or macOS 12.0 or later, as described in Apple Platform Setup. ### `SentryFlutter.init` Throws a `sentry_init failed` Error @@ -235,6 +227,7 @@ If you encounter a circular dependency error when building your Android app with ### Error Example You might see an error similar to: + ``` Circular dependency between the following tasks: :app:compileReleaseJavaWithJavac @@ -331,7 +324,7 @@ SentryFlutter.init( Copy the `main.dart` file into the `lib` folder of your existing project. This file already contains the code of the `multi_view_app.dart` from the [`flutter documentation`](https://docs.flutter.dev/platform-integration/web/embedding-flutter-web#handling-view-changes-from-dart). Next, copy the `flutter_bootstrap.js` file and the `index.html` file into the `web` folder. -Make sure you're using **Flutter 3.24** or newer and run the application. +Make sure you're using **Flutter 3.44** or newer and run the application. Now you should be able to see **two** instances of the same application side by side, with different **ViewIds** in the `body`. diff --git a/includes/dart-integrations/app-start-instrumentation.mdx b/includes/dart-integrations/app-start-instrumentation.mdx index c95bd89e4e034..2ac7670c57802 100644 --- a/includes/dart-integrations/app-start-instrumentation.mdx +++ b/includes/dart-integrations/app-start-instrumentation.mdx @@ -1,6 +1,6 @@ --- title: App Start Instrumentation -description: "Learn more about the Sentry App Start Instrumentation for the Flutter SDK." +description: 'Learn more about the Sentry App Start Instrumentation for the Flutter SDK.' caseStyle: camelCase supportLevel: production sdk: sentry.dart.flutter @@ -20,83 +20,32 @@ App start instrumentation is available on **iOS** and **Android**. -## Instrumentation Behaviour +## Instrumentation Behavior -Before diving into the configuration, it's important to understand how app start instrumentation behaves: +On Android and iOS, the SDK measures startup from native process initialization to the first rendered frame. In v10, it reports this as a standalone root named `App Start` with the `app.start` operation, independently of screen-navigation transactions. -App start instrumentation tracks the duration between the earliest native process initialization and the first frame rendered (as reported by [addTimingsCallback](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/addTimingsCallback.html)). Once the app start is processed, the callback is removed to avoid additional overhead. +The root includes startup breakdown spans and mobile vitals, including the cold or warm start duration. In transaction mode, these are sent together when the transaction finishes. In stream mode, the SDK uses the streaming span APIs. -When the SDK receives the start and end times of the app launch, the SDK: - -- Creates a transaction named `ui.load` -- Attaches a span with either `app.start.cold` or `app.start.warm` operation -- Adds app start metrics to the transaction - -If you'd rather have the app start reported as its own transaction, see [Standalone App Start Tracing](#standalone-app-start-tracing). - - - -Sentry's App Start instrumentation aims to be as comprehensive and representative of the user experience as possible, and adheres to guidelines by the platform vendors. For this reason, App Starts reported by Sentry might be longer than what you see in other tools. - - +On web and desktop platforms, a separate integration measures initial display timing. It does not report the native Android/iOS app-start measurements described here. ## Prerequisites -Before starting, ensure: - -1. The Sentry Flutter SDK is initialized. Learn more [here](/platforms/dart/guides/flutter/#configure) -2. Tracing is set up. Learn more [here](/platforms/dart/guides/flutter/tracing/). - -## Configure +Initialize SentryFlutter as early as possible and enable tracing. Native app-start instrumentation runs automatically on Android and iOS; no additional enable flag is needed. -This instrumentation is automatically enabled. There is no need for further configuration. - - - -App start instrumentation is designed specifically for pure Flutter applications and requires UI rendering to function properly. If you're using Flutter in an add-to-app integration scenario, the app start metrics will not provide accurate measurements. In such cases, we recommend disabling this instrumentation. - - +App-start measurements assume a pure Flutter application. For add-to-app integrations, native process startup may not represent the Flutter UI startup you want to measure. See [Disable App Start Instrumentation](#disable-app-start-instrumentation) if those measurements aren't useful for your app. ## Verify -### 1. Launch Your App: - -Launch your Sentry configured app. - -### 2. Locate Your Transaction: - -Open the [sentry.io performance page](https://sentry.io/performance), find, and select the 'root /' transaction and navigate to the trace view of a sampled event. - -### 3. View App Start Metrics: - -Select the event within your transaction. Sentry displays the app start metrics on the right side of the screen in the **Mobile Vitals** section. +Launch your app with tracing enabled. In your Sentry project, find a sampled `App Start` root with operation `app.start`, then inspect its breakdown spans and mobile vitals. It is separate from the first screen's `ui.load` transaction. ## Standalone App Start Tracing - - -This feature is experimental and available since [version 9.26.0](https://github.com/getsentry/sentry-dart/blob/main/CHANGELOG.md#9260). The API is subject to change and may introduce breaking changes in future releases. - - - -By default, app start data is attached to the first `ui.load` transaction in your app, which mixes startup timing with screen-display timing. Standalone app start tracing sends the app start as its own `App Start` transaction with the `app.start` operation instead. This gives you more accurate measurements, because they no longer depend on a screen transaction being started, and it lets you sample app starts independently. - -To enable it: - -```dart -await SentryFlutter.init((options) { - options.tracesSampleRate = 1.0; - options.enableStandaloneAppStartTracing = true; -}); -``` +Standalone app start tracing is the default in v10. The old `enableStandaloneAppStartTracing` option has been removed. Transaction mode remains the default trace lifecycle; switching to stream mode is optional. -Standalone app start tracing requires tracing to be enabled and is only supported on Android and iOS. On every other platform the SDK keeps attaching app start data to the first `ui.load` transaction. - -Because the app start uses the `app.start` operation, you can use `tracesSampler` to give app starts a dedicated sample rate without raising your overall sample rate. Where you read that operation depends on your trace lifecycle: transaction mode exposes it on the transaction context, while stream mode carries it as the span's `sentry.op` attribute. +App start has its own sampling decision. To sample it independently, inspect the operation in `tracesSampler`: transaction mode exposes it on the transaction context, while stream mode carries it in the span's `sentry.op` attribute. ```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs} await SentryFlutter.init((options) { - options.enableStandaloneAppStartTracing = true; options.tracesSampler = (samplingContext) { if (samplingContext.transactionContext.operation == 'app.start') { return 1.0; @@ -108,7 +57,7 @@ await SentryFlutter.init((options) { ```dart {tabTitle:Stream Mode} await SentryFlutter.init((options) { - options.enableStandaloneAppStartTracing = true; + options.traceLifecycle = SentryTraceLifecycle.stream; options.tracesSampler = (samplingContext) { final operation = samplingContext.spanContext.attributes['sentry.op']?.value; if (operation == 'app.start') { @@ -129,7 +78,6 @@ The only requirement is that `extendAppStart()` runs before the first frame rend await SentryFlutter.init( (options) { options.tracesSampleRate = 1.0; - options.enableStandaloneAppStartTracing = true; }, appRunner: () async { SentryFlutter.extendAppStart(); @@ -195,11 +143,16 @@ try { SentryFlutter.extendAppStart(); try { - await Sentry.startSpan( - 'Fetch remote config', - (span) => fetchRemoteConfig(), - parentSpan: SentryFlutter.getExtendedAppStartSpanV2(), - ); + final parent = SentryFlutter.getExtendedAppStartSpanV2(); + if (parent != null) { + await Sentry.startSpan( + 'Fetch remote config', + (span) => fetchRemoteConfig(), + parentSpan: parent, + ); + } else { + await fetchRemoteConfig(); + } } finally { await SentryFlutter.finishExtendedAppStart(); } @@ -207,7 +160,7 @@ try { In stream mode, `startSpan` ends the child for you once the callback completes, so it only needs the parent. The extension span isn't the active span, which is why you have to pass it as `parentSpan` rather than relying on automatic nesting. -Both getters return `null` when the app start isn't extended. In transaction mode the null-aware calls take care of that. In stream mode, passing `parentSpan: null` means "start a root span", so guard the call if a stray root would be a problem. +Both getters return `null` when the app start isn't extended. In transaction mode the null-aware calls take care of that. In stream mode, the example checks for a parent because passing `parentSpan: null` starts a root span instead of a child. Spans you start under the extension keep the app start open until they finish, so finish them too if they shouldn't delay it. @@ -219,27 +172,27 @@ Always finish what you extend. While an extension is open the app start is still -Extending requires standalone app start tracing to be enabled. `extendAppStart()` does nothing when standalone app start tracing is off, when the first frame has already rendered, or when the app start is already extended. Each of those cases is logged rather than reported back to the caller. +Extending requires an active, sampled app start on Android or iOS. `extendAppStart()` does nothing if there is no eligible app start, the first frame has already rendered, or an extension has already been requested. ## Disable App Start Instrumentation -App start ships as two integrations: `NativeAppStartIntegration` for the default `ui.load`-attached path, and `StandaloneAppStartIntegration` for standalone app start tracing. The SDK registers both and each one stands down at runtime depending on your configuration, so remove both to turn app start off no matter how it's configured. +To disable native app-start tracing on Android and iOS, remove `StandaloneAppStartIntegration` during initialization. This requires an internal import, which can change between SDK versions. ```dart -// ignore_for_file: implementation_imports +// ignore_for_file: implementation_imports, invalid_use_of_internal_member +import 'package:sentry_flutter/sentry_flutter.dart'; import 'package:sentry_flutter/src/app_start/standalone/standalone_app_start_integration.dart'; -import 'package:sentry_flutter/src/app_start/ui_load_attached/native_app_start_integration.dart'; await SentryFlutter.init((options) { - for (final integration in options.integrations) { - if (integration is NativeAppStartIntegration || - integration is StandaloneAppStartIntegration) { - options.removeIntegration(integration); - } + final appStartIntegrations = options.integrations + .whereType() + .toList(); + for (final integration in appStartIntegrations) { + options.removeIntegration(integration); } }); ``` -App start integrations are only registered on the platforms that support them, so don't assume either one is present — looking them up with `firstWhere` throws when they aren't. +The integration is only registered on supported platforms. This lookup is safe when it is absent. Web and desktop initial-display tracking is handled separately by `GenericAppStartIntegration`. diff --git a/includes/dart-integrations/dio.mdx b/includes/dart-integrations/dio.mdx index 85a444a2c0a27..08bac9ffa3d56 100644 --- a/includes/dart-integrations/dio.mdx +++ b/includes/dart-integrations/dio.mdx @@ -1,6 +1,6 @@ --- -title: Logging Integration -description: "Learn more about the Sentry Dio integration for the Dart SDK." +title: Dio Integration +description: 'Learn more about the Sentry Dio integration for the Dart SDK.' platforms: - dart - flutter @@ -13,19 +13,18 @@ The `sentry_dio` library provides [Dio](https://pub.dev/packages/dio) support fo ## Install -To add the Dio integration, add the `sentry_dio` dependency. +To add the Dio integration, add the `sentry_dio` dependency. Version 10 requires Dio `5.8.0` or later within the v5 series. Match the Sentry integration package version to your core SDK version. ```yml {filename:pubspec.yaml} dependencies: sentry: ^{{@inject packages.version('sentry.dart', '6.4.0') }} sentry_dio: ^{{@inject packages.version('sentry.dart.dio', '6.4.0') }} - dio: ^4.0.0 + dio: ^5.8.0 ``` ## Configure -Configuration should happen as early as possible in your application's lifecycle. - +Configuration should happen as early as possible in your application's lifecycle. In Flutter apps, initialize with `SentryFlutter.init` instead of the core `Sentry.init` shown below. ```dart import 'package:sentry_dio/sentry_dio.dart'; @@ -48,7 +47,7 @@ dio.addSentry(...); ## Reporting Bad HTTP Requests as Errors -The `Interceptors` can also catch exceptions that may occur during requests — for example [DioError](https://pub.dev/documentation/dio2/latest/dio2/DioError-class.html). +The `Interceptors` can also catch exceptions that may occur during requests — for example [DioException](https://pub.dev/documentation/dio/latest/dio/DioException-class.html). ```dart import 'package:sentry_dio/sentry_dio.dart'; @@ -62,7 +61,6 @@ final response = await dio.get('https://wrong-url.dev/'); This is an opt-out feature. The following example shows how to disable it: - ```dart {2} await Sentry.init((options) { options.captureFailedRequests = false; @@ -88,13 +86,13 @@ dio.addSentry( **Default Behavior:** -By default, `failedRequestStatusCodes` is set to `[SentryStatusCode.range(500, 599)]`, which captures server errors (status codes 500-599). +By default, `failedRequestStatusCodes` is set to `[SentryStatusCode.range(500, 599)]`, which captures server errors (status codes 500-599). In v10, connection failures without a status code, such as timeouts, DNS failures, and certificate errors, are also captured when the target matches. Caller-initiated cancellations without a status code are excluded. ### Failed Request Targets To control which URLs should have failed requests captured, use the `failedRequestTargets` option. This is useful when you only want to capture errors from specific APIs or domains. -The SDK will only capture HTTP client errors if the request URL matches one of the provided targets. Targets can be: +In v10, the SDK matches targets against the resolved full URL, including the host, rather than the relative request path. Requests to the configured Sentry DSN host are excluded to prevent recursive reporting. The SDK will only capture HTTP client errors if the URL matches one of the provided targets. Targets can be: - Strings that appear anywhere in the URL - Regular expression patterns @@ -115,7 +113,13 @@ dio.addSentry( **Default Behavior:** -By default, `failedRequestTargets` is set to `['.*']`, which matches all URLs. This means all failed requests are captured (subject to `failedRequestStatusCodes`). +By default, `failedRequestTargets` is set to `['.*']`, which matches all URLs. HTTP responses are subject to `failedRequestStatusCodes`; connection failures follow the rules above. + +### Error Details + +In v10, captured Dio errors use the stable type `DioException`, including in obfuscated builds. Default values are `HTTP Client Error with status code: ` for responses or `HTTP Client Error: ` for connection failures. Custom Dio string builders are preserved. + +Response status and metadata are attached to `event.contexts.response`. Response bodies remain on `hint.response` for inspection in `beforeSend`; they are not automatically attached to the event. ## Tracing for HTTP Requests @@ -138,7 +142,7 @@ Before starting, ensure: ### Configure -Call `addSentry()` on your instance of `Dio: +Call `addSentry()` on your instance of `Dio`: ```dart import 'package:sentry_dio/sentry_dio.dart'; @@ -179,6 +183,7 @@ Future makeWebRequestWithDio() async { await Sentry.captureException(exception, stackTrace: stackTrace); } finally { await span.finish(); + await transaction.finish(); } } ``` diff --git a/includes/dart-integrations/drift-instrumentation.mdx b/includes/dart-integrations/drift-instrumentation.mdx index ac3bb1bfe2f10..3eb776b9a178a 100644 --- a/includes/dart-integrations/drift-instrumentation.mdx +++ b/includes/dart-integrations/drift-instrumentation.mdx @@ -1,6 +1,6 @@ --- title: Drift Database Instrumentation -description: "Learn more about the Sentry Drift Database Instrumentation for the Flutter SDK." +description: 'Learn more about the Sentry Drift Database Instrumentation for the Flutter SDK.' caseStyle: camelCase supportLevel: production sdk: sentry.dart.drift @@ -127,3 +127,7 @@ Future driftTest() async { To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project. Clicking **Performance** will open a page with transactions, where you can select the just recorded transaction with the name `driftTest`. + +## Span Attributes + +In v10, database spans identify the database system with `db.system.name` (`sqlite`) and the database name with `db.namespace`, when available. Use these keys in queries and span-filtering callbacks instead of the v9 keys `db.system` and `db.name`. diff --git a/includes/dart-integrations/firebase-remote-config.mdx b/includes/dart-integrations/firebase-remote-config.mdx index f49f9d97fac2c..850149a07aa33 100644 --- a/includes/dart-integrations/firebase-remote-config.mdx +++ b/includes/dart-integrations/firebase-remote-config.mdx @@ -15,7 +15,7 @@ The `sentry_firebase_remote_config` integration provides [Firebase Remote Config ## Prerequisites -1. [Sentry SDK](/platforms/dart/#configure) version `9.0.0` or higher. +1. The [Sentry Flutter SDK](/platforms/dart/guides/flutter/manual-setup/) is initialized. Match the integration package version to your Flutter SDK version. 2. Firebase Remote Config is set up. ## Install @@ -24,8 +24,8 @@ To use the `SentryFirebaseRemoteConfig` integration, add the `sentry_firebase_re ```yml {filename:pubspec.yaml} dependencies: - sentry: ^9.0.0 - sentry_firebase_remote_config: ^9.0.0 + sentry_flutter: ^{{@inject packages.version('sentry.dart.flutter') }} + sentry_firebase_remote_config: ^10.0.0 ``` ## Configure @@ -68,4 +68,4 @@ To view the recorded feature flag evaluation, log into [sentry.io](https://sentr Flag evaluations will appear in the "Feature Flag" section of Issue Details page as a table, with "suspect" flag predictions highlighted in yellow. -![Flag Change Suspect](./img/SuspectFlag.png) \ No newline at end of file +![Flag Change Suspect](./img/SuspectFlag.png) diff --git a/includes/dart-integrations/graphql.mdx b/includes/dart-integrations/graphql.mdx index f9aad81c43c01..7b436ce53fec2 100644 --- a/includes/dart-integrations/graphql.mdx +++ b/includes/dart-integrations/graphql.mdx @@ -1,6 +1,6 @@ --- title: GraphQL Integration -description: "Learn more about the Sentry GraphQL (sentry_link) integration for the Dart SDK." +description: 'Learn more about the Sentry GraphQL (sentry_link) integration for the Dart SDK.' sidebar_order: 5 platforms: - dart @@ -21,6 +21,8 @@ It helps you capture: ## Compatibility +Version 10 of `sentry_link` requires `gql_link >=0.5.1 <2.0.0`. Match the Sentry integration version to your core SDK version. + `sentry_link` works with the `gql` ecosystem and is commonly used with: - [`gql_link`](https://pub.dev/packages/gql_link) diff --git a/includes/dart-integrations/hive-instrumentation.mdx b/includes/dart-integrations/hive-instrumentation.mdx index 6f82a6b2d0e5c..6af4279fb27d4 100644 --- a/includes/dart-integrations/hive-instrumentation.mdx +++ b/includes/dart-integrations/hive-instrumentation.mdx @@ -1,6 +1,6 @@ --- title: Hive Database Instrumentation -description: "Learn more about the Sentry Hive Database Instrumentation for the Flutter SDK." +description: 'Learn more about the Sentry Hive Database Instrumentation for the Flutter SDK.' caseStyle: camelCase supportLevel: production sdk: sentry.dart.hive @@ -105,3 +105,9 @@ Future hiveTest() async { To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project. Clicking **Performance** will open a page with transactions, where you can select the just recorded transaction with the name `hiveTest`. + +## Span Attributes + +In v10, database spans identify the database system with `db.system.name` (`flutter_hive`) and the database name with `db.namespace`, when available. Use these keys in queries and span-filtering callbacks instead of the v9 keys `db.system` and `db.name`. + +Database breadcrumbs also use `db.system.name` and `db.namespace`. diff --git a/includes/dart-integrations/http-integration.mdx b/includes/dart-integrations/http-integration.mdx index c7b9f4d6259f3..f22b8d72c2000 100644 --- a/includes/dart-integrations/http-integration.mdx +++ b/includes/dart-integrations/http-integration.mdx @@ -1,6 +1,6 @@ --- title: HTTP Integration -description: "Learn more about the Sentry HTTP integration for the Dart SDK." +description: 'Learn more about the Sentry HTTP integration for the Dart SDK.' sidebar_order: 2 platforms: - dart @@ -79,7 +79,6 @@ Response details: This is an opt-out feature. The following example shows how to disable it: - ```dart import 'package:sentry/sentry.dart'; @@ -177,7 +176,6 @@ try { By default, `failedRequestTargets` is set to `['.*']`, which matches all URLs. This means all failed requests are captured (subject to `failedRequestStatusCodes`). - ## Tracing for HTTP Requests @@ -224,3 +222,11 @@ await Sentry.startSpan('webrequest', (span) async { } }, parentSpan: null); ``` + +## HTTP Error and Span Data + +In v10, failed status responses use the stable exception type `SentryHttpClientError` with a message such as `HTTP Client Error with status code: 500`. The message has no `Exception:` prefix. Requests to the configured Sentry DSN host are excluded from failed-request capture. + +HTTP spans use `url.full` for the URL and `http.response.body.size` for the response body size. Use these keys in custom span processing and queries. + +On iOS and macOS, Dart-side `captureFailedRequests` does not enable capture by native network instrumentation. Set `captureNativeFailedRequests = true` separately if you need native failed-request events. diff --git a/includes/dart-integrations/isar-instrumentation.mdx b/includes/dart-integrations/isar-instrumentation.mdx index 280a6ef1ad09e..319c77892751e 100644 --- a/includes/dart-integrations/isar-instrumentation.mdx +++ b/includes/dart-integrations/isar-instrumentation.mdx @@ -1,6 +1,6 @@ --- title: Isar Database Instrumentation -description: "Learn more about the Sentry Isar Database Instrumentation for the Flutter SDK." +description: 'Learn more about the Sentry Isar Database Instrumentation for the Flutter SDK.' caseStyle: camelCase supportLevel: production sdk: sentry.dart.flutter @@ -134,3 +134,11 @@ Future runApp() async { ### 2. View the Transaction on Sentry.io To view the recorded transaction, log into [sentry.io](https://sentry.io). Use the left sidebar to navigate to the **Performance** page. Select your project and scroll down to the transactions table to see the just recorded transaction with the name `isarTest`. You can also use the search bar to find the transaction. Click on the transaction to open its **Transaction Summary** page for more performance details. + +## Span Attributes + +In v10, database spans identify the database system with `db.system.name` (`isar`) and the database name with `db.namespace`, when available. Use these keys in queries and span-filtering callbacks instead of the v9 keys `db.system` and `db.name`. + +Collection names use `db.collection.name`. + +Database breadcrumbs also use `db.system.name` and `db.namespace`. diff --git a/includes/dart-integrations/logging.mdx b/includes/dart-integrations/logging.mdx index 175006ae59fff..807d1960d9b75 100644 --- a/includes/dart-integrations/logging.mdx +++ b/includes/dart-integrations/logging.mdx @@ -1,6 +1,6 @@ --- title: Logging Integration -description: "Integrate Sentry with the Dart Logging package to capture events, breadcrumbs, and automatically send structured logs to Sentry." +description: 'Integrate Sentry with the Dart Logging package to capture events, breadcrumbs, and automatically send structured logs to Sentry.' caseStyle: canonical supportLevel: production sidebar_order: 3 @@ -11,7 +11,7 @@ platforms: This integration connects Sentry with the popular [Dart logging package](https://pub.dev/packages/logging), providing the following capabilities: -- Sends your log messages as [Sentry Structured Logs](/platforms/dart/logs/) (enabled by default in `9.28.0` and above) +- Sends your log messages as [Sentry Structured Logs](/platforms/dart/logs/) (enabled automatically when this integration is added in v10) - Captures breadcrumbs from your log calls - Converts error-level logs into Sentry error events - Works with your existing logging code @@ -19,10 +19,12 @@ This integration connects Sentry with the popular [Dart logging package](https:/ This page covers the instrumentation of the **Dart Logging package**. -This integration also supports creating structured logs. However, if you're looking to set up Sentry structured logs in general, visit our [Structured Logs](/platforms/dart/logs/) documentation. +This integration also supports creating structured logs. However, if you're looking to set up Sentry structured logs in general, visit our [Structured Logs](/platforms/dart/logs/) documentation. +On SDK v9, `enableLogs` controls automatic forwarding of log records. In v10, that option is removed. Set `minSentryLogLevel: Level.OFF` to stop forwarding structured logs while retaining breadcrumbs and error events. + ## Install To add the Logging integration, add the `sentry_logging` dependency. @@ -36,7 +38,7 @@ dependencies: ## Configure -Add the `LoggingIntegration` to your `Sentry.init` call: +Add `LoggingIntegration` during SDK initialization. In Flutter apps, use `SentryFlutter.init` so native crash reporting and Flutter integrations are also initialized. The example below uses the core Dart SDK: ```dart import 'package:sentry_logging/sentry_logging.dart'; @@ -55,11 +57,11 @@ Future main() async { ### Configuration Options -| Parameter | Default | Description | -|-----------|---------|-------------| -| `minBreadcrumbLevel` | `Level.INFO` | Minimum level for creating breadcrumbs | -| `minEventLevel` | `Level.SEVERE` | Minimum level for creating error events | -| `minSentryLogLevel` | `Level.INFO` | Minimum level for sending structured logs | +| Parameter | Default | Description | +| -------------------- | -------------- | ----------------------------------------- | +| `minBreadcrumbLevel` | `Level.INFO` | Minimum level for creating breadcrumbs | +| `minEventLevel` | `Level.SEVERE` | Minimum level for creating error events | +| `minSentryLogLevel` | `Level.INFO` | Minimum level for sending structured logs | You can customize which log levels trigger different Sentry features: @@ -69,7 +71,7 @@ await Sentry.init( options.dsn = '___PUBLIC_DSN___'; options.addIntegration(LoggingIntegration( minBreadcrumbLevel: Level.INFO, // Breadcrumbs for INFO and above - minEventLevel: Level.SEVERE, // Error events for SEVERE and above + minEventLevel: Level.SEVERE, // Error events for SEVERE and above minSentryLogLevel: Level.INFO, // Structured logs for INFO and above )); }, @@ -89,8 +91,8 @@ void testLogging() { // This creates a breadcrumb AND a structured log (Level.INFO >= defaults) log.info('User logged in successfully'); - - // This creates a breadcrumb AND a structured log (Level.WARNING >= defaults) + + // This creates a breadcrumb AND a structured log (Level.WARNING >= defaults) log.warning('Rate limit approaching'); try { @@ -103,7 +105,8 @@ void testLogging() { ``` ### What You'll See in Sentry: -- **Breadcrumbs**: All three log calls will appear as breadcrumbs on the error event + +- **Breadcrumbs**: The earlier `info` and `warning` calls appear on the error event. The `severe` call is added as a breadcrumb after its own event is captured. - **Error Event**: The `severe` log creates a full error event with stack trace - **Structured Logs**: Navigate to **Logs** in your Sentry project to see all three entries as searchable structured logs diff --git a/includes/dart-integrations/sqflite-instrumentation.mdx b/includes/dart-integrations/sqflite-instrumentation.mdx index 0b068609aedfa..6690e526fa7cf 100644 --- a/includes/dart-integrations/sqflite-instrumentation.mdx +++ b/includes/dart-integrations/sqflite-instrumentation.mdx @@ -1,6 +1,6 @@ --- title: sqflite Database Instrumentation -description: "Learn more about the Sentry sqflite Database Instrumentation for the Flutter SDK." +description: 'Learn more about the Sentry sqflite Database Instrumentation for the Flutter SDK.' caseStyle: camelCase supportLevel: production sdk: sentry.dart.sqflite @@ -172,3 +172,9 @@ Future sqfliteTest() async { To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project (via main navigation menu Dashboards). Clicking **View Transactions** (in _Quick Links_ section) will open a page with transactions, where you can select the just recorded transaction with the name `sqfliteTest`. + +## Span Attributes + +In v10, database spans identify the database system with `db.system.name` (`sqlite`) and the database name with `db.namespace`, when available. Use these keys in queries and span-filtering callbacks instead of the v9 keys `db.system` and `db.name`. + +Database breadcrumbs also use `db.system.name` and `db.namespace`. diff --git a/platform-includes/configuration/auto-session-tracking/dart.flutter.mdx b/platform-includes/configuration/auto-session-tracking/dart.flutter.mdx index aee14f614b377..6b7fd5c9b98b7 100644 --- a/platform-includes/configuration/auto-session-tracking/dart.flutter.mdx +++ b/platform-includes/configuration/auto-session-tracking/dart.flutter.mdx @@ -4,7 +4,7 @@ By default, the session is terminated once the application is in the background ```dart {2} await SentryFlutter.init((options) { - options.autoSessionTrackingInterval = const Duration(seconds: 60) + options.autoSessionTrackingInterval = const Duration(seconds: 60); }); ``` diff --git a/platform-includes/feature-flags/evaluation-tracking-index/dart.mdx b/platform-includes/feature-flags/evaluation-tracking-index/dart.mdx index a7a686a7139f5..fa04d48eed68b 100644 --- a/platform-includes/feature-flags/evaluation-tracking-index/dart.mdx +++ b/platform-includes/feature-flags/evaluation-tracking-index/dart.mdx @@ -7,7 +7,7 @@ If you use a third-party SDK to evaluate feature flags, you can enable Sentry to Call `Sentry.addFeatureFlag` to track feature flag evaluations: ```dart -Sentry.addFeatureFlag("feature_flag_a", true); +await Sentry.addFeatureFlag("feature_flag_a", true); ``` -Calling this function multiple times with the same flag name will override the previous value. +Calling this function multiple times with the same flag name overrides the previous value. In v10, evaluations are stored on the current scope and added to the active span. No separate `FeatureFlagsIntegration` is required. diff --git a/platform-includes/getting-started-prerequisites/dart.flutter.mdx b/platform-includes/getting-started-prerequisites/dart.flutter.mdx new file mode 100644 index 0000000000000..47c73511ff8b7 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/dart.flutter.mdx @@ -0,0 +1,10 @@ +## Prerequisites + +These instructions use Sentry Flutter SDK v10. You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- A Flutter application using **Flutter 3.44.0** and **Dart 3.12.0** or later +- **Android API 21** or later for Android apps +- **iOS 15.0** or **macOS 12.0** or later for Apple apps, with Swift Package Manager enabled + +For an existing Sentry integration, review the migration guide before upgrading to v10. diff --git a/platform-includes/logs/options/dart.flutter.mdx b/platform-includes/logs/options/dart.flutter.mdx index daae4f0b4ad18..251057429a890 100644 --- a/platform-includes/logs/options/dart.flutter.mdx +++ b/platform-includes/logs/options/dart.flutter.mdx @@ -6,7 +6,7 @@ To filter logs, or update them before they are sent to Sentry, you can use the ` await SentryFlutter.init( (options) { options.dsn = "___PUBLIC_DSN___"; - options.beforeSendLog = (log) { + options.beforeSendLog = (log, hint) { if (log.level == SentryLogLevel.info) { // Filter out all info logs return null; @@ -18,4 +18,4 @@ await SentryFlutter.init( ); ``` -The `beforeSend` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it. +The `beforeSendLog` callback receives a log object and a `Hint`. Return the log to send it or `null` to discard it. On SDK v9, the callback takes only the log parameter. diff --git a/platform-includes/logs/options/dart.mdx b/platform-includes/logs/options/dart.mdx index 41539620bbf1a..8636ee2c10d3b 100644 --- a/platform-includes/logs/options/dart.mdx +++ b/platform-includes/logs/options/dart.mdx @@ -6,7 +6,7 @@ To filter logs, or update them before they are sent to Sentry, you can use the ` await Sentry.init( (options) { options.dsn = "___PUBLIC_DSN___"; - options.beforeSendLog = (log) { + options.beforeSendLog = (log, hint) { if (log.level == SentryLogLevel.info) { // Filter out all info logs return null; @@ -18,4 +18,4 @@ await Sentry.init( ); ``` -The `beforeSend` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it. +The `beforeSendLog` callback receives a log object and a `Hint`. Return the log to send it or `null` to discard it. On SDK v9, the callback takes only the log parameter. diff --git a/platform-includes/logs/requirements/dart.flutter.mdx b/platform-includes/logs/requirements/dart.flutter.mdx index 38ba71d783b6c..cb3a4ea5d6687 100644 --- a/platform-includes/logs/requirements/dart.flutter.mdx +++ b/platform-includes/logs/requirements/dart.flutter.mdx @@ -1,5 +1,7 @@ -Logs for Flutter are supported in Sentry Flutter SDK version `9.0.0` and above, and are enabled by default in version `9.28.0` and above. +Logs are supported in SDK version `9.0.0` and above. In SDK v10, logs are always enabled: initialize the SDK and call `Sentry.logger`. - On SDK versions below `9.28.0`, logs are opt-in. Set `options.enableLogs = true` in your `SentryFlutter.init` to send them. + +On SDK versions below `9.28.0`, set `options.enableLogs = true` in `SentryFlutter.init` to send logs. In v9 releases from `9.28.0` onward, direct logger calls work without the flag, but automatic collection still uses `enableLogs`. The option is removed in v10; use `beforeSendLog` to filter logs. + diff --git a/platform-includes/logs/requirements/dart.mdx b/platform-includes/logs/requirements/dart.mdx index ab91422835201..790193840cf4a 100644 --- a/platform-includes/logs/requirements/dart.mdx +++ b/platform-includes/logs/requirements/dart.mdx @@ -1,5 +1,7 @@ -Logs for Dart are supported in Sentry Dart SDK version `9.0.0` and above, and are enabled by default in version `9.28.0` and above. +Logs are supported in SDK version `9.0.0` and above. In SDK v10, logs are always enabled: initialize the SDK and call `Sentry.logger`. - On SDK versions below `9.28.0`, logs are opt-in. Set `options.enableLogs = true` in your `Sentry.init` to send them. + +On SDK versions below `9.28.0`, set `options.enableLogs = true` in `Sentry.init` to send logs. In v9 releases from `9.28.0` onward, direct logger calls work without the flag, but automatic collection still uses `enableLogs`. The option is removed in v10; use `beforeSendLog` to filter logs. + diff --git a/platform-includes/logs/usage/dart.mdx b/platform-includes/logs/usage/dart.mdx index 272d1d8a93d81..9590baf230af1 100644 --- a/platform-includes/logs/usage/dart.mdx +++ b/platform-includes/logs/usage/dart.mdx @@ -1,6 +1,6 @@ -Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `Sentry.logger` APIs. +After initializing the SDK, send logs using the `Sentry.logger` APIs. In v10, the logger methods and their `fmt` variants return `void`; call them without `await`. -The `logger` namespace exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warning`, `error`, and `fatal`. +The `logger` namespace exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warn`, `error`, and `fatal`. Aside from the primary logging methods, we've provided a format text function, `Sentry.logger.fmt`, that you can use to insert properties into to your log entries. diff --git a/platform-includes/metrics/options/dart.flutter.mdx b/platform-includes/metrics/options/dart.flutter.mdx index bbd4f3d74f3d3..4d6ac84e1b79a 100644 --- a/platform-includes/metrics/options/dart.flutter.mdx +++ b/platform-includes/metrics/options/dart.flutter.mdx @@ -4,7 +4,7 @@ ### beforeSendMetric -Filter or modify metrics before sending. Return `null` to drop a metric. +Filter or modify metrics before sending. The callback receives a metric and a `Hint`; return `null` to drop the metric. On SDK v9, the callback takes only the metric parameter. @@ -14,7 +14,7 @@ import 'package:sentry_flutter/sentry_flutter.dart'; await SentryFlutter.init((options) { options.dsn = '___PUBLIC_DSN___'; - options.beforeSendMetric = (metric) { + options.beforeSendMetric = (metric, hint) { // Drop specific metrics if (metric.attributes.containsKey('debug')) { return null; @@ -32,9 +32,9 @@ await SentryFlutter.init((options) { -### Disable Metrics +### Drop All Metrics -Set `enableMetrics: false` to disable metrics collection entirely. +Metrics are always enabled in SDK v10. To prevent metrics from being sent, return `null` from `beforeSendMetric`. The `enableMetrics` option has been removed. @@ -44,7 +44,7 @@ import 'package:sentry_flutter/sentry_flutter.dart'; await SentryFlutter.init((options) { options.dsn = '___PUBLIC_DSN___'; - options.enableMetrics = false; + options.beforeSendMetric = (metric, hint) => null; }); ``` diff --git a/platform-includes/metrics/options/dart.mdx b/platform-includes/metrics/options/dart.mdx index b7c0fc93c994a..7392b6adf328b 100644 --- a/platform-includes/metrics/options/dart.mdx +++ b/platform-includes/metrics/options/dart.mdx @@ -4,7 +4,7 @@ ### beforeSendMetric -Filter or modify metrics before sending. Return `null` to drop a metric. +Filter or modify metrics before sending. The callback receives a metric and a `Hint`; return `null` to drop the metric. On SDK v9, the callback takes only the metric parameter. @@ -14,7 +14,7 @@ import 'package:sentry/sentry.dart'; await Sentry.init((options) { options.dsn = '___PUBLIC_DSN___'; - options.beforeSendMetric = (metric) { + options.beforeSendMetric = (metric, hint) { // Drop specific metrics if (metric.attributes.containsKey('debug')) { return null; @@ -32,9 +32,9 @@ await Sentry.init((options) { -### Disable Metrics +### Drop All Metrics -Set `enableMetrics: false` to disable metrics collection entirely. +Metrics are always enabled in SDK v10. To prevent metrics from being sent, return `null` from `beforeSendMetric`. The `enableMetrics` option has been removed. @@ -45,7 +45,7 @@ import 'package:sentry/sentry.dart'; // Disable metrics await Sentry.init((options) { options.dsn = '___PUBLIC_DSN___'; - options.enableMetrics = false; + options.beforeSendMetric = (metric, hint) => null; }); ``` diff --git a/platform-includes/replay/privacy-configuration/dart.flutter.mdx b/platform-includes/replay/privacy-configuration/dart.flutter.mdx index 7ff639cbbd752..79d25860b7ae7 100644 --- a/platform-includes/replay/privacy-configuration/dart.flutter.mdx +++ b/platform-includes/replay/privacy-configuration/dart.flutter.mdx @@ -7,14 +7,14 @@ This approach allows the SDK to automatically mask widgets that are part of the The following options can be configured in the `options.privacy` field of your Sentry Flutter SDK, in `SentryFlutter.init((options) { ... })`: -| Key | Type | Default | Description | -| ------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| maskAllText | `bool` | `true` | Mask all text content. Draws a rectangle of text bounds with text color on top. Currently `Text`, `EditableText` and `RichText` widgets are masked. | -| maskAllImages | `bool` | `true` | Mask content of all images. Draws a rectangle of image bounds with image's dominant color on top. Currently `Image` widgets are masked. | -| maskAssetImages | `bool` | `true` | Mask asset images coming from the root asset bundle. | -| mask<T extends Widget>() | `void` | / | Mask given widget type `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | -| unmask<T extends Widget>() | `void` | / | Unmask given widget type `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | -| maskCallback<T extends Widget>() | `void` | / | Provide a custom callback to decide whether to mask the widget of class `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | +| Key | Type | Default | Description | +| -------------------------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| maskAllText | `bool` | `true` | Mask all text content. Draws a rectangle of text bounds with text color on top. Currently `Text`, `EditableText` and `RichText` widgets are masked. | +| maskAllImages | `bool` | `true` | Mask content of all images. Draws a rectangle of image bounds with image's dominant color on top. Currently `Image` widgets are masked. | +| maskAssetImages | `bool` | `false` | Mask asset images coming from the root asset bundle. | +| mask<T extends Widget>() | `void` | / | Mask given widget type `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | +| unmask<T extends Widget>() | `void` | / | Unmask given widget type `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | +| maskCallback<T extends Widget>() | `void` | / | Provide a custom callback to decide whether to mask the widget of class `T` (or subclasses of `T`). Note: masking rules are called in the order they're added so if a previous rule already makes a decision, this rule won't be called. | For example, you can explicitly mask or unmask widgets by type, or you can even have a callback to decide whether a specific widget instance should be masked: @@ -35,13 +35,19 @@ If you find that data isn't being masked with the default settings, please let u -To disable masking for `Screenshots` and `Session Replay` (not to be used on applications with sensitive data): +To disable the default text and image masking rules for screenshots and Session Replay, use the following options. This does not disable `SensitiveContent` masking, `SentryMask`, or custom rules. Only use these settings when the content is safe to capture: ```dart options.privacy.maskAllText = false; options.privacy.maskAllImages = false; ``` +## SensitiveContent Widgets + +In v10, the default rules mask Flutter `SensitiveContent` widgets marked `ContentSensitivity.sensitive` or `ContentSensitivity.autoSensitive`. Unrecognized sensitivity values are also masked. `ContentSensitivity.notSensitive` continues through other masking rules; it does not unmask the content by itself. + +These rules apply to both screenshots and Session Replay. Custom rules and `SentryUnmask` take precedence over the default rules, so verify your configuration if you override masking. + ## Third Party Widgets The Sentry Flutter SDK cannot automatically mask widgets from third party packages. @@ -51,4 +57,4 @@ For example, if you are using the [FlutterMap](https://pub.dev/packages/flutter_ ```dart options.privacy.mask(); -``` \ No newline at end of file +```