すべてのスキル > 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: 検出

プロジェクトを理解して推奨事項を作成する前に、以下のコマンドを実行します：

# Flutter プロジェクトタイプと既存の Sentry を検出
cat pubspec.yaml | grep -E '(sentry|flutter|dart)'

# SDK バージョンを確認
cat pubspec.yaml | grep -A2 'environment:'

# 既存の Sentry 初期化を確認
grep -r "SentryFlutter.init\|Sentry.init" lib/ 2>/dev/null | head -5

# ナビゲーションライブラリを検出
grep -E '(go_router|auto_route|get:|beamer|routemaster)' pubspec.yaml

# HTTP クライアントを検出
grep -E '(dio:|http:|chopper:)' pubspec.yaml

# データベースパッケージを検出
grep -E '(sqflite|drift|hive|isar|floor)' pubspec.yaml

# 状態管理を検出（統合パターン用）
grep -E '(flutter_bloc|riverpod|provider:|get:)' pubspec.yaml

# GraphQL を検出
grep -E '(graphql|ferry|gql)' pubspec.yaml

# Firebase を検出
grep -E '(firebase_core|supabase)' pubspec.yaml

# クロスリンク用バックエンドを検出
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

# プラットフォームターゲットを検出
ls android/ ios/ macos/ linux/ windows/ web/ 2>/dev/null

決定すべき内容：

質問	影響
sentry_flutter は既に pubspec.yaml にある?	インストールをスキップして機能設定に進む
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	N/A	Flutter/Dart SDK では利用不可

提案：「iOS/Android をターゲットとする Flutter アプリの場合、エラー監視 + トレース + セッションリプレイをお勧めします。ログとプロファイリング（iOS/macOS アルファ）も追加したいですか？」

---

フェーズ 3: ガイダンス

セットアップパスを決定する

プロジェクトタイプ	推奨セットアップ
任意の Flutter アプリ	ウィザード CLI（pubspec、init、シンボルアップロードを処理）
マニュアルを希望	以下のパス B — pubspec.yaml + main.dart
Dart のみ（CLI、サーバー）	以下のパス C — 純粋な sentry パッケージ

---

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

これはあなた自身で実行する必要があります — ウィザードはログイン用にブラウザを開き、エージェントが処理できない対話的入力が必要です。ターミナルにコピーペーストしてください：

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

これは org/プロジェクト選択を処理し、sentry_flutter を pubspec.yaml に追加し、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	認証トークンと org/プロジェクト設定	シンボルアップロード資格情報

完了したら、戻って 検証 に進みます。

ユーザーがウィザードをスキップした場合、以下のパス 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;

      // トレース
      options.tracesSampleRate = 1.0; // 本番環境では 0.1–0.2 に下げる

      // プロファイリング（iOS と macOS のみ — アルファ）
      options.profilesSampleRate = 1.0;

      // セッションリプレイ（iOS と Android のみ）
      options.replay.sessionSampleRate = 0.1;
      options.replay.onErrorSampleRate = 1.0;

      // 構造化ロギング（SDK ≥9.5.0）
      options.enableLogs = true;

      options.environment = const bool.fromEnvironment('dart.vm.product')
          ? 'production'
          : 'development';
    },
    // 必須：スクリーンショット、リプレイ、ユーザーインタラクション追跡を有効化するためにルートウィジェットをラップ
    appRunner: () => runApp(SentryWidget(child: MyApp())),
  );
}

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

