jifalops / flutter_sentry

Sentry.io error reporting plugin for Flutter, offering tight integration with Flutter and native code.

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.

Setup

1. Add flutter_sentry to your pubspec.yaml:

   dependencies:
     flutter_sentry: ^0.4.4
     # To use classes provided by sentry package (e.g. User).
     sentry: any

2. 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>).

3. Finally, wrap your runApp() call in FlutterSentry.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',
      );

Environments

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,
);

Release Health tracking

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" />

Why do I have to specify DSN in multiple places?

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!