HTTP Integration

Learn more about the Sentry HTTP integration for the Dart SDK.

You can use the SentryHttpClient and call its methods directly, or you can use it with the runWithClient function. If you need to use a fresh instance of the client (so that other instances are not affected) or to run in a separate Zone, which allows you to override the functionality of the existing Zone, then use the runWithClient function (see the runWithClient tab). Otherwise, just use SentryHttpClient directly and call its methods (see the default tab).

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

final client = SentryHttpClient();

try {
  final response = await client.get(Uri.https('www.example.com', ''));
  print(response.body);
} finally {
  client.close();
}

The SentryHttpClient can also catch exceptions that may occur during requests — for example SocketException.

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

var client = SentryHttpClient();
try {
  var uriResponse = await client.post('https://example.com/whatsit/create',
    body: {'name': 'doodle', 'color': 'blue'});
  print(await client.get(uriResponse.bodyFields['uri']));
} finally {
  client.close();
}

When an error occurs, the following information is captured and sent to Sentry:

The marked elements (*) are affected by the default enabled server-side data scrubbing. To implement client side data scrubbing, go to client-side data scrubbing in Flutter.

Request details:

  • Method
  • URL *
  • Headers *
  • Body *
  • Content length
  • Duration

Response details:

  • Headers *
  • Content length
  • Status code

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 = '___PUBLIC_DSN___';
      options.captureFailedRequests = false;
    },
    appRunner: initApp, // Init your App.
  );
}

Furthermore you can track HTTP requests that you consider bad. In the following example, exceptions are captured for each request with a status code within the range of 400 to 404, and also for 500.

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

var client = SentryHttpClient(
  failedRequestStatusCodes: [
    SentryStatusCode.range(400, 404),
    SentryStatusCode(500),
  ],
);

try {
  var uriResponse = await client.post('https://example.com/whatsit/create',
    body: {'name': 'doodle', 'color': 'blue'});
  print(await client.get(uriResponse.bodyFields['uri']));
} finally {
  client.close();
}

You can customize which status codes should be considered failed requests by setting the failedRequestStatusCodes option when calling SentryHttpClient().

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

var client = SentryHttpClient(
  failedRequestStatusCodes: [
    SentryStatusCode.range(400, 404), // Capture 400-404
    SentryStatusCode(500),             // Capture 500
  ],
);

try {
  var uriResponse = await client.post('https://example.com/whatsit/create',
    body: {'name': 'doodle', 'color': 'blue'});
  print(await client.get(uriResponse.bodyFields['uri']));
} finally {
  client.close();
}

Default Behavior:

By default, failedRequestStatusCodes is set to [SentryStatusCode.range(500, 599)], which captures server errors (status codes 500-599).

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:

  • Strings that appear anywhere in the URL
  • Regular expression patterns
Copied
import 'package:sentry/sentry.dart';

// Capture failed requests only from specific domains
var client = SentryHttpClient(
  failedRequestTargets: [
    'api.example.com',      // Matches any URL containing this string
    'myapi.com',            // Another domain to track
  ],
);

try {
  var uriResponse = await client.post('https://api.example.com/whatsit/create',
    body: {'name': 'doodle', 'color': 'blue'});
  print(await client.get(uriResponse.bodyFields['uri']));
} finally {
  client.close();
}

Default Behavior:

By default, failedRequestTargets is set to ['.*'], which matches all URLs. This means all failed requests are captured (subject to failedRequestStatusCodes).

The SentryHttpClient starts a span out of the active span bound to the scope for each HTTP Request.

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

final transaction = Sentry.startTransaction(
  'webrequest',
  'request',
  bindToScope: true,
);

var client = SentryHttpClient();
try {
  var uriResponse = await client.post('https://example.com/whatsit/create',
    body: {'name': 'doodle', 'color': 'blue'});
  print(await client.get(uriResponse.bodyFields['uri']));
} finally {
  client.close();
}

await transaction.finish(status: SpanStatus.ok());
Previous
File I/O
Next
Logging Integration
Was this helpful?
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").