Flutter集成Sentry如何发送事件、绑定用户信息及调试模式关闭上报

1. 如何在Sentry中发送自定义信息、正确使用Events能力 #

Sentry的自定义信息上报分为两种常用场景，使用方式和对应位置如下：

• 主动上报自定义事件/业务异常：如果需要上报非崩溃类的业务问题（比如支付失败、接口请求异常但未触发崩溃），直接在对应业务逻辑的异常捕获块中调用Sentry.captureEvent()或者Sentry.captureException()方法即可，还可以附带自定义标签、额外字段、用户信息等上下文内容。
• 全局绑定通用自定义字段：如果需要让所有上报的错误/事件都默认携带固定信息（比如用户邮箱、APP版本、业务渠道号），可以通过配置Scope全局绑定，后续所有上报都会自动携带这些字段。

错误上报附带用户邮箱的示例代码如下：

try {
  // 可能抛出异常的业务逻辑
} catch (exception, stackTrace) {
  await Sentry.captureException(
    exception,
    stackTrace: stackTrace,
    withScope: (scope) {
      // 单次上报绑定用户邮箱
      scope.setUser(SentryUser(email: 'user@example.com', id: 'xxxx'));
      scope.setExtra('当前操作', '提交订单');
      scope.setTag('业务模块', '订单中心');
    },
  );
}

2. 配置用户信息的代码放置位置 #

你给出的Sentry.configureScope配置用户信息的代码，放在用户身份信息获取成功之后的位置即可，常见放置场景：

• 用户登录成功后：用户完成账号登录、拿到用户ID、邮箱等信息后调用这段代码，后续所有上报的事件都会自动绑定对应用户信息。
• APP启动读取到缓存登录态时：如果APP启动时就已经有本地缓存的已登录用户信息，可以在初始化完Sentry、读取完用户缓存后直接调用配置。
• 用户退出登录时也可以调用同样的方法把scope.user设为null，清除用户信息绑定，避免匿名状态的事件绑定已退出的用户信息。

该配置是全局持久生效的，不需要重复调用，仅在用户身份变更时修改即可。

3. 调试模式下关闭Sentry上报的配置方法 #

只需要在初始化Sentry时，通过Flutter内置的kDebugMode常量判断当前是否为调试模式，设置enabled参数即可，示例代码如下：

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

Future<void> main() async {
  await SentryFlutter.init(
    (options) {
      options.dsn = '你的Sentry项目DSN';
      // 调试模式下关闭所有上报
      options.enabled = !kDebugMode;
      // 调试模式下可以开启SDK日志方便排查接入问题
      options.debug = kDebugMode;
    },
    appRunner: () => runApp(const MyApp()),
  );
}

如果需要更细粒度的控制，比如调试模式下只关闭崩溃上报、允许上报自定义业务事件，可以单独配置enableAutoNativeCrashTracking、enableAutoPerformanceTracking等细分开关，也可以在上报逻辑处自行判断环境过滤上报。

内容的提问来源于stack exchange，提问作者Rock