用户体验监控兼容 Sentry SDK 事件上报最佳实践

原生 JavaScript (Browser) 项目示例

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://key@<YOUR-ENDPOINT>/0",
  
  // ─── 基础配置 ───
  release: "my-web-app@1.2.0",
  environment: "production",

  // ─── Performance Tracing（性能追踪） ───
  tracesSampleRate: 1.0, // 生产环境建议按需调整，例如 0.2

  integrations:[
    // 自动采集 pageload / navigation / resource / Web Vitals 等
    Sentry.browserTracingIntegration(),
  ],
});

Android 项目完整示例 (Kotlin)

import android.app.Application
import io.sentry.android.core.SentryAndroid
import io.sentry.android.core.SentryAndroidOptions

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        SentryAndroid.init(this) { options ->
            options.dsn = "https://key@<YOUR-ENDPOINT>/0"
            
            // ─── 基础配置 ───
            options.release = "my-android-app@1.2.0"
            options.environment = "production"

            // ─── Performance Tracing（性能追踪） ───
            options.tracesSampleRate = 1.0
        }
    }
}

Android 补充提示： 对于网络请求（Resource 事件），如果您使用的是 OkHttp 或 Retrofit，必须在构建 OkHttpClient 时添加 SentryOkHttpInterceptor()，否则无法自动采集接口请求耗时。

iOS (Swift) 项目完整示例

import UIKit
import Sentry

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        SentrySDK.start { options in
            options.dsn = "https://key@<YOUR-ENDPOINT>/0"
            
            // ─── 基础配置 ───
            options.environment = "production"
            options.releaseName = "my-ios-app@1.2.0"
            
            // ─── Performance Tracing（性能追踪） ───
            options.tracesSampleRate = 1.0
        }

        return true
    }
}

关键配置项说明

自动采集的 RUM 数据总览

开启上述配置后，以下数据会被自动采集，无需额外代码：

不需要开启的配置

使用方式

通过 Sentry.startSpan 上报，op 固定为 rum.custom：

import * as Sentry from "@sentry/vue"; // 或 @sentry/react、@sentry/browser 等

// 基础用法
Sentry.startSpan(
  {
    op: "rum.custom",
    name: "支付流程",
    attributes: {
      "custom.group": "payment",
      "custom.value": "99.9",
    },
  },
  () => {
    // 业务逻辑...
  }
);

// 携带自定义业务属性
Sentry.startSpan(
  {
    op: "rum.custom",
    name: "商品搜索",
    attributes: {
      "custom.group": "search",
      "custom.value": "42",
      // 以下属性会自动落入 properties，可在控制台查询
      "keyword": "蓝牙耳机",
      "result_count": 42,
      "search_type": "full_text",
    },
  },
  () => {
    // 搜索逻辑...
  }
);

异步场景

如果业务逻辑是异步的，回调函数返回 Promise 即可，SDK 会自动等待完成后计算耗时：

await Sentry.startSpan(
  {
    op: "rum.custom",
    name: "上传文件",
    attributes: {
      "custom.group": "upload",
      "file_type": "image",
      "file_size": 1024000,
    },
  },
  async () => {
    await uploadFile(file);
  }
);

字段说明

使用方式

通过 Sentry.captureMessage 上报：

import * as Sentry from "@sentry/vue";

// 基础用法（默认 level 为 "info"）
Sentry.captureMessage("用户完成了新手引导流程");

// 指定日志级别
Sentry.captureMessage("支付重试超过最大次数", "warning");

字段说明

使用方式

通过 Sentry.captureException 上报：

import * as Sentry from "@sentry/vue";

// 基础用法 — 捕获一个 Error 对象
try {
  riskyOperation();
} catch (err) {
  Sentry.captureException(err);
}

// 手动构造 Error 上报
Sentry.captureException(new Error("支付接口返回异常状态码"));

// 捕获 Promise 异常
fetchOrder(orderId).catch((err) => {
  Sentry.captureException(err);
});

落盘说明

captureException 上报的事件会生成以下 RUM 数据：

注意事项

• 始终传入 Error 对象：captureException(new Error("msg")) 比 captureException("msg") 更好，前者会包含完整堆栈信息。

• 与 captureMessage 的区别：captureException 走 Exception 链路，有堆栈和错误分组；captureMessage 走 Custom Log 链路，是轻量日志。

• 不要用 captureMessage 上报错误：错误场景请使用 captureException，以便在控制台获得完整的错误分析能力。

使用方式

import * as Sentry from "@sentry/vue";

// 用户登录后设置
Sentry.setUser({
  id: "user-12345",
  username: "张三",
  data: {
    vip_level: "gold",
    department: "engineering",
  },
});

// 用户退出后清除
Sentry.setUser(null);

字段说明

注意事项

• 尽早调用 setUser：建议在用户登录完成后立即设置，确保后续事件都能关联到用户。

• id 是最重要的字段：控制台按用户维度检索依赖此字段，建议使用业务系统的用户 ID。

• data 适合放业务属性：如会员等级、用户角色、所属组织等，会以 JSON 格式存储在 userTags 中。

• 退出时清除用户信息：调用 Sentry.setUser(null) 避免事件错误关联到已退出的用户。