SentryNavigatorObserver を MaterialApp または CupertinoApp に追加：

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(),
      ],
      // 常にルートに名前を付けて Sentry が追跡できるようにする
      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', // Sentry ルート追跡に必須
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'profile/:id',
          name: 'profile', // 必須
          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  # 代わりに SENTRY_AUTH_TOKEN 環境変数を推奨
  upload_debug_symbols: true
  upload_sources: true
  upload_source_maps: true     # 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;

      // 環境 — dart.vm.product 経由でリリースビルドを検出
      options.environment = const bool.fromEnvironment('dart.vm.product')
          ? 'production'
          : 'development';

      // リリースは iOS/Android で自動設定されます「packageName@version+build」として
      // 必要な場合はオーバーライド：
      // options.release = 'my-app@1.0.0+42';

      // エラーサンプリング — 高ボリュームの本番環境でエラーの一部をドロップするために削減
      options.sampleRate = 1.0;

      // トレース — 高トラフィックの本番環境では 0.1–0.2 に下げる
      options.tracesSampleRate = 1.0;

      // プロファイリング — iOS と macOS のみ（アルファ）； tracesSampleRate に対する相対値
      options.profilesSampleRate = 1.0;

      // セッションリプレイ — iOS と Android のみ（SDK ≥9.0.0）
      options.replay.sessionSampleRate = 0.1;   // すべてのセッションの 10% を記録
      options.replay.onErrorSampleRate = 1.0;   // エラーセッションは常に記録

      // プライバシーデフォルト — すべてのテキストと画像がマスク
      options.privacy.maskAllText = true;
      options.privacy.maskAllImages = true;

      // 構造化ロギング（SDK ≥9.5.0）
      options.enableLogs = true;

      // 添付ファイル
      options.attachScreenshot = true;          // エラー時にスクリーンショット
      options.attachViewHierarchy = true;       // エラー時にウィジェットツリー

      // HTTP クライアント
      options.captureFailedRequests = true;     // HTTP エラーを自動キャプチャ
      options.maxRequestBodySize = MaxRequestBodySize.small;

      // Android 固有
      options.anrEnabled = true;                // ANR 検出
      options.enableNdkScopeSync = true;        // ネイティブへスコープを同期
      options.enableTombstone = false;          // Android 12+ トームストーン（オプトイン）

      // ナビゲーション（Time to Full Display — オプトイン）
      options.enableTimeToFullDisplayTracing = true;
    },
    appRunner: () => runApp(SentryWidget(child: MyApp())),
  );
}

---

ナビゲーション: Time to Full Display (TTFD)

TTID（Time to Initial Display）は常に有効です。TTFD はオプトイン：

// オプションで有効化：
options.enableTimeToFullDisplayTracing = true;

その後、スクリーンがデータをロードしたときにレポート：

// オプション 1: ウィジェットラッパー（子が最初にレンダリングされるときに TTFD をマーク）
SentryDisplayWidget(child: MyWidget())

// オプション 2: マニュアル API 呼び出し（非同期データロード後）
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/<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	Android 12+ ネイティブクラッシュ情報 ApplicationExitInfo 経由（オプトイン）
attachThreads	bool	false	クラッシュ時にすべてのスレッドを添付（Android）
captureNativeFailedRequests	bool	—	ネイティブ HTTP エラーキャプチャ、Dart クライアント独立（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	Data Source Name	options.dsn からフォールバック
SENTRY_ENVIRONMENT	デプロイメント環境	options.environment からフォールバック
SENTRY_RELEASE	リリース識別子	options.release からフォールバック
SENTRY_DIST	ビルド分布	options.dist からフォールバック
SENTRY_AUTH_TOKEN	デバッグシンボルアップロード	アプリに埋め込まない — ビルドツールのみ
SENTRY_ORG	Organization slug	sentry_dart_plugin で使用
SENTRY_PROJECT	Project slug	sentry_dart_plugin で使用

使用法：

flutter build apk --release \
  --dart-define=SENTRY_DSN=https://xxx@sentry.io/123 \
  --dart-define=SENTRY_ENVIRONMENT=production

その後、コード内：

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

---

エコシステム統合

sentry_flutter と並行してこれらのパッケージを追加し、より深い計測を実現：

HTTP クライアント

標準 http パッケージ — sentry_flutter に組み込まれ、追加インストール不要：

import 'package:sentry/sentry.dart';

// HTTP クライアントをラップ
final client = SentryHttpClient(
  captureFailedRequests: true,
  failedRequestStatusCodes: [SentryStatusCode.range(400, 599)],
);
try {
  final response = await client.get(Uri.parse('https://api.example.com/users'));
} finally {
  client.close();
}

Dio — sentry_dio をインストール：

flutter pub add sentry_dio

import 'package:dio/dio.dart';
import 'package:sentry_dio/sentry_dio.dart';

final dio = Dio();
// インターセプターを最初に追加してから、THEN addSentry()を最後に
dio.addSentry(
  captureFailedRequests: true,
  failedRequestStatusCodes: [SentryStatusCode.range(400, 599)],
);

データベース

