Application Real-Time Monitoring Service：使用者體驗監控相容 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 是最重要的欄位：控制台按使用者維度檢索依賴此欄位，建議使用業務系統的使用者識別碼。

• data 適合放業務屬性：如會員等級、使用者角色、所屬組織等，會以 JSON 格式儲存在 userTags 中。

• 退出時清除使用者資訊：調用 Sentry.setUser(null) 避免事件錯誤關聯到已退出的使用者。