Migration Guide

Migrate between versions of Sentry's SDK for Dart.

The required minimium Dart version is now 3.5.0. This change allows us to use safer APIs and better support for features such as WASM compilation.

  • LoadImagesListIntegration has been renamed to LoadNativeDebugImagesIntegration.
  • The enableTracing option has been removed. Use options.traceSampleRate or options.tracesSampler instead.
  • BeforeSendTransactionCallback now has a Hint parameter.
  • Usage of dart:html has been removed in favor of package:web. The SDK is now packaged with the package:web dependency for better interoperability with web APIs.
  • The segment field from SentryUser has been removed.

The default log level is now warning when debug = true. This can be adjusted by setting options.diagnosticLevel = SentryLevel.info in Sentry.init.

SDK data classes are now mutable which makes it easier to manipulate them. For backwards-compatibility, copyWith and clone can still be used but are officially deprecated.

Copied
// old
options.beforeSend = (event, hint) {
  event = event.copyWith(release: 'my-release')
  return event
}

// new
options.beforeSend = (event, hint) {
  event.release = 'my-release'
  return event
}

The old user feedback API has been removed and replaced by Sentry.captureFeedback.

Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically. Responses are now attached to the Hint object, which can be read in beforeSend/beforeSendTransaction callbacks via hint.response so you can manually attach the response to your event. Response bodies with a size greater than 0.15MB are not added to the hint object. Currently as of version 9.0.0, only the dio integration is supported.

API changes:

  • Sentry's Dart SDK version 7.0.0 and above requires Dart 2.17.0.
  • Sentry's sentry_file package version 7.0.0 and above requires Dart 2.19.0.
  • Methods that used to take a dynamic hint optional parameter now take Hint? hint instead.
  • The following deprecated fields have been removed from the SentryDevice class and replaced:
    • screenResolution replaced with screenHeightPixels and screenWidthPixels.
    • timezone replaced with SentryCulture#timezone.
    • language replaced with SentryCulture#locale.
    • theme replaced with SentryOperatingSystem#theme.
  • The following deprecated field has been removed from the Contexts#dart_context databag and replaced:
    • isolate replaced with SentryThread#name.
  • The following fields have been removed from the Scope class and replaced:
    • user(SentryUser? user) replaced with setUser(SentryUser? user).
    • attachements replaced with attachments.
  • Classes or methods that used to take the below optional parameters, have been moved to the SentryOptions class and replaced:
    • captureFailedRequests replaced with SentryOptions#captureFailedRequests.
    • sendDefaultPii replaced with SentryOptions#sendDefaultPii.
    • maxRequestBodySize replaced with SentryOptions#maxRequestBodySize.
    • networkTracing replaced with SentryOptions#tracesSampleRate or SentryOptions#tracesSampler.
    • recordBreadcrumbs replaced with SentryOptions#recordHttpBreadcrumbs.
  • The following SentryMeasurementUnits are now strongly typed:
    • DurationSentryMeasurementUnit
    • InformationSentryMeasurementUnit
    • FractionSentryMeasurementUnit
    • CustomSentryMeasurementUnit
    • NoneSentryMeasurementUnit

Behavior changes:

  • Sentry's Dart SDK version 7.0.0 and above supports Dart 3.0.0.
  • When an unhandled error happens and there's a running transaction, the transaction status will be set to internal_error.
  • The captureFailedRequests feature is now enabled by default.
  • The enableStructuredDataTracing feature is now enabled by default.
  • The enableUserInteractionTracing feature is now enabled by default.

  • SentryOptions#sendClientReports is now enabled by default. To disable it, use the code snippet below:
Copied
import 'package:sentry/sentry.dart';

Future<void> main() async {
  await Sentry.init((options) => options.sendClientReports = false;
}

  • The Scope.user setter was deprecated in favor of Scope.setUser, and it will be removed in a future update.

  • The Scope.attachements getter was deprecated in favor of attachments, and it will be removed in a future update.

  • The following Scope methods now return Future<void> instead of void:

    • setContexts
    • removeContexts
    • setUser
    • addBreadcrumb
    • clearBreadcrumbs
    • setExtra
    • removeExtra
    • setTag
    • removeTag

  • Starting with version 6.6.0 of sentry, Sentry's version >= v21.9.0 is required or you have to manually disable sending client reports via the sendClientReports option. This only applies to self-hosted Sentry. If you are using sentry.io, no action is needed.

  • Sentry.currentHub was removed. Please use the static methods on Sentry
  • SentryOptions.cacheDirSize was renamed to SentryOptions.maxCacheItems
  • EventProcessor was changed from a callback to an interface
  • The data type from the following options was changed from int to Duration. The old options are still present but deprecated and will be removed in a future version.
    • SentryOptions.autoSessionTrackingIntervalMillis to SentryOptions.autoSessionTrackingInterval
    • SentryOptions.anrTimeoutIntervalMillis to SentryOptions.anrTimeoutInterval
  • The beforeSend callback now accepts async code. The method signature changed from SentryEvent? Function(SentryEvent event, {dynamic hint}); to FutureOr<SentryEvent?> Function(SentryEvent event, {dynamic hint});. While this is technically a breaking change, your code probably is still valid.
  • Sentry accepts multiple exceptions and multiple threads. If you haven't set exceptions, there's no need to do anything.

  • Sentry's Dart SDK version 5.0.0 and above requires Dart 1.12.0
  • Fix: Prefix classes with Sentry
    • A couple of classes were often conflicting with user's code. As a result, this change renames the following classes:
      • App -> SentryApp
      • Browser -> SentryBrowser
      • Device -> SentryDevice
      • Gpu -> SentryGpu
      • Integration -> SentryIntegration
      • Message -> SentryMessage
      • OperatingSystem -> SentryOperatingSystem
      • Orientation -> SentryOrientation
      • Request -> SentryRequest
      • User -> SentryUser
  • Return type of Sentry.close() changed from void to Future<void> and Integration.close() changed from void to FutureOr<void>
Previous
SDK Overhead
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").