Feat: Document Dio for Dart/Flutter (#4857)

marandaneto · web-flow · commit ce079ff15c0f · 2022-03-22T07:19:11.000Z
diff --git a/src/includes/getting-started-primer/dart.mdx b/src/includes/getting-started-primer/dart.mdx
@@ -8,9 +8,12 @@ Sentry's Dart SDK enables automatic reporting of errors, messages, and exception
 
 - Breadcrumbs automatically captured:
   - by the [Dart SDK](/platforms/dart/enriching-events/breadcrumbs/#automatic-breadcrumbs)
-  - as well as `http` with the [Dart SDK](/platforms/dart/)
+  - by the [Logging Integration](/platforms/dart/configuration/integrations/logging)
+  - by the [Dio Integration](/platforms/dart/configuration/integrations/dio/)
 - [Attachments](/platforms/dart/enriching-events/attachments/) enrich your event by storing additional files, such as config or log files.
 - [User Feedback](/platforms/dart/enriching-events/user-feedback/) provides the ability to collect user information when an event occurs.
 - [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)
 - [Logging Integration](/platforms/dart/configuration/integrations/logging)
+- [Dio Integration](/platforms/dart/configuration/integrations/dio/)
diff --git a/src/includes/getting-started-primer/flutter.mdx b/src/includes/getting-started-primer/flutter.mdx
@@ -12,15 +12,18 @@ Features:
 - Offline storage of events
 - Events [enriched](/platforms/flutter/enriching-events/context/) with device data
 - Breadcrumbs automatically captured:
-    -  by the [Flutter SDK](/platforms/flutter/enriching-events/breadcrumbs/#automatic-breadcrumbs)
+    - by the [Dart SDK](/platforms/dart/enriching-events/breadcrumbs/#automatic-breadcrumbs)
+    - by the [Flutter SDK](/platforms/flutter/enriching-events/breadcrumbs/#automatic-breadcrumbs)
     - via the Native SDKs [Automatic Breadcrumbs for Android](/platforms/android/enriching-events/breadcrumbs/#automatic-breadcrumbs) and [Automatic Breadcrumbs for iOS](/platforms/apple/configuration/integrations/default/#sentryautobreadcrumbtrackingintegration)
-    - as well as `http` with the [Dart SDK](/platforms/dart/)
+    - by the [Logging Integration](/platforms/dart/configuration/integrations/logging)
+    - by the [Dio Integration](/platforms/dart/configuration/integrations/dio/)
 - [Release Health](/product/releases/health/) tracks crash free users and sessions
 - [Attachments](/platforms/flutter/enriching-events/attachments/) enrich your event by storing additional files, such as config or log files.
 - [User Feedback](/platforms/flutter/enriching-events/user-feedback/) provides the ability to collect user information when an event occurs.
 - [Performance Monitoring](/product/performance/) creates transactions for:
     - [HTTP requests](/platforms/flutter/performance/instrumentation/automatic-instrumentation/#httpclient-library-instrumentation)
     - [Routing Instumentation](/platforms/flutter/performance/instrumentation/automatic-instrumentation/#routing-instumentation)
+    - [Dio HTTP library](/platforms/dart/configuration/integrations/dio/#performance-monitoring-for-http-requests)
     - [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)
 - [Logging Integration](/platforms/dart/configuration/integrations/logging)
diff --git a/src/platforms/dart/common/performance/instrumentation/automatic-instrumentation.mdx b/src/platforms/dart/common/performance/instrumentation/automatic-instrumentation.mdx
@@ -18,6 +18,16 @@ The `http.Client` instrumentation, once added the `SentryHttpClient` and enabled
 
 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`.
 
-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.
+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.
 
 For more information see our [SentryHttpClient integration](/platforms/dart/configuration/integrations/http-integration/#performance-monitoring-for-http-requests).
+
+### Dio HTTP Library Instrumentation
+
+The Dio instrumentation starts a span out of the active span 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 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.
+
+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).
diff --git a/src/platforms/dart/configuration/integrations/dio.mdx b/src/platforms/dart/configuration/integrations/dio.mdx
@@ -0,0 +1,83 @@
+---
+title: Dio Integration
+sidebar_order: 4
+description: "Learn more about the Sentry Dio integration for the Dart SDK."
+---
+
+The `sentry_dio` library provides [Dio](https://pub.dev/packages/dio) support for Sentry using the [HttpClientAdapter](https://pub.dev/documentation/dio/latest/dio/HttpClientAdapter-class.html). It is able to collect breadcrumbs, run performance monitoring for HTTP requests, and capture events for failed requests.
+
+The source can be found [on GitHub](https://github.com/getsentry/sentry-dart/tree/main/dio/).
+
+<Note>
+
+This is an experimental feature. Experimental features are still a work-in-progress and may have bugs. We recognize the irony.
+
+</Note>
+
+## Install
+
+To add the Dio integration, add the `sentry_dio` dependency.
+
+```yml {filename:pubspec.yaml}
+dependencies:
+  sentry: ^{{ packages.version('sentry.dart', '6.4.0') }}
+  sentry_dio: ^{{ packages.version('sentry.dart.dio', '6.4.0') }}
+  dio: ^4.0.0
+```
+
+## Configure
+
+Configuration should happen as early as possible in your application's lifecycle.
+
+```dart
+import 'package:sentry_dio/sentry_dio.dart';
+import 'package:sentry/sentry.dart';
+
+Future<void> main() async {
+  await Sentry.init(
+    (options) {
+      options.dsn = '___PUBLIC_DSN___';
+    },
+    appRunner: initApp, // Init your App.
+  );
+}
+
+final dio = Dio();
+
+// This *must* be the last initialization step of the Dio setup.
+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/dio/latest/dio/DioError-class.html).
+This is currently an opt-in feature. The following example shows how to enable it.
+
+```dart
+import 'package:sentry_dio/sentry_dio.dart';
+
+final dio = Dio();
+
+dio.addSentry(captureFailedRequests: true);
+
+final response = await dio.get<String>('https://wrong-url.dev/');
+```
+
+## Performance Monitoring for HTTP Requests
+
+<Note>
+
+Capturing transactions requires that you first <PlatformLink to="/performance/">set up performance monitoring</PlatformLink> if you haven't already.
+
+</Note>
+
+The Dio integration starts a span out of the active span bound to the scope for each HTTP request.
+This is currently enabled by default. The following example shows how to disable it.
+
+```dart
+import 'package:sentry_dio/sentry_dio.dart';
+
+final dio = Dio();
+
+dio.addSentry(networkTracing: false);
+```
diff --git a/src/platforms/dart/configuration/integrations/http-integration.mdx b/src/platforms/dart/configuration/integrations/http-integration.mdx
@@ -6,12 +6,6 @@ redirect_from:
 description: "Learn more about the Sentry HTTP integration for the Dart SDK."
 ---
 
-<Note>
-
-The minimum required Dart SDK version is `2.12.0`.
-
-</Note>
-
 ## Reporting Bad HTTP Requests as Errors
 
 The `SentryHttpClient` can also catch exceptions that may occur during requests — for example [`SocketException`](https://api.dart.dev/stable/2.13.4/dart-io/SocketException-class.html).
diff --git a/src/platforms/flutter/common/performance/instrumentation/automatic-instrumentation.mdx b/src/platforms/flutter/common/performance/instrumentation/automatic-instrumentation.mdx
@@ -18,10 +18,20 @@ The `http.Client` instrumentation, once added the `SentryHttpClient` and enabled
 
 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`.
 
-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.
+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.
 
 For more information see our [SentryHttpClient integration](/platforms/dart/configuration/integrations/http-integration/#performance-monitoring-for-http-requests).
 
+### Dio HTTP Library Instrumentation
+
+The Dio instrumentation starts a span out of the active span 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 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.
+
+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).
+
 ### Routing Instumentation
 
 Automatic routing instrumentation can be enabled by adding an instance of `SentryNavigationObserver` to your application's `navigatorObservers`. Transactions are started automatically when routing to new pages in your application.
