sentry-flutter-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Flutter SDK # Sentry Flutter SDK Opinionated wizard that scans your Flutter or Dart project and guides you through complete Sentry setup — error monitoring, tracing, session replay, logging, profiling, and ecosystem integrations. ## Invoke This Skill When - User asks to "add Sentry to Flutter" or "set up Sentry" in a Flutter or Dart app - User wants error monitoring, tracing, profiling, session replay, or logging in Flutter - User mentions `sentry_flutter`, `sentry_dart`, mobile error tracking, or Sentry for Flutter - User wants to monitor native crashes, ANRs, or app hangs on iOS/Android > **Note:** SDK versions and APIs below reflect `sentry_flutter` ≥9.14.0 (current stable, February 2026). > Always verify against [docs.sentry.io/platforms/flutter/](https://docs.sentry.io/platforms/flutter/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # Detect Flutter project type and existing Sentry cat pubspec.yaml | grep -E '(sentry|flutter|dart)' # Check SDK version cat pubspec.yaml | grep -A2 'environment:' # Check for existing Sentry initialization grep -r "SentryFlutter.init\|Sentry.init" lib/ 2>/dev/null | head -5 # Detect navigation library grep -E '(go_router|auto_route|get:|beamer|routemaster)' pubspec.yaml # Detect HTTP client grep -E '(dio:|http:|chopper:)' pubspec.yaml # Detect database packages grep -E '(sqflite|drift|hive|isar|floor)' pubspec.yaml # Detect state management (for integration patterns) grep -E '(flutter_bloc|riverpod|provider:|get:)' pubspec.yaml # Detect GraphQL grep -E '(graphql|ferry|gql)' pubspec.yaml # Detect Firebase grep -E '(firebase_core|supabase)' pubspec.yaml # Detect backend for cross-link ls ../backend/ ../server/ ../api/ 2>/dev/null find .. -maxdepth 3 \( -name "go.mod" -o -name "requirements.txt" -o -name "Gemfile" -o -name "*.csproj" \) 2>/dev/null | grep -v flutter | head -10 # Detect platform targets ls android/ ios/ macos/ linux/ windows/ web/ 2>/dev/null ``` **What to determine:** | Question | Impact | |----------|--------| | `sentry_flutter` already in `pubspec.yaml`? | Skip install, jump to feature config | | Dart SDK `>=3.5`? | Required for `sentry_flutter` ≥9.0.0 | | `go_router` or `auto_route` present? | Use `SentryNavigatorObserver` — specific patterns apply | | `dio` present? | Recommend `sentry_dio` integration | | `sqflite`, `drift`, `hive`, `isar` present? | Recommend matching `sentry_*` DB package | | Has `android/` and `ios/` directories? | Full mobile feature set available | | Has `web/` directory only? | Session Replay and Profiling unavailable | | Has `macos/` directory? | Profiling available (alpha) | | Backend directory detected? | Trigger Phase 4 cross-link | --- ## Phase 2: Recommend Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal: **Recommended (core coverage — always set up these):** - ✅ **Error Monitoring** — captures Dart exceptions, Flutter framework errors, and native crashes (iOS + Android) - ✅ **Tracing** — auto-instruments navigation, app start, network requests, and UI interactions - ✅ **Session Replay** — captures widget tree screenshots for debugging (iOS + Android only) **Optional (enhanced observability):** - ⚡ **Profiling** — CPU profiling; iOS and macOS only (alpha) - ⚡ **Logging** — structured logs via `Sentry.logger.*` and `sentry_logging` integration - ⚡ **Metrics** — counters, gauges, distributions (SDK ≥9.11.0) **Platform limitations — be upfront:** | Feature | Platforms | Notes | |---------|-----------|-------| | Session Replay | iOS, Android | Not available on macOS, Linux, Windows, Web | | Profiling | iOS, macOS | Alpha status; not available on Android, Linux, Windows, Web | | Native crashes | iOS, Android, macOS | NDK/signal handling; Linux/Windows/Web: Dart exceptions only | | App Start metrics | iOS, Android | Not available on desktop/web | | Slow/frozen frames | iOS, Android, macOS | Not available on Linux, Windows, Web | | Crons | N/A | **Not available** in the Flutter/Dart SDK | Propose: *"For your Flutter app targeting iOS/Android, I recommend Error Monitoring + Tracing + Session Replay. Want me to also add Logging and Profiling (iOS/macOS alpha)?"* --- ## Phase 3: Guide ### Determine Your Setup Path | Project type | Recommended setup | |-------------|------------------| | Any Flutter app | Wizard CLI (handles pubspec, init, symbol upload) | | Manual preferred | Path B below — `pubspec.yaml` + `main.dart` | | Dart-only (CLI, server) | Path C below — pure `sentry` package | --- ### Path A: Wizard CLI (Recommended) > **You need to run this yourself** — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal: > > ```bash > brew install getsentry/tools/sentry-wizard && sentry-wizard -i flutter > ``` > > It handles org/project selection, adds `sentry_flutter` to `pubspec.yaml`, updates `main.dart`, configures `sentry_dart_plugin` for debug symbol upload, and adds build scripts. Here's what it creates/modifies: > > | File | Action | Purpose | > |------|--------|---------| > | `pubspec.yaml` | Adds `sentry_flutter` dependency and `sentry:` config block | SDK + symbol upload config | > | `lib/main.dart` | Wraps `main()` with `SentryFlutter.init()` | SDK initialization | > | `android/app/build.gradle` | Adds Proguard config reference | Android obfuscation support | > | `.sentryclirc` | Auth token and org/project config | Symbol upload credentials | > > **Once it finishes, come back and skip to [Verification](#verification).** If the user skips the wizard, proceed with Path B (Manual Setup) below. --- ### Path B: Manual — Flutter App **Step 1 — Install** ```bash flutter pub add sentry_flutter ``` Or add to `pubspec.yaml` manually: ```yaml dependencies: flutter: sdk: flutter sentry_flutter: ^9.14.0 ``` Then run: ```bash flutter pub get ``` **Step 2 — Initialize Sentry in `lib/main.dart`** ```dart import 'package:flutter/widgets.dart'; import 'package:sentry_flutter/sentry_flutter.dart'; Future<void> main() async { await SentryFlutter.init( (options) { options.dsn = 'YOUR_SENTRY_DSN'; options.sendDefaultPii = true; // Tracing options.tracesSampleRate = 1.0; // lower to 0.1–0.2 in production // Profiling (iOS and macOS only — alpha) options.profilesSampleRate = 1.0; // Session Replay (iOS and Android only) options.replay.sessionSampleRate = 0.1; options.replay.onErrorSampleRate = 1.0; // Structured Logging (SDK ≥9.5.0) options.enableLogs = true; options.environment = const bool.fromEnvironment('dart.vm.product') ? 'production' : 'development'; }, // REQUIRED: wrap root widget to enable screenshots, replay, user interaction tracing appRunner: () => runApp(SentryWidget(child: MyApp())), ); } ``` **Step 3 — Add Navigation Observer** Add `SentryNavigatorObserver` to your `MaterialApp` or `CupertinoApp`: ```dart import 'package:flutter/material.dart'; import 'package:sentry_flutter/sentry_flutter.dart'; class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( navigatorObservers: [ SentryNavigatorObserver(), ], // Always name your routes for Sentry to track them routes: { '/': (context) => HomeScreen(), '/profile': (context) => ProfileScreen(), }, ); } } ``` For **GoRouter**: ```dart import 'package:go_router/go_router.dart'; import 'package:sentry_flutter/sentry_flutter.dart'; final GoRouter router = GoRouter( observers: [SentryNavigatorObserver()], routes: [ GoRoute( path: '/', name: 'home', // name is REQUIRED for Sentry route tracking builder: (context, state) => const HomeScreen(), routes: [ GoRoute( path: 'profile/:id', name: 'profile', // name is REQUIRED builder: (context, state) => ProfileScreen( id: state.pathParameters['id']!, ), ), ], ), ], ); ``` **Step 4 — Configure Debug Symbol Upload** Readable stack traces in Sentry require uploading debug symbols when building with `--obfuscate`. Add to `pubspec.yaml`: ```yaml dev_dependencies: sentry_dart_plugin: ^3.2.1 sentry: project: YOUR_PROJECT_SLUG org: YOUR_ORG_SLUG auth_token: YOUR_AUTH_TOKEN # prefer SENTRY_AUTH_TOKEN env var instead upload_debug_symbols: true upload_sources: true upload_source_maps: true # for Web ``` Build and upload: ```bash # Android flutter build apk \ --release \ --obfuscate \ --split-debug-info=build/debug-info \ --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json dart run sentry_dart_plugin # iOS flutter build ipa \ --release \ --obfuscate \ --split-debug-info=build/debug-info \ --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json dart run sentry_dart_plugin # Web flutter build web --release --source-maps dart run sentry_dart_plugin ``` --- ### Path C: Manual — Dart-Only (CLI / Server) ```yaml # pubspec.yaml dependencies: sentry: ^9.14.0 ``` ```dart import 'package:sentry/sentry.dart'; Future<void> main() async { await Sentry.init( (options) { options.dsn = 'YOUR_SENTRY_DSN'; options.tracesSampleRate = 1.0; options.enableLogs = true; }, appRunner: myApp, ); } ``` --- ### Quick Reference: Full-Featured `SentryFlutter.init()` ```dart import 'package:sentry_flutter/sentry_flutter.dart'; Future<void> main() async { await SentryFlutter.init( (options) { options.dsn = 'YOUR_SENTRY_DSN'; options.sendDefaultPii = true; // Environment — detect release builds via dart.vm.product options.environment = const bool.fromEnvironment('dart.vm.product') ? 'production' : 'development'; // Release is auto-set on iOS/Android as "packageName@version+build" // Override if needed: // options.release = 'my-app@1.0.0+42'; // Error sampling — reduce to drop a fraction of errors in high-volume production options.sampleRate = 1.0; // Tracing — lower to 0.1–0.2 in high-traffic production options.tracesSampleRate = 1.0; // Profiling — iOS and macOS only (alpha); relative to tracesSampleRate options.profilesSampleRate = 1.0; // Session Replay — iOS and Android only (SDK ≥9.0.0) options.replay.sessionSampleRate = 0.1; // record 10% of all sessions options.replay.onErrorSampleRate = 1.0; // always record error sessions // Privacy defaults — all text and images masked options.privacy.maskAllText = true; options.privacy.maskAllImages = true; // Structured logging (SDK ≥9.5.0) options.enableLogs = true; // Attachments options.attachScreenshot = true; // screenshot on error options.attachViewHierarchy = true; // widget tree on error // HTTP client options.captureFailedRequests = true; // auto-capture HTTP errors options.maxRequestBodySize = MaxRequestBodySize.small; // Android specifics options.anrEnabled = true; // ANR detection options.enableNdkScopeSync = true; // sync scope to native options.enableTombstone = false; // Android 12+ tombstone (opt-in) // Navigation (Time to Full Display — opt-in) options.enableTimeToFullDisplayTracing = true; }, appRunner: () => runApp(SentryWidget(child: MyApp())), ); } ``` --- ### Navigation: Time to Full Display (TTFD) TTID (Time to Initial Display) is always enabled. TTFD is opt-in: ```dart // Enable in options: options.enableTimeToFullDisplayTracing = true;