sentry-flutter-sdk

すべてのスキル > SDK セットアップ > Flutter SDK

Sentry Flutter SDK

Flutter または Dart プロジェクトをスキャンし、エラー監視、トレーシング、セッションリプレイ、ロギング、プロファイリング、エコシステムとの統合を含む Sentry の完全なセットアップを案内する、独自のウィザードです。

このスキルを使うタイミング

• ユーザーが Flutter または Dart アプリに「Sentry を追加」または「Sentry をセットアップ」したいと依頼した場合
• ユーザーが Flutter でエラー監視、トレーシング、プロファイリング、セッションリプレイ、ロギングを行いたい場合
• ユーザーが sentry_flutter、sentry_dart、モバイルのエラー追跡、または Flutter 向け Sentry に言及した場合
• ユーザーが iOS/Android でネイティブクラッシュ、ANR、アプリのハングを監視したい場合

注： 以下の SDK バージョンと API は sentry_flutter ≥9.14.0（2026 年 2 月時点の最新安定版）を反映しています。 実装前に必ず docs.sentry.io/platforms/flutter/ で確認してください。

---

フェーズ 1：検出

提案を行う前に、次のコマンドを実行してプロジェクトの状況を把握します。

# 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

確認する項目：

質問	影響
pubspec.yaml に sentry_flutter がすでに含まれていますか？	インストールを省略し、機能設定に進みます
Dart SDK は >=3.5 ですか？	sentry_flutter ≥9.0.0 の要件です
go_router または auto_route が含まれていますか？	SentryNavigatorObserver を使用します。固有のパターンが適用されます
dio が含まれていますか？	sentry_dio 統合を推奨します
sqflite、drift、hive、isar が含まれていますか？	対応する sentry_* DB パッケージを推奨します
android/ と ios/ ディレクトリがありますか？	モバイル向けの機能一式を利用できます
web/ ディレクトリのみありますか？	セッションリプレイとプロファイリングは利用できません
macos/ ディレクトリがありますか？	プロファイリングを利用できます（アルファ版）
バックエンドのディレクトリが検出されましたか？	フェーズ 4 のクロスリンクを実施します

---

フェーズ 2：推奨

確認した内容に基づいて、具体的な推奨事項を提示します。自由回答式の質問はせず、まず提案を示します。

推奨（基本的なカバレッジ — 常に設定する機能）：

• ✅ エラー監視 — Dart の例外、Flutter フレームワークのエラー、ネイティブクラッシュ（iOS + Android）をキャプチャします
• ✅ トレーシング — ナビゲーション、アプリ起動、ネットワークリクエスト、UI 操作を自動計測します
• ✅ セッションリプレイ — デバッグ用にウィジェットツリーのスクリーンショットをキャプチャします（iOS + Android のみ）

オプション（可観測性の強化）：

• ⚡ プロファイリング — CPU プロファイリング。iOS と macOS のみ（アルファ版）
• ⚡ ロギング — Sentry.logger.* と sentry_logging 統合による構造化ログ
• ⚡ メトリクス — カウンター、ゲージ、分布（SDK ≥9.11.0）

プラットフォームの制限 — 明確に伝えます：

機能	プラットフォーム	備考
セッションリプレイ	iOS、Android	macOS、Linux、Windows、Web では利用できません
プロファイリング	iOS、macOS	アルファ版です。Android、Linux、Windows、Web では利用できません
ネイティブクラッシュ	iOS、Android、macOS	NDK/シグナル処理。Linux/Windows/Web では Dart の例外のみ
アプリ起動メトリクス	iOS、Android	デスクトップ/Web では利用できません
スローフレーム／フリーズフレーム	iOS、Android、macOS	Linux、Windows、Web では利用できません
Crons	該当なし	Flutter/Dart SDK では利用できません

次のように提案します。「iOS/Android を対象とする Flutter アプリには、エラー監視 + トレーシング + セッションリプレイをおすすめします。ロギングとプロファイリング（iOS/macOS のアルファ版）も追加しますか？」

---

フェーズ 3：案内

