Add File IO instrumentation docs (#5895)

Co-authored-by: Isabel <[email protected]>

Author: marandaneto

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

@@ -15,5 +15,6 @@ Sentry's Dart SDK enables automatic reporting of errors, messages, and exception
 - [Performance Monitoring](/product/performance/) creates transactions for:
     - [HTTP requests](/platforms/dart/configuration/integrations/http-integration/#performance-monitoring-for-http-requests)
     - [Dio HTTP library](/platforms/dart/configuration/integrations/dio/#performance-monitoring-for-http-requests)
+    - [File I/O Integration](/platforms/dart/configuration/integrations/file/)
 - [Logging Integration](/platforms/dart/configuration/integrations/logging)
 - [Dio Integration](/platforms/dart/configuration/integrations/dio/)

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

@@ -30,6 +30,7 @@ Features:
   - [Cold and warm app start](/platforms/flutter/performance/instrumentation/automatic-instrumentation/#app-start-instrumentation)
   - [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/)
 - [Logging Integration](/platforms/dart/configuration/integrations/logging)
 - [Screenshot attachments for errors](/platforms/flutter/enriching-events/screenshots/)
 - Limited support for Flutter Web, Windows, and Linux

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

@@ -31,3 +31,15 @@ The span finishes once the request has been executed. The span `status` depends
 When the HTTP request 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).
 
 Learn more in our [Dio integration documentation](/platforms/dart/configuration/integrations/dio/#performance-monitoring-for-http-requests).
+
+### 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`).
+
+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.
+
+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).
+
+For more information see our [file I/O integration](/platforms/dart/configuration/integrations/file/).

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

@@ -0,0 +1,86 @@
+---
+title: File I/O
+sidebar_order: 5
+description: "Learn more about the Sentry file I/O integration for the Dart SDK."
+---
+
+<Include name="beta-note.mdx" />
+
+The `sentry_file` library provides [File](https://api.dart.dev/stable/2.18.5/dart-io/File-class.html) support for Sentry wrapping the `File` class with a `SentryFile` wrapper. The `SentryFile` is able to run performance monitoring for `File` operations.
+
+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`.
+
+<Note>
+
+The File I/O integration is only available for the `dart:io:File` class, not for the `dart:html:File` class.
+
+</Note>
+
+## Install
+
+To use the `SentryFile` wrapper, add the `sentry_file` dependency.
+
+```yml {filename:pubspec.yaml}
+dependencies:
+  sentry: ^{{ packages.version('sentry.dart', '6.18.0') }}
+  sentry_file: ^{{ packages.version('sentry.dart.file', '6.18.0') }}
+```
+
+## Verify
+
+<Note>
+
+Capturing transactions requires that you first <PlatformLink to="/performance/">set up performance monitoring</PlatformLink> if you haven't already.
+
+</Note>
+
+```dart
+import 'package:sentry/sentry.dart';
+import 'package:sentry_file/sentry_file.dart';
+import 'dart:io';
+
+Future<void> main() async {
+  await Sentry.init(
+    (options) {
+      options.dsn = 'https://[email protected]/example';
+      // To set a uniform sample rate
+      options.tracesSampleRate = 1.0;
+    },
+    appRunner: runApp, // Init your App.
+  );
+}
+
+Future<void> runApp() async {
+  final file = File('my_file.txt');
+  // Call the Sentry extension method to wrap up the File
+  final sentryFile = file.sentryTrace();
+
+  // Start a transaction if there's no active transaction
+  final transaction = Sentry.startTransaction(
+    'MyFileExample',
+    'file',
+    bindToScope: true,
+  );
+
+  // create the File
+  await sentryFile.create();
+  // Write some content
+  await sentryFile.writeAsString('Hello World');
+  // Read the content
+  final text = await sentryFile.readAsString();
+
+  print(text);
+
+  // Delete the file
+  await sentryFile.delete();
+
+  // Finish the transaction
+  await transaction.finish(status: SpanStatus.ok());
+
+  await Sentry.close();
+}
+```
+
+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 `MyFileExample`.

src/platforms/flutter/common/configuration/integrations/user-interaction-instrumentation.mdx

@@ -10,11 +10,7 @@ categories:
 
 _(New in version 6.17.0)_
 
-<Note>
-
-This feature is currently in Beta. Beta features are still in-progress and may have bugs. We recognize the irony.
-
-</Note>
+<Include name="beta-note.mdx" />
 
 The UI instrumentation, once enabled, captures transactions and adds breadcrumbs for a set of different user interactions, which include clicks, long clicks, taps, and so on. The SDK composes the transaction name from the `key` of the `Widget` that captured the user interaction (for example, `login_button`). The transaction operation is set to `ui.action.click`.
 

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

@@ -213,3 +213,15 @@ The `SentryAssetBundle` instrumentation starts a span out of the active transact
 The `enableStructuredDataTracing` feature is available in Beta. Beta features are still in-progress and may have bugs. We recognize the irony.
 
 </Note>
+
+### 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`).
+
+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.
+
+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).
+
+Learn more about our [file I/O integration](/platforms/dart/configuration/integrations/file/).