integrating-sentry

Sentry Flutter Integration Guide (sentry_flutter)

Goal

Implement a robust observability and performance monitoring layer using Sentry's official Flutter SDK. This skill ensures comprehensive error tracking across the UI and Network layers, alongside performance tracking (Tracing) for application navigation and HTTP requests, without exhausting Sentry data quotas or exposing PII.

Instructions

1. Core Initialization (sentry_flutter)

You must initialize Sentry as early as possible in your application's lifecycle, wrapping runApp with SentryWidget to capture AssetBundle transaction times and basic UI interactions natively.

import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await SentryFlutter.init(
    (options) {
      options.dsn = '___PUBLIC_DSN___'; // Inject via --dart-define or .env
      
      // Controls the percentage of Tracing (Performance) transactions sent.
      // 1.0 = 100%. (Reduce in production to avoid quota exhaustion!)
      options.tracesSampleRate = 0.2; 
      
      // Profiles provide deep CPU-level insights. Tied to TracesSampleRate.
      options.profilesSampleRate = 1.0; 

      // Replay sessions to visually debug errors.
      options.replay.onErrorSampleRate = 1.0; 
      options.replay.sessionSampleRate = 0.1;

      // Ensure PII (Personally Identifiable Information) isn't recklessly sent
      options.sendDefaultPii = false; 
    },
    appRunner: () => runApp(
      SentryWidget(
        child: const MyApp(),
      ),
    ),
  );
}

2. Routing Instrumentation (GoRouter)

Sentry can automatically track how long it takes to render a screen and trace the navigation paths of users. If you are using go_router (the standard Flutter routing solution), you must inject the SentryNavigatorObserver.

import 'package:go_router/go_router.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

final GoRouter _router = GoRouter(
  initialLocation: '/',
  // 1. Add the observer to the main router
  observers: [
    SentryNavigatorObserver(),
  ],
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/details',
      builder: (context, state) => const DetailsScreen(),
    ),
  ],
);

Note: This automatically creates Spans and Breadcrumbs every time context.go() or context.push() is invoked.