セットアップ方法を決める

プロジェクトの種類	推奨セットアップ
任意の Flutter アプリ	Wizard CLI（pubspec、初期化、シンボルのアップロードを処理します）
手動でのセットアップを希望	以下の方法 B — pubspec.yaml + main.dart
Dart のみ（CLI、サーバー）	以下の方法 C — 純粋な sentry パッケージ

---

パス A：ウィザード CLI（推奨）

この操作はご自身で実行する必要があります — ウィザードはログイン用のブラウザーを開き、エージェントでは対応できない対話形式の入力を求めます。以下をコピーしてターミナルに貼り付けてください。

brew install getsentry/tools/sentry-wizard && sentry-wizard -i flutter

組織／プロジェクトの選択、pubspec.yaml への sentry_flutter の追加、main.dart の更新、デバッグシンボルのアップロード用 sentry_dart_plugin の設定、ビルドスクリプトの追加を行います。作成／変更される内容は次のとおりです。

ファイル	操作	目的
pubspec.yaml	sentry_flutter 依存関係と sentry: 設定ブロックを追加	SDK とシンボルアップロードの設定
lib/main.dart	main() を SentryFlutter.init() でラップ	SDK の初期化
android/app/build.gradle	Proguard 設定への参照を追加	Android の難読化サポート
.sentryclirc	認証トークンと組織／プロジェクトの設定	シンボルアップロードの認証情報

完了したら、戻って検証に進んでください。

ウィザードをスキップした場合は、以下のパス B（手動セットアップ）に進みます。

---

パス B：手動 — Flutter アプリ

ステップ 1 — インストール

flutter pub add sentry_flutter

または、手動で pubspec.yaml に追加します。

dependencies:
  flutter:
    sdk: flutter
  sentry_flutter: ^9.14.0

次に、以下を実行します。

flutter pub get

ステップ 2 — lib/main.dart で Sentry を初期化する

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

ステップ 3 — ナビゲーションオブザーバーを追加する

MaterialApp または CupertinoApp に SentryNavigatorObserver を追加します。

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

GoRouter の場合：

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']!,
          ),
        ),
      ],
    ),
  ],
);

ステップ 4 — デバッグシンボルのアップロードを設定する

--obfuscate を指定してビルドする場合、Sentry で読み取り可能なスタックトレースを表示するには、デバッグシンボルのアップロードが必要です。

pubspec.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

ビルドしてアップロードします。

# 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

---

パス C：手動 — Dart のみ（CLI／サーバー）

# pubspec.yaml
dependencies:
  sentry: ^9.14.0

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

---

クイックリファレンス：機能をすべて有効にする SentryFlutter.init()

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 = '[email protected]+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())),
  );
}

---

ナビゲーション：完全な画面表示までの時間（TTFD）

TTID（初回画面表示までの時間）は常に有効です。TTFD はオプトインです。

// Enable in options:
options.enableTimeToFullDisplayTracing = true;

次に、画面のデータ読み込みが完了した時点で報告します。

// Option 1: Widget wrapper (marks TTFD when child first renders)
SentryDisplayWidget(child: MyWidget())

// Option 2: Manual API call (after async data loads)
await _loadData();
SentryFlutter.currentDisplay()?.reportFullyDisplayed();

---

合意した各機能について

機能を 1 つずつ確認します。各機能のリファレンスファイルを読み込み、手順に従ってから、次に進む前に検証してください。

機能	リファレンス	読み込むタイミング
エラー監視	${SKILL_ROOT}/references/error-monitoring.md	常に（基本設定）
トレーシングとパフォーマンス	${SKILL_ROOT}/references/tracing.md	常に — ナビゲーション、HTTP、DB スパン
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	iOS／Android のユーザー向けアプリ
プロファイリング	${SKILL_ROOT}/references/profiling.md	パフォーマンスが重要な iOS／macOS アプリ
ロギング	${SKILL_ROOT}/references/logging.md	構造化ロギング／ログとトレースの相関
メトリクス	${SKILL_ROOT}/references/metrics.md	カスタムビジネスメトリクス
エコシステム連携	${SKILL_ROOT}/references/ecosystem-integrations.md	HTTP クライアント、データベース、GraphQL、状態管理

