From 3e2a94b4372e005366fdf9e7c3afd9bdfc2760e2 Mon Sep 17 00:00:00 2001 From: Denis Andrasec Date: Mon, 2 Dec 2024 15:40:03 +0100 Subject: [PATCH 1/5] docs(flutter): Document `Sentry.runZonedGuarded` --- platform-includes/capture-error/flutter.mdx | 32 +++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/platform-includes/capture-error/flutter.mdx b/platform-includes/capture-error/flutter.mdx index 401ae10e443ea..bc5494901b7ea 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(() { + WidgetsBinding.ensureInitialized(); + + // Errors before init will not be handled by Sentry + + 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. +}); +``` From 86391152362afb7e5d61d9f615be7049cd2ae960 Mon Sep 17 00:00:00 2001 From: Denis Andrasec Date: Mon, 9 Dec 2024 11:23:42 +0100 Subject: [PATCH 2/5] add FlutterWeb with WidgetsBindingIntegration sample tab --- docs/platforms/flutter/index.mdx | 35 +++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/platforms/flutter/index.mdx b/docs/platforms/flutter/index.mdx index 6b8772ae93e5f..0c0aa94b81968 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,40 @@ Future main() async { } ``` +```dart {tabTitle:FlutterWeb with WidgetsBindingIntegration} {"onboardingOptions": {"performance": "13-15", "profiling": "16-19"}} +import 'package:flutter/widgets.dart'; +import 'package:sentry_flutter/sentry_flutter.dart'; + +Future main() async { + 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. From 56c1d3ea6c798f392a19dc54d5912ed9e77756f2 Mon Sep 17 00:00:00 2001 From: Denis Andrasec Date: Mon, 9 Dec 2024 13:39:40 +0100 Subject: [PATCH 3/5] add async modifier --- platform-includes/capture-error/flutter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/capture-error/flutter.mdx b/platform-includes/capture-error/flutter.mdx index bc5494901b7ea..c87d2c033f046 100644 --- a/platform-includes/capture-error/flutter.mdx +++ b/platform-includes/capture-error/flutter.mdx @@ -13,12 +13,12 @@ If you need a custom error handling zone which also provides automatic error rep This function automatically records calls to `print()` as `Breadcrumbs` and can be configured using `SentryOptions.enablePrintBreadcrumbs`. ```dart -Sentry.runZonedGuarded(() { +Sentry.runZonedGuarded(() async { WidgetsBinding.ensureInitialized(); // Errors before init will not be handled by Sentry - SentryFlutter.init( + await SentryFlutter.init( (options) { ... }, From 64ea81bb485f998b445c8377a2c4c86a02146c22 Mon Sep 17 00:00:00 2001 From: Denis Andrasec Date: Tue, 17 Dec 2024 15:08:07 +0100 Subject: [PATCH 4/5] pr feedback --- docs/platforms/flutter/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/platforms/flutter/index.mdx b/docs/platforms/flutter/index.mdx index 0c0aa94b81968..c332c87f1d965 100644 --- a/docs/platforms/flutter/index.mdx +++ b/docs/platforms/flutter/index.mdx @@ -70,11 +70,12 @@ Future main() async { } ``` -```dart {tabTitle:FlutterWeb with WidgetsBindingIntegration} {"onboardingOptions": {"performance": "13-15", "profiling": "16-19"}} +```dart {tabTitle:Flutter Web} {"onboardingOptions": {"performance": "13-15", "profiling": "16-19"}} import 'package:flutter/widgets.dart'; import 'package:sentry_flutter/sentry_flutter.dart'; Future main() async { + // By using Sentry.runZonedGuarded you can have a custom Zone, where you can call `WidgetsBinding` before `SentryFlutter.init`, with automatic error and breadcrumb reporting. Sentry.runZonedGuarded(() async { WidgetsBinding.ensureInitialized(); From bf104652f45092d3841f6462e7474619de2f32d3 Mon Sep 17 00:00:00 2001 From: Denis Andrasec Date: Tue, 17 Dec 2024 15:19:34 +0100 Subject: [PATCH 5/5] Update docs --- docs/platforms/flutter/index.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/platforms/flutter/index.mdx b/docs/platforms/flutter/index.mdx index c332c87f1d965..c28e909175f6c 100644 --- a/docs/platforms/flutter/index.mdx +++ b/docs/platforms/flutter/index.mdx @@ -70,12 +70,14 @@ Future main() async { } ``` -```dart {tabTitle:Flutter Web} {"onboardingOptions": {"performance": "13-15", "profiling": "16-19"}} +```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 { - // By using Sentry.runZonedGuarded you can have a custom Zone, where you can call `WidgetsBinding` before `SentryFlutter.init`, with automatic error and breadcrumb reporting. + // 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();