diff --git a/docs/platforms/flutter/index.mdx b/docs/platforms/flutter/index.mdx index 6b8772ae93e5f..c28e909175f6c 100644 --- a/docs/platforms/flutter/index.mdx +++ b/docs/platforms/flutter/index.mdx @@ -46,7 +46,6 @@ dependencies: Configuration should happen as early as possible in your application's lifecycle. - ```dart {"onboardingOptions": {"performance": "8-10", "profiling": "11-14"}} import 'package:flutter/widgets.dart'; import 'package:sentry_flutter/sentry_flutter.dart'; @@ -71,6 +70,43 @@ Future main() async { } ``` +```dart {tabTitle:With custom zone} {"onboardingOptions": {"performance": "16-18", "profiling": "19-22"}} +import 'package:flutter/widgets.dart'; +import 'package:sentry_flutter/sentry_flutter.dart'; + +Future main() async { + // The SDK creates it's own custom zone on web for automatic error and breadcrumb tracking on web. + // This could lead to zone mismatch errors if you needed to call `WidgetsBinding.ensureInitialized()` before Sentry in a cusom zone. + // With `Sentry.runZonedGuarded` you still get convenient auto error and breadcrumb tracking and can also call `WidgetsBinding.ensureInitialized()` before Sentry. + Sentry.runZonedGuarded(() async { + WidgetsBinding.ensureInitialized(); + + // Errors before init will not be handled by Sentry + + await SentryFlutter.init( + (options) { + options.dsn = '___PUBLIC_DSN___'; + // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing. + // We recommend adjusting this value in production. + options.tracesSampleRate = 1.0; + // The sampling rate for profiling is relative to tracesSampleRate + // Setting to 1.0 will profile 100% of sampled transactions: + // Note: Profiling alpha is available for iOS and macOS since SDK version 7.12.0 + options.profilesSampleRate = 1.0; + }, + appRunner: () => runApp(MyApp()), + ); + } (error, stackTrace) { + // Automatically sends errors to Sentry, no need to do any + // captureException calls on your part. + // On top of that, you can do your own custom stuff in this callback. + }); + + // you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and + // SENTRY_ENVIRONMENT via Dart environment variable (--dart-define) +} +``` + ## Verify Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes. diff --git a/platform-includes/capture-error/flutter.mdx b/platform-includes/capture-error/flutter.mdx index 401ae10e443ea..c87d2c033f046 100644 --- a/platform-includes/capture-error/flutter.mdx +++ b/platform-includes/capture-error/flutter.mdx @@ -1,4 +1,32 @@ -- Flutter-specific errors, such as using `FlutterError.onError`, are captured automatically -- The SDK already runs your init `callback` on an error handler, such as [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) on Flutter versions prior to `3.3`, or [`PlatformDispatcher.onError`](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) on Flutter versions 3.3 and higher, so that errors are automatically captured. +### FlutterError.onError + +Flutter-specific errors, such as using `FlutterError.onError`, are captured automatically. + +### PlatformDispatcher.onError / runZonedGuarded + +The SDK already runs your init `callback` on an error handler, such as [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) on Flutter versions prior to `3.3`, or [`PlatformDispatcher.onError`](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) on Flutter versions 3.3 and higher, so that errors are automatically captured. + +If you need a custom error handling zone which also provides automatic error reporting and breadcrumb tracking, use `Sentry.runZonedGuarded`. It wraps Dart's native [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) function with Sentry-specific functionality. + +This function automatically records calls to `print()` as `Breadcrumbs` and can be configured using `SentryOptions.enablePrintBreadcrumbs`. + +```dart +Sentry.runZonedGuarded(() async { + WidgetsBinding.ensureInitialized(); + + // Errors before init will not be handled by Sentry + + await SentryFlutter.init( + (options) { + ... + }, + appRunner: () => runApp(MyApp()), + ); +} (error, stackTrace) { + // Automatically sends errors to Sentry, no need to do any + // captureException calls on your part. + // On top of that, you can do your own custom stuff in this callback. +}); +```