各機能について、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を検証してください。

---

設定リファレンス

コア SentryFlutter.init() オプション

オプション	型	デフォルト	目的
dsn	string	—	必須。 プロジェクトの DSN。環境変数：--dart-define 経由の SENTRY_DSN
environment	string	—	例：「production」、「staging」。環境変数：SENTRY_ENVIRONMENT
release	string	iOS/Android では自動	「packageName@version+build」。環境変数：SENTRY_RELEASE
dist	string	—	配布識別子。最大 64 文字。環境変数：SENTRY_DIST
sendDefaultPii	bool	false	PII（IP アドレス、ユーザーラベル、リプレイ内のウィジェットテキスト）を含めます
sampleRate	double	1.0	エラーイベントのサンプリング率（0.0～1.0）
maxBreadcrumbs	int	100	イベントごとのパンくずリストの最大数
attachStacktrace	bool	true	メッセージにスタックトレースを自動的に添付します
attachScreenshot	bool	false	エラー発生時にスクリーンショットを撮影します（モバイル／デスクトップのみ）
screenshotQuality	enum	high	スクリーンショットの画質：full、high、medium、low
attachViewHierarchy	bool	false	エラー発生時に JSON ウィジェットツリーを添付ファイルとして添付します
debug	bool	デバッグ時は true	SDK の詳細な出力。本番環境では true に設定しないでください
diagnosticLevel	enum	warning	ログの詳細度：debug、info、warning、error、fatal
enabled	bool	true	SDK を完全に無効にします（テスト時など）
maxCacheItems	int	30	オフラインでキャッシュするエンベロープの最大数（Web では未対応）
sendClientReports	bool	true	SDK のヘルスレポート（破棄されたイベントなど）を送信します
reportPackages	bool	true	pubspec.yaml の依存関係リストを報告します
reportSilentFlutterErrors	bool	false	FlutterErrorDetails.silent エラーを取得します
idleTimeout	Duration	3000ms	アイドル状態のユーザーインタラクションのトランザクションを自動的に終了します

トレーシングオプション

オプション	型	デフォルト	目的
tracesSampleRate	double	—	トランザクションのサンプリング率（0～1）。0 より大きい値を設定すると有効になります
tracesSampler	function	—	トランザクションごとのサンプリング。tracesSampleRate を上書きします
tracePropagationTargets	List	—	sentry-trace と baggage ヘッダーを付与する URL
propagateTraceparent	bool	false	W3C traceparent ヘッダーも送信します（SDK ≥9.7.0）
enableTimeToFullDisplayTracing	bool	false	画面ごとの TTFD 計測をオプトインで有効にします
enableAutoPerformanceTracing	bool	true	パフォーマンスモニタリングを自動的に有効にします
enableUserInteractionTracing	bool	true	タップ／クリック／長押しイベントのトランザクションを作成します
enableUserInteractionBreadcrumbs	bool	true	計測対象のユーザーインタラクションごとにパンくずリストを記録します

プロファイリングオプション

オプション	型	デフォルト	目的
profilesSampleRate	double	—	tracesSampleRate に対するプロファイリング率。iOS/macOS のみ

ネイティブ／モバイルのオプション

オプション	型	デフォルト	目的
autoInitializeNativeSdk	bool	true	ネイティブ Android／iOS SDK レイヤーを自動初期化します
enableNativeCrashHandling	bool	true	ネイティブクラッシュを捕捉します（NDK、シグナル、Mach 例外）
enableNdkScopeSync	bool	true	Dart スコープを Android NDK に同期します
enableScopeSync	bool	true	スコープデータをネイティブ SDK に同期します
anrEnabled	bool	true	ANR 検出（Android）
anrTimeoutInterval	int	5000	ANR のタイムアウト（ミリ秒、Android）
enableWatchdogTerminationTracking	bool	true	OOM キルの追跡（iOS）
enableTombstone	bool	false	ApplicationExitInfo による Android 12 以降のネイティブクラッシュ情報
attachThreads	bool	false	クラッシュ時にすべてのスレッドを添付します（Android）
captureNativeFailedRequests	bool	—	Dart クライアントとは独立したネイティブ HTTP エラーの捕捉（iOS/macOS、v9.11.0 以降）
enableAutoNativeAppStart	bool	true	アプリ起動時間の計測（iOS/Android）
enableFramesTracking	bool	true	遅延／フリーズしたフレームの監視（iOS/Android/macOS）
proguardUuid	string	—	Android の難読化マッピング用 Proguard UUID

