Dio Integration

The sentry_dio library provides Dio support for Sentry using the HttpClientAdapter. It is able to collect breadcrumbs, run performance monitoring for HTTP requests, and capture events for failed requests.

Install

To add the Dio integration, add the sentry_dio dependency.

pubspec.yaml
Copied
dependencies:
  sentry: ^7.16.1
  sentry_dio: ^7.16.1
  dio: ^4.0.0

Configure

Configuration should happen as early as possible in your application's lifecycle.

Copied
import 'package:sentry_dio/sentry_dio.dart';
import 'package:sentry/sentry.dart';

Future<void> main() async {
  await Sentry.init(
    (options) {
      options.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0';
    },
    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.

Copied
import 'package:sentry_dio/sentry_dio.dart';

final dio = Dio();

dio.addSentry();

final response = await dio.get<String>('https://wrong-url.dev/');

This is an opt-out feature. The following example shows how to disable it:

Copied
import 'package:sentry/sentry.dart';

Future<void> main() async {
  await Sentry.init(
    (options) {
      options.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0';
      options.captureFailedRequests = false;
    },
    appRunner: initApp, // Init your App.
  );
}

Performance Monitoring for HTTP Requests

The Dio integration also provides insight into performance monitoring for your HTTP requests done with Dio.

Instrumentation Behaviour

  • The created spans will be attached to the transaction on the scope - if no transaction is on the scope the span will not be sent to Sentry.
  • 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.

Prerequisites

Before starting, ensure:

  1. The Sentry Flutter SDK is initialized. Learn more here.
  2. Performance Monitoring is set up. Learn more here.

Configure

Call addSentry() on your instance of `Dio:

Copied
import 'package:sentry_dio/sentry_dio.dart';

final dio = Dio();

dio.addSentry();

Verify

1. Execute the Code

Copied
import 'package:sentry_dio/sentry_dio.dart';

Future<void> makeWebRequestWithDio() async {
  final dio = Dio();
  dio.addSentry();

  // If there is no active transaction, start one
  final transaction = Sentry.startTransaction(
    'dio-web-request',
    'request',
    bindToScope: true,
  );
  final span = transaction.startChild(
    'dio',
    description: 'desc',
  );
  Response<String>? response;
  try {
    response = await dio.get<String>(exampleUrl);
      span.status = const SpanStatus.ok();
    } catch (exception, stackTrace) {
      span.throwable = exception;
      span.status = const SpanStatus.internalError();
      await Sentry.captureException(exception, stackTrace: stackTrace);
    } finally {
      await span.finish();
    }
}

2. View the Transaction on Sentry.io

To view the recorded transaction, log into 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 dio-web-request.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").