sqflite integration for Flutter (#6500)

Co-authored-by: Karl Heinz Struggl <kahest@users.noreply.github.com>

Author: marandaneto

src/platform-includes/getting-started-primer/flutter.mdx

@@ -33,6 +33,7 @@ Features:
   - [Slow and frozen frames](/platforms/flutter/performance/instrumentation/automatic-instrumentation/#slow-and-frozen-frames)
   - [AssetBundle Instrumentation](/platforms/flutter/performance/instrumentation/automatic-instrumentation/#assetbundle-instrumentation)
   - [File I/O Integration](/platforms/dart/configuration/integrations/file/)
+  - [sqflite Database Instrumentation](/platforms/flutter/configuration/integrations/sqflite-instrumentation/)
 - [Logging Integration](/platforms/dart/configuration/integrations/logging)
 - [Screenshot attachments for errors](/platforms/flutter/enriching-events/screenshots/)
 - [View Hierarchy attachments for errors](/platforms/flutter/enriching-events/viewhierarchy/)

src/platforms/android/configuration/integrations/file-io.mdx

@@ -17,7 +17,7 @@ Supported in Sentry Android Gradle Plugin version `3.0.0` and above.
 
 The [Sentry Android Gradle Plugin](/platforms/android/gradle/) provides file I/O support through bytecode manipulation. The source can be found [on GitHub](https://github.com/getsentry/sentry-android-gradle-plugin/tree/main/plugin-build/src/main/kotlin/io/sentry/android/gradle/instrumentation).
 
-On this page, we get you up and running with Sentry's file I/O integration, so that it will automatically start a span out of the active transaction, bound to the scope for each file input/output stream operation.
+On this page, we get you up and running with Sentry's file I/O integration, so that it will automatically start a span from an active transaction that's bound to the scope of each file input/output stream operation.
 
 ## Install
 

src/platforms/android/configuration/integrations/fragment.mdx

@@ -10,7 +10,7 @@ categories:
 
 The `sentry-android-fragment` library provides [Fragment](https://developer.android.com/jetpack/androidx/releases/fragment) support for Sentry using the [FragmentLifecycleIntegration](https://github.com/getsentry/sentry-java/blob/a5f30b43b1dad2634ce020809f3b52e0d564a22a/sentry-android-fragment/src/main/java/io/sentry/android/fragment/FragmentLifecycleIntegration.kt). The source can be found [on GitHub](https://github.com/getsentry/sentry-java/tree/main/sentry-android-fragment/src/main/java/io/sentry/android/fragment).
 
-On this page, we get you up and running with Sentry's Fragment Integration, so that it will automatically add a breadcrumb for each fragment's lifecycle and start a span out of the active transaction bound to the scope for each launch of a fragment.
+On this page, we get you up and running with Sentry's Fragment Integration, so that it will automatically add a breadcrumb for each fragment's lifecycle and start a span from an active transaction that's bound to the scope of each launch of a fragment.
 
 ## Auto-Installation With the Sentry Android Gradle Plugin
 
@@ -46,7 +46,7 @@ plugins {
 
 Then, initialize the [Android SDK](/platforms/android/#configure).
 
-The Android SDK automatically adds the `FragmentLifecycleIntegration` if the `sentry-android-fragment` dependency was found on the classpath. The integration is added with both `enableFragmentLifecycleBreadcrumbs` and `enableAutoFragmentLifecycleTracing` enabled. 
+The Android SDK automatically adds the `FragmentLifecycleIntegration` if the `sentry-android-fragment` dependency was found on the classpath. The integration is added with both `enableFragmentLifecycleBreadcrumbs` and `enableAutoFragmentLifecycleTracing` enabled.
 
 However, you can still override the default behaviour by adding your own instance of the `FragmentLifecycleIntegration`. For that, refer to the [manual installation](/platforms/android/configuration/integrations/fragment/#configure) section below.
 

src/platforms/android/configuration/integrations/room-and-sqlite.mdx

@@ -17,7 +17,7 @@ Supported in Sentry Android Gradle Plugin version `3.0.0` and above.
 
 The [Sentry Android Gradle Plugin](/platforms/android/gradle/) provides Room and AndroidX SQLite support through bytecode manipulation. The source can be found [on GitHub](https://github.com/getsentry/sentry-android-gradle-plugin/tree/main/plugin-build/src/main/kotlin/io/sentry/android/gradle/instrumentation).
 
-On this page, we get you up and running with Sentry's Room and SQLite Integration, so that it will automatically start a span out of the active transaction, bound to the scope for each sqlite/dao query.
+On this page, we get you up and running with Sentry's Room and SQLite Integration, so that it will automatically start a span from an active transaction that's bound to the scope of each sqlite/dao query.
 
 ## Install
 

src/platforms/dart/common/performance/instrumentation/automatic-instrumentation.mdx

@@ -38,8 +38,8 @@ The Sentry-specific file I/O implementation starts a span out of the active span
 
 In addition, the span contains other useful information such as `file.size` (raw number of bytes), `file.path` (an absolute path to the file), and `file.async` (`true` if the called method returns a `Future`, or `false` if it's a `Sync` call) as part of the `data` payload.
 
-The span finishes once the operation has been executed. The span `status` is set to `SpanStatus.ok` if successful or `SpanStatus.internalError` if there was any error.
+The span finishes once the operation has been executed. The span `status` is then set to `SpanStatus.ok` if successful, or `SpanStatus.internalError` if there was an error.
 
-When the operation throws an `Exception`, Sentry's SDK associates this exception to the running span. If you haven't set the SDK to swallow the exception and capture it, the span and `SentryEvent` will be linked when viewing it on the **Issue Details** page in [sentry.io](https://sentry.io).
+When the operation throws an `Exception`, Sentry's SDK associates it with the running span. If you haven't set the SDK to swallow and capture the exception, the span and `SentryEvent` will be shown as linked on the **Issue Details** page in [sentry.io](https://sentry.io).
 
 For more information see our [file I/O integration](/platforms/dart/configuration/integrations/file/).

src/platforms/dart/configuration/integrations/file.mdx

@@ -8,7 +8,7 @@ The `sentry_file` library provides [File](https://api.dart.dev/stable/2.18.5/dar
 
 The source can be found [on GitHub](https://github.com/getsentry/sentry-dart/tree/main/file/).
 
-On this page, we get you up and running with Sentry's file I/O integration, so that it will automatically start a span out of the active transaction, bound to the scope for operations such as `copy`, `create`, `delete`, `open`, `rename`, `read`, and `write`.
+On this page, we get you up and running with Sentry's file I/O integration, so that it will automatically start a span from an active transaction that's bound to the scope of each operation such as `copy`, `create`, `delete`, `open`, `rename`, `read`, and `write`.
 
 <Note>
 

src/platforms/flutter/common/configuration/integrations/sqflite-instrumentation.mdx

@@ -0,0 +1,74 @@
+---
+title: sqflite Database Instrumentation
+caseStyle: camelCase
+supportLevel: production
+sdk: sentry.dart.sqflite
+description: "Learn more about the Sentry sqflite Database Instrumentation for the Flutter SDK."
+categories:
+  - mobile
+---
+
+<Include name="beta-note.mdx" />
+
+_(New in version 7.2.0)_
+
+The [sentry_sqflite](https://pub.dev/packages/sentry_sqflite) package provides `sqflite` support for database instrumentation. The source can be found [on GitHub](https://github.com/getsentry/sentry-dart/tree/main/sqflite). Note, that to capture transactions, you have to first <PlatformLink to="/performance/">set up performance monitoring</PlatformLink>.
+
+## Install
+
+Add the `sentry_sqflite` dependency to install the sqflite database instrumentation.
+
+```yml {filename:pubspec.yaml}
+dependencies:
+  sentry_flutter: ^{{ packages.version('sentry.dart.flutter', '7.2.0') }}
+  sentry_sqflite: ^{{ packages.version('sentry.dart.sqflite', '7.2.0') }}
+  sqflite: ^2.0.0
+```
+
+## Configure
+
+There are four ways to configure the sqflite database instrumentation:
+
+By using the global `databaseFactory`, (which is used by the `openDatabase` method). With this approach, every call to `openDatabase` will be instrumented, including from other packages:
+
+```dart
+import 'package:sentry_sqflite/sentry_sqflite.dart';
+import 'package:sqflite/sqflite.dart';
+
+databaseFactory = SentrySqfliteDatabaseFactory();
+final database = await openDatabase('path/to/db');
+```
+
+If you're using the `FFI` factories, you can instrument the `SentrySqfliteDatabaseFactory` with its factory:
+
+```dart
+import 'package:sentry_sqflite/sentry_sqflite.dart';
+import 'package:sqflite/sqflite.dart';
+
+databaseFactory = SentrySqfliteDatabaseFactory(databaseFactory: databaseFactoryFfi);
+final database = await openDatabase('path/to/db');
+```
+
+By using the `openDatabaseWithSentry` wrapper. With this approach, only the database opened with this method will be instrumented:
+
+```dart
+import 'package:sentry_sqflite/sentry_sqflite.dart';
+import 'package:sqflite/sqflite.dart';
+
+final database = await openDatabaseWithSentry('path/to/db');
+// or final database = await openReadOnlyDatabaseWithSentry('path/to/db');
+```
+
+By using the `SentryDatabase` wrapper, which can be used to instrument any `Database` instance:
+
+```dart
+import 'package:sentry_sqflite/sentry_sqflite.dart';
+import 'package:sqflite/sqflite.dart';
+
+final database = await openDatabase('path/to/db');
+final sentryDatabase = SentryDatabase(database);
+```
+
+After configuring via one of the above methods, every `CRUD` operation, including database transactions and batches, will be automatically instrumented and sent to Sentry.
+
+The spans' `operation` are either `db`, `db.sql.execute`, `db.sql.query` or `db.sql.transaction`. Its `description` is the SQL statement using placeholders instead of its values due to the possibility of containing PII.

src/platforms/flutter/common/performance/instrumentation/automatic-instrumentation.mdx

@@ -97,7 +97,7 @@ Learn more in our [User Interaction Instrumentation](/platforms/flutter/configur
 
 ### http.Client Library Instrumentation
 
-The `http.Client` instrumentation, once added the `SentryHttpClient` and enabled the [performance](/platforms/flutter/performance/) feature, starts a span out of the active transaction bound to the scope for each HTTP Request. The SDK sets the span `operation` to `http.client` and `description` to request `$METHOD $url`; for example, `GET https://sentry.io`.
+The `http.Client` instrumentation, once added the `SentryHttpClient` and enabled the [performance](/platforms/flutter/performance/) feature, starts a span from an active transaction that's bound to the scope of each HTTP Request. The SDK sets the span `operation` to `http.client` and `description` to request `$METHOD $url`; for example, `GET https://sentry.io`.
 
 The span finishes once the request has been executed. The span `status` depends on either the HTTP Response `code` or `SpanStatus.internalError()` if the `code` does not match any of Sentry's `SpanStatus`.
 
@@ -107,7 +107,7 @@ For more information see our [SentryHttpClient integration](/platforms/dart/conf
 
 ### Dio HTTP Library Instrumentation
 
-The Dio instrumentation starts a span out of the active transaction bound to the scope for each HTTP request. The SDK sets the span `operation` to `http.client` and the `description` to request `$METHOD $url`. For example, `GET https://sentry.io`.
+The Dio instrumentation starts a span from an active transaction that's bound to the scope of each HTTP request. The SDK sets the span `operation` to `http.client` and the `description` to request `$METHOD $url`. For example, `GET https://sentry.io`.
 
 The span finishes once the request has been executed. The span `status` depends on either the HTTP response `code` or `SpanStatus.internalError()` if the `code` does not match any of Sentry's `SpanStatus` options.
 
@@ -198,9 +198,9 @@ Future<void> main() async {
 }
 ```
 
-The `SentryAssetBundle` instrumentation starts a span out of the active transaction bound to the scope for each `load` and `loadString` call. The SDK sets the span `operation` to `file.read`.
+The `SentryAssetBundle` instrumentation starts a span from an active transaction that's bound to the scope of each `load` and `loadString` call. The SDK sets the span `operation` to `file.read`.
 
-The `SentryAssetBundle` instrumentation starts a span out of the active transaction bound to the scope for each `loadStructuredData` call. The SDK sets the span `operation` to `serialize`.
+The `SentryAssetBundle` instrumentation starts a span from an active transaction that's bound to the scope of each `loadStructuredData` call. The SDK sets the span `operation` to `serialize`.
 
 The `loadStructuredData` is an opt-out feature. The following example shows how to disable it:
 
@@ -212,12 +212,22 @@ SentryAssetBundle(enableStructuredDataTracing: false)
 
 ### File I/O Instrumentation
 
-The Sentry-specific file I/O implementation starts a span out of the active span, bound to the scope for each file I/O operation. The SDK sets the span `operation` to `file.copy`, `file.write`, `file.delete`, `file.open`, `file.read` or `file.rename`, and `description` to `filename` (for example, `file.txt`).
+The Sentry-specific file I/O instrumentation starts a span from an active transaction that's bound to the scope of each file I/O operation. The SDK sets the span `operation` to `file.copy`, `file.write`, `file.delete`, `file.open`, `file.read` or `file.rename`, and `description` to `filename` (for example, `file.txt`).
 
 In addition, the span contains other useful information such as `file.size` (raw number of bytes), `file.path` (an absolute path to the file) and `file.async` (`true` if the called method returns a `Future`, or `false` if it's a `Sync` call) as part of the `data` payload.
 
-The span finishes once the operation has been executed. The span `status` is set to `SpanStatus.ok` if successful or `SpanStatus.internalError` if there was any error.
+The span finishes once the operation has been executed. The span `status` is then set to `SpanStatus.ok` if successful, or `SpanStatus.internalError` if there was an error.
 
-When the operation throws an `Exception`, Sentry's SDK associates this exception to the running span. If you haven't set the SDK to swallow the exception and capture it, the span and `SentryEvent` will be linked when viewing it on the **Issue Details** page in [sentry.io](https://sentry.io).
+When the operation throws an `Exception`, Sentry's SDK associates it with the running span. If you haven't set the SDK to swallow and capture the exception, the span and `SentryEvent` will be shown as linked on the **Issue Details** page in [sentry.io](https://sentry.io).
 
 Learn more about our [file I/O integration](/platforms/dart/configuration/integrations/file/).
+
+### sqflite Database Instrumentation
+
+The sqflite database instrumentation starts a span from an active transaction that's bound to the scope of each `CRUD` operation.
+
+The span finishes once the operation has been executed. The span `status` is then set to `SpanStatus.ok` if successful, or `SpanStatus.internalError` if there was an error.
+
+When the operation throws an `Exception`, Sentry's SDK associates it with the running span. If you haven't set the SDK to swallow and capture the exception, the span and `SentryEvent` will be shown as linked on the **Issue Details** page in [sentry.io](https://sentry.io).
+
+Learn more about our [sqflite Database Instrumentation](/platforms/flutter/configuration/integrations/sqflite-instrumentation/).