セッションとリリースヘルスのオプション

オプション	型	デフォルト	目的
enableAutoSessionTracking	bool	true	クラッシュのないユーザー／セッションのメトリクス用にセッションを追跡します
autoSessionTrackingInterval	Duration	30s	セッション終了までのバックグラウンド非アクティブ時間

リプレイのオプション（options.replay）

オプション	型	デフォルト	目的
replay.sessionSampleRate	double	0.0	記録される全セッションの割合
replay.onErrorSampleRate	double	0.0	記録されるエラーセッションの割合

リプレイのプライバシーオプション（options.privacy）

オプション／メソッド	デフォルト	目的
privacy.maskAllText	true	すべてのテキストウィジェットの内容をマスクします
privacy.maskAllImages	true	すべての画像ウィジェットをマスクします
privacy.maskAssetImages	true	ルートアセットバンドル内の画像をマスクします
privacy.mask<T>()	—	特定のウィジェット型とそのすべてのサブクラスをマスクします
privacy.unmask<T>()	—	特定のウィジェット型のマスクを解除します
privacy.maskCallback<T>()	—	ウィジェットインスタンスごとにマスク方法をカスタマイズします

HTTP オプション

オプション	型	デフォルト	目的
captureFailedRequests	bool	true（Flutter）	HTTP エラーを自動的に捕捉します
maxRequestBodySize	enum	never	リクエストボディの捕捉：never、small、medium、always
failedRequestStatusCodes	List	[500–599]	失敗として扱うステータスコード
failedRequestTargets	List	['.*']	監視する URL パターン

フックのオプション

オプション	型	目的
beforeSend	(SentryEvent, Hint) → SentryEvent?	エラーイベントを変更または破棄します。破棄するには null を返します
beforeSendTransaction	(SentryEvent) → SentryEvent?	トランザクションイベントを変更または破棄します
beforeBreadcrumb	(Breadcrumb, Hint) → Breadcrumb?	保存前にパンくずを処理します
beforeSendLog	(SentryLog) → SentryLog?	送信前に構造化ログをフィルタリングします

環境変数

ビルド時に --dart-define で渡します。

変数	目的	備考
SENTRY_DSN	データソース名	options.dsn からフォールバックします
SENTRY_ENVIRONMENT	デプロイ環境	options.environment からフォールバックします
SENTRY_RELEASE	リリース識別子	options.release からフォールバックします
SENTRY_DIST	ビルド配布先	options.dist からフォールバックします
SENTRY_AUTH_TOKEN	デバッグシンボルのアップロード	アプリに埋め込まないでください。ビルドツール専用です
SENTRY_ORG	組織のスラッグ	sentry_dart_plugin で使用されます
SENTRY_PROJECT	プロジェクトのスラッグ	sentry_dart_plugin で使用されます

使用方法：

flutter build apk --release \
  --dart-define=SENTRY_DSN=https://[email protected]/123 \
  --dart-define=SENTRY_ENVIRONMENT=production

次に、コード内で設定します。

options.dsn = const String.fromEnvironment('SENTRY_DSN');
options.environment = const String.fromEnvironment('SENTRY_ENVIRONMENT', defaultValue: 'development');

本番環境の設定

リリース前にサンプルレートを下げ、設定を強化します。

