NOTE: While sentry
package provides a
low-level functionality to report exceptions from Dart/Flutter code,
flutter_sentry
plugin (which also uses sentry
package behind the scenes!)
aims at full integration with Flutter ecosystem, automatically including Flutter
application details in reports and catching crashes in native code, including
other Flutter plugins and Flutter itself.
-
Add
flutter_sentry
to yourpubspec.yaml
:dependencies: flutter_sentry: ^0.4.4 # To use classes provided by sentry package (e.g. User). sentry: any
-
Find out a DSN value from Sentry.io and add it to native platforms:
NOTE: if you forget to add DSN to the platform code, or do it incorrectly, the application will encounter a fatal crash on startup on that platform.
-
iOS: in
ios/Runner/Info.plist
:<dict> ... existing configuration parameters ... <key>SentryDSN</key> <string>value you got from sentry.io</string> </dict>
-
Android: in
android/app/src/main/AndroidManifest.xml
:<application> <meta-data android:name="io.sentry.dsn" android:value="value you got from sentry.io" />
You can also enable debug logging for Sentry Android library if it's not working as intended:
<meta-data android:name="io.sentry.debug" android:value="true" />
NOTE: make sure to add
<meta-data>
tag directly under<application>
(and not for example<activity>
).
-
-
Finally, wrap your
runApp()
call inFlutterSentry.wrap()
like this:import 'package:flutter_sentry/flutter_sentry.dart'; Future<void> main() => FlutterSentry.wrap( () async { // Optionally other initializers, like Firebase. runApp(App()); }, dsn: 'value you got from sentry.io', );
It is sensible to have error reporting configured for debug builds similar to production. This makes sure that error reporting works as expected in all environments, and provides consistency.
You may be even sharing the same DSN (pointer to Sentry project) between debug and production environments. If you don't have to worry about Sentry quotas, this is probably a reasonable decision for smaller projects.
However, you still don't want to be alerted about each and every error that
occurs during debugging. FlutterSentry.wrap
helps avoiding this by setting
environment
attribute of error reports according to the environment your
Flutter application is running in: release
, debug
or profile
. In your
Sentry project's "Alerts" section you can configure to only get notified about
release
issues.
One exception may be Flutter Driver tests running on CI environment. Pre-release tests are often one of the last lines of defense before releasing an application to production. Background failures in such tests may be uncaught (because tests are often focused on a specific flow) but should still alert you.
For such exceptions, flutter_sentry
allows overriding autodetected environment
by running driver with sentry.environment
override:
$ flutter drive --dart-define=sentry.environment=ci ...
For a higher degree of control, you can turn reporting on or off through the
enable
parameter. Passing enable: false
will avoid passing errors to the
Sentry library, but errors are still logged to the console.
FlutterSentry.wrap(
() async {
runApp(App());
},
enable: !kDebugMode,
);
One of the most recent additions to Sentry.io was Release Health tracking. Learn more how to set it up for Android and iOS. This feature does not yet have any Flutter specific integrations.
NOTE: Session tracking is disabled by default and the timeout for a session defaults to 30000 milliseconds (30 seconds).
-
iOS: in
ios/Runner/Info.plist
:<dict> ... existing configuration parameters ... <key>SentryEnableAutoSessionTracking</key> <true/> <key>SentrySessionTrackingIntervalMillis</key> <integer>60000</integer> </dict>
-
Android: in
android/app/src/main/AndroidManifest.xml
:<application> <meta-data android:name="io.sentry.session-tracking.enable" android:value="true"/> <meta-data android:name="io.sentry.session-tracking.timeout-interval-millis" android:value="60000" />
You might be wondering why a DSN value can't be specified in a single place and then exchanged between platforms and Dart/Flutter code via a MethodChannel. The reason for that is, native code and Flutter initialize in parallel, before MethodChannel is available, and if a crash happens before MethodChannel is ready... that part of application is on its own.
That said, we want to minimize the installation burden. While the plugin is still in development, we may eventually introduce a way to configure the value once and have it copied to all platforms at build time. Stay tuned!