崩溃监控与线上可观测性

import 'dart:async';
import 'dart:ui';
import 'package:flutter/foundation.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  // 必须在 runApp 之前初始化
  WidgetsFlutterBinding.ensureInitialized();

  // 第一层：框架异常（build/layout/paint 期间的错误）
  FlutterError.onError = (FlutterErrorDetails details) {
    // 转发给框架默认处理（debug 下会打印红屏）
    FlutterError.presentError(details);
    // 上报到监控
    Sentry.captureException(
      details.exception,
      stackTrace: details.stack,
      hint: Hint.withMap({'context': details.context?.toString() ?? ''}),
    );
  };

  // 第二层：异步未捕获异常（Dart 2.19+ 推荐入口）
  PlatformDispatcher.instance.onError = (Object error, StackTrace stack) {
    Sentry.captureException(error, stackTrace: stack);
    return true;   // 返回 true 表示已处理，不再向上抛
  };

  await SentryFlutter.init(
    (options) {
      options.dsn = 'https://xxx@sentry.example.com/1';
      options.tracesSampleRate = 0.2;
    },
    appRunner: () => runApp(const MyApp()),
  );
}

#0      a (package:myapp/main.dart)
#1      b (package:myapp/main.dart)

# 1. 构建时剥离符号
flutter build appbundle --release \
  --obfuscate \
  --split-debug-info=build/symbols

# 2. 上传符号到 Sentry（需要 SENTRY_AUTH_TOKEN 与 org/project）
sentry-cli upload-dif --org my-org --project my-flutter-app build/symbols

# Android 原生符号（native debug symbols）也要上传
sentry-cli upload-dif --org my-org --project my-flutter-app \
  build/app/intermediates/merged_native_libs/release/out/lib

# iOS 需要上传 dSYM
sentry-cli upload-dif --org my-org --project my-flutter-app \
  build/ios/archive/Runner.xcarchive/dSYMs

# .github/workflows/release.yml（节选）
- name: Build with symbols
  run: flutter build appbundle --release --obfuscate --split-debug-info=build/symbols
- name: Upload symbols
  run: sentry-cli upload-dif --org $ORG --project $PROJECT build/symbols
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
- name: Archive symbols
  uses: actions/upload-artifact@v4
  with:
    name: symbols-${{ github.sha }}
    path: build/symbols
    retention-days: 90

import 'package:flutter/scheduler.dart';

class FrameMonitor {
  static const _slowFrameThreshold = Duration(milliseconds: 16);  // 60fps 预算

  static void start() {
    SchedulerBinding.instance.addTimingsCallback((List<FrameTiming> timings) {
      for (final t in timings) {
        final buildMs = t.buildDuration.inMilliseconds;
        final rasterMs = t.rasterDuration.inMilliseconds;
        final totalMs = t.totalSpan.inMilliseconds;

        // 掉帧上报：单帧超过预算 2 倍视为卡顿
        if (totalMs > 32) {
          Sentry.addBreadcrumb(Breadcrumb(
            message: 'Slow frame: build=${buildMs}ms raster=${rasterMs}ms',
            category: 'performance',
            level: Severity.warning,
          ));
        }
      }
    });
  }
}

// 记录关键操作（导航、接口调用、状态变更）
Sentry.addBreadcrumb(Breadcrumb(
  message: 'Navigate to /checkout',
  category: 'navigation',
  level: Severity.info,
));

// 网络请求失败时记录
Sentry.addBreadcrumb(Breadcrumb(
  message: 'GET /api/cart failed: 500',
  category: 'http',
  level: Severity.error,
  data: {'status': 500, 'duration_ms': 1230},
));

// 设置用户上下文（注意脱敏，不要放手机号、身份证）
Sentry.configureScope((scope) {
  scope.setUser(SentryUser(
    id: userId,               // 内部 ID，非手机号
    // 不要设置 email、username 等 PII
  ));
  scope.setTag('app_version', '1.2.3');
  scope.setTag('build_flavor', 'prod');
  scope.setContexts('device', {
    'model': deviceModel,
    'os_version': osVersion,
    'screen': '$width x $height',
  });
});

SentryFlutter.init((options) {
  options.dsn = 'https://xxx@sentry.example.com/1';

  // 错误采样：崩溃全量上报，非致命错误按比例采样
  options.sampleRate = 1.0;

  // 性能追踪采样：只对 20% 的会话追踪，控制成本
  options.tracesSampleRate = 0.2;

  // 同一异常在上报前聚合，避免刷屏
  options.beforeSend = (event, hint) {
    // 过滤掉已知的、无价值的噪音
    final ex = event.throwable;
    if (ex is FlutterError && ex.message.contains('setState() called after dispose')) {
      return null;   // 返回 null 丢弃
    }
    return event;
  };

  // 上报前脱敏
  options.beforeBreadcrumb = (crumb, hint) {
    // 移除 URL 里的 token 参数
    return crumb;
  };
});

// 后台 Isolate 内单独捕获
void isolateEntry(SendPort sendPort) {
  runZonedGuarded(() {
    // 后台任务
  }, (error, stack) {
    sendPort.send({'error': error.toString(), 'stack': stack.toString()});
  });
}