Future<void> main() async {
  final isProduction = const bool.fromEnvironment('dart.vm.product');

  await SentryFlutter.init(
    (options) {
      options.dsn = const String.fromEnvironment('SENTRY_DSN');
      options.environment = isProduction ? 'production' : 'development';

      // Trace 10% of transactions in high-traffic production
      options.tracesSampleRate = isProduction ? 0.1 : 1.0;

      // Profile 100% of traced transactions (profiling is always a subset)
      options.profilesSampleRate = 1.0;

      // Replay all error sessions, sample 5% of normal sessions
      options.replay.onErrorSampleRate = 1.0;
      options.replay.sessionSampleRate = isProduction ? 0.05 : 1.0;

      // Disable debug logging in production
      options.debug = !isProduction;
    },
    appRunner: () => runApp(SentryWidget(child: MyApp())),
  );
}

デフォルトで自動有効化されるインテグレーション

SentryFlutter.init() を呼び出すと、追加の設定なしで以下が有効になります。

インテグレーション	機能
FlutterErrorIntegration	FlutterError.onError のフレームワークエラーをキャプチャします
RunZonedGuardedIntegration	runZonedGuarded 内の未処理の Dart 例外を捕捉します
NativeAppStartIntegration	アプリの起動時間を計測します（iOS／Android）
FramesTrackingIntegration	遅いフレームやフリーズしたフレームを計測します（iOS／Android／macOS）
NativeUserInteractionIntegration	ネイティブレイヤーからユーザー操作のパンくずリストを取得します
UserInteractionIntegration	Dart レイヤーのタップ／クリックトランザクションを計測します（SentryWidget が必要です）
DeviceContextIntegration	デバイスモデル、OS バージョン、画面解像度を取得します
AppContextIntegration	アプリのバージョン、ビルド番号、バンドル ID を取得します
ConnectivityIntegration	ネットワーク接続の変更をパンくずリストとして記録します
HttpClientIntegration	Dart の http リクエストを自動計測します
SdkIntegration	SDK メタデータをタグ付けします
ReleaseIntegration	パッケージ情報から iOS／Android のリリースを自動設定します

---

検証

セットアップ後、Sentry がイベントを受信していることをテストします。

// Add a test button somewhere visible during development:
ElevatedButton(
  onPressed: () {
    throw Exception('Sentry test error!');
  },
  child: const Text('Test Sentry Error'),
)

// Or capture manually:
ElevatedButton(
  onPressed: () {
    Sentry.captureMessage('Sentry test message', level: SentryLevel.info);
  },
  child: const Text('Test Sentry Message'),
)

// Test structured logging:
ElevatedButton(
  onPressed: () {
    Sentry.logger.info('Test log from Flutter app');
  },
  child: const Text('Test Sentry Log'),
)

Sentry ダッシュボードを確認します。

• Issues → テストエラーが数秒以内に表示されます
• Traces → 子スパンを含むナビゲーショントランザクションを確認します
• Replays → アプリの操作後にセッション録画が表示されます（iOS／Android のみ）
• Logs → enableLogs: true の場合、構造化ログエントリが表示されます

⚠️ デバッグモードでのプラットフォームの制限：

• ネイティブクラッシュ、セッションリプレイ、遅いフレームやフリーズしたフレーム、アプリ起動メトリクスは、iOS／Android のリリースビルドでのみ完全に動作します
• flutter run --release を実行するか、実機／エミュレーターを使用してネイティブ機能をテストします
• デバッグモードでは JIT コンパイルを使用する Dart VM が動作するため、一部のネイティブインテグレーションの挙動が異なります

---

フェーズ 4：相互リンク

Flutter のセットアップ完了後、バックエンドで Sentry による監視が不足していないか確認します。

# Adjacent backend directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
ls ../backend/package.json ../server/package.json 2>/dev/null

Sentry が設定されていないバックエンドがある場合は、対応するスキルを提案します。

検出対象	提案するスキル
Go バックエンド（go.mod）	sentry-go-sdk
Python バックエンド（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby バックエンド（Gemfile）	sentry-ruby-sdk
Node.js バックエンド	sentry-node-sdk
.NET バックエンド（*.csproj）	sentry-dotnet-sdk
React／Next.js ウェブ	sentry-react-sdk / sentry-nextjs-sdk