パッケージ	インストール	セットアップ
sentry_sqflite	flutter pub add sentry_sqflite	databaseFactory = SentrySqfliteDatabaseFactory();
sentry_drift	flutter pub add sentry_drift	.interceptWith(SentryQueryInterceptor(databaseName: 'db'))
sentry_hive	flutter pub add sentry_hive	Hive の代わりに SentryHive を使用
sentry_isar	flutter pub add sentry_isar	Isar.open() の代わりに SentryIsar.open() を使用

その他

パッケージ	インストール	目的
sentry_logging	flutter pub add sentry_logging	Dart logging パッケージ → Sentry ブレッドクラム/イベント
sentry_link	flutter pub add sentry_link	GraphQL（gql、graphql_flutter、ferry）トレース
sentry_supabase	flutter pub add sentry_supabase	Supabase クエリトレース（SDK ≥9.9.0）
sentry_firebase_remote_config	flutter pub add sentry_firebase_remote_config	機能フラグ追跡
sentry_file	flutter pub add sentry_file	.sentryTrace() 拡張経由のファイル I/O トレース

状態管理パターン

公式パッケージはありません — オブザーバー API 経由で Sentry をワイヤリング：

フレームワーク	フックポイント	パターン
BLoC/Cubit	BlocObserver.onError	onError 内の Sentry.captureException(error, stackTrace: stackTrace)；init 前に Bloc.observer = SentryBlocObserver() を設定
Riverpod	ProviderObserver.providerDidFail	FutureProvider/StreamProvider 失敗で発動；アプリを ProviderScope(observers: [SentryProviderObserver()]) でラップ
Provider/ChangeNotifier	notifyListeners 呼び出し内の try/catch	catch ブロックで Sentry.captureException(e, stackTrace: stack) を手動呼び出し
GetX	GetMaterialApp.onError	GetMaterialApp(onError: (details) => Sentry.captureException(...))

---

本番環境設定

配送前にサンプルレートを低下させ、設定を強化：

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';

      // 高トラフィック本番環境のトランザクションの 10% をトレース
      options.tracesSampleRate = isProduction ? 0.1 : 1.0;

      // トレースされたトランザクションの 100% をプロファイル（プロファイリングは常にサブセット）
      options.profilesSampleRate = 1.0;

      // すべてのエラーセッションをリプレイ、通常セッションの 5% をサンプル
      options.replay.onErrorSampleRate = 1.0;
      options.replay.sessionSampleRate = isProduction ? 0.05 : 1.0;

      // 本番環境ではデバッグロギングを無効化
      options.debug = !isProduction;
    },
    appRunner: () => runApp(SentryWidget(child: MyApp())),
  );
}

---

検証

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

// 開発中に表示する場所にテストボタンを追加：
ElevatedButton(
  onPressed: () {
    throw Exception('Sentry test error!');
  },
  child: const Text('Test Sentry Error'),
)

// または手動でキャプチャ：
ElevatedButton(
  onPressed: () {
    Sentry.captureMessage('Sentry test message', level: SentryLevel.info);
  },
  child: const Text('Test Sentry Message'),
)

// 構造化ロギングをテスト：
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 を使用 — 一部のネイティブ統合は異なる動作をします

---

デフォルトで自動有効化される統合

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 でパッケージ情報からリリースを自動設定

---

フェーズ 4: クロスリンク

Flutter セットアップを完了した後、Sentry カバレッジがないバックエンドをチェック：

# 隣接バックエンドディレクトリ
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 Web	sentry-react-sdk/sentry-nextjs-sdk

分散トレース — バックエンドスキルが追加される場合、Flutter で tracePropagationTargets を設定して API にトレースコンテキストを伝播：

options.tracePropagationTargets = ['api.myapp.com', 'localhost'];
options.propagateTraceparent = true; // W3C traceparent ヘッダーも送信

これはモバイルトランザクションを Sentry ウォーターフォールビュー内のバックエンドトレースにリンク。

---

トラブルシューティング

問題	解決策
Sentry にイベントが表示されない	options.debug = true を設定 — SDK が Flutter コンソールにログ出力；DSN が正しいことを確認
SentryFlutter.init がスロー	main() が async であることを確認；await SentryFlutter.init(...)
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 が最初に設定されていることを確認
ナビゲーションが追跡されていない	SentryNavigatorObserver() を navigatorObservers に追加；すべてのルートに名前を付ける
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 の制限）
Isar トレース Web 上	sentry_isar は Web をサポートしていません（Isar が Web をサポートしていない）