分散トレーシング — バックエンドスキルを追加する場合は、Flutter で tracePropagationTargets を設定し、トレースコンテキストを API に伝播させます。

options.tracePropagationTargets = ['api.myapp.com', 'localhost'];
options.propagateTraceparent = true; // also send W3C traceparent header

これにより、Sentry のウォーターフォールビューでモバイルのトランザクションとバックエンドのトレースが関連付けられます。

---

トラブルシューティング

問題	解決方法
イベントが Sentry に表示されない	options.debug = true を設定します。SDK のログが Flutter コンソールに出力されます。DSN が正しいことを確認してください
SentryFlutter.init が例外をスローする	main() が async であり、SentryFlutter.init(...) を await していることを確認してください
Sentry でスタックトレースが読めない	sentry_dart_plugin でデバッグシンボルをアップロードします。--obfuscate --split-debug-info を指定してビルドしてください
Web でスタックトレースが表示されない	--source-maps を指定してビルドし、dart run sentry_dart_plugin を実行してアップロードしてください
ネイティブクラッシュがキャプチャされない	enableNativeCrashHandling: true を確認してください。デバッグモードではなく、リリースモードでテストしてください
セッションリプレイが記録されない	iOS／Android のみ対応しています。ルートを SentryWidget でラップしていることを確認し、replay.onErrorSampleRate を確認してください
リプレイに空白の画面が表示される	SentryWidget(child: MyApp()) が最も外側のウィジェットであり、ナビゲーターの内側にないことを確認してください
プロファイリングが機能しない	iOS と macOS のみ対応しています（アルファ版）。まず tracesSampleRate > 0 が設定されていることを確認してください
ナビゲーションが追跡されない	navigatorObservers に SentryNavigatorObserver() を追加し、すべてのルートに名前を付けてください
GoRouter のルートに名前がない	すべての GoRoute エントリに name: を追加してください。名前のないルートは null として追跡されます
TTFD が報告されない	データの読み込み後に SentryFlutter.currentDisplay()?.reportFullyDisplayed() を呼び出すか、SentryDisplayWidget でラップしてください
sentry_dart_plugin の認証エラー	pubspec.yaml にハードコードするのではなく、SENTRY_AUTH_TOKEN 環境変数を設定してください
Android の ProGuard マッピングが見つからない	--extra-gen-snapshot-options=--save-obfuscation-map=... フラグが設定されていることを確認してください
iOS の dSYM がアップロードされない	sentry_dart_plugin が処理します。pubspec.yaml の sentry: ブロックで upload_debug_symbols: true を確認してください
pub get が失敗する：Dart SDK が古い	sentry_flutter ≥9.0.0 には Dart ≥3.5.0 が必要です。flutter upgrade を実行してください
Android のデバッグ中にホットリスタートでクラッシュする	既知の問題です（SDK ≥9.9.0 で修正済み）。古いバージョンを使用している場合はアップグレードしてください
ANR 検出の条件が厳しすぎる	anrTimeoutInterval を大きくしてください（デフォルト：5000ms）
ダッシュボードのトランザクションが多すぎる	tracesSampleRate を 0.1 に下げるか、tracesSampler を使ってヘルスチェックを除外してください
ネイティブクラッシュで beforeSend が実行されない	想定どおりです。beforeSend は Dart 層のイベントのみをインターセプトします。ネイティブクラッシュには適用されません
Crons が利用できない	Flutter／Dart SDK は Sentry Crons をサポートしていません。代わりにサーバーサイド SDK を使用してください
テストで SentryWidget の警告が表示される	setUpAll でテストウィジェットを SentryFlutter.init() でラップするか、enabled: false を使用してください
Firebase Remote Config：Linux／Windows	sentry_firebase_remote_config は Linux／Windows ではサポートされていません（Firebase の制限）
Web での Isar トレース	sentry_isar は Web をサポートしていません（Isar が Web をサポートしていません）