RUM-Web Sentry Browser SDK v7 Integration

rum-sentry-integration-v7-browser 是腾讯云 RUM-Web 埋点 SDK 的自定义 Sentry Integration，为 Sentry Browser SDK v7 注入浏览器环境上下文、网络信息、设备 ID、HTTP 请求全量拦截、静态资源采集、TTI 测算和自定义事件上报能力。

功能

• 设备 ID — UUID 生成 + localStorage 持久化（AEGIS_ID），跨会话复用
• 会话 ID — 支持 Sentry 官方 session sid 或 aegis-sdk 共享 session 两种数据源，注入 contexts.app.app_session_id，后端落库到 RUM 日志会话 ID 字段
• 环境上下文 — 视口（viewport）、用户偏好（语言/主题）、网络类型（effectiveType）
• HTTP 拦截 — 全量拦截 fetch/XHR（成功+失败+耗时），自动抑制 Sentry 原生 httpClientIntegration 的重复上报（详见下文「与 httpClientIntegration 的关系」）
• 静态资源采集 — 首次资源注入 resource.success 状态 + 动态资源 PerformanceObserver/MutationObserver 独立采集
• TTI 测算 — 基于 Google Lighthouse 定义的 TTI 计算（Longtask Observer + FCP）
• 内存 OOM 检测 — 轮询 performance.memory（仅 Chrome），超阈值时通过 captureEvent 上报，后端入库为 OOM 事件（含冷却时间防抖）
• 自定义事件 — reportEvent(name, data) 底层 captureEvent + isCustomEvent tag，后端路由到 LogCollectionEvent
• 可配置开关 — 所有采集能力可独立启用/禁用

安装

npm install rum-sentry-integration-v7-browser

确保已安装 @sentry/browser ^7.0.0 作为 peer dependency。

使用

import { init, browserTracingIntegration } from '@sentry/browser';
import { RumWebIntegration } from 'rum-sentry-integration-v7-browser';

init({
  dsn: 'https://{RumProjectKey}@{rum_collect_host}/1',
  // BrowserTracing 采集的 pageload/navigation/resource spans 通过 transaction 上报，
  // tracesSampleRate 默认为 0（不上报任何 transaction），必须显式设置否则这些指标全部丢失
  tracesSampleRate: 1.0,
  integrations: [
    // RUM-Web 部分指标（pageload、navigation timing、resource spans 等）依赖 Browser Tracing 上报
    // @sentry/browser >= 7.99.0 推荐使用函数式写法 browserTracingIntegration()
    // 也兼容 new BrowserTracing()（类形式在 7.99.0 仍可用，仅标记 deprecated）
    browserTracingIntegration(),

    // 注意：无需加载 httpClientIntegration，RumWebIntegration 会自动抑制其重复上报
    // （v7 下 httpClientIntegration 注册的 fetch/XHR handler 无法撤销，RumWebIntegration
    //  通过 processEvent 去重；建议仍从 integrations 中移除以避免无用的 event 创建开销）
    new RumWebIntegration({
      // 设备 ID（可选，默认开启）
      captureDeviceId: true,
      // 会话 ID 数据源（可选，默认 'sentry'）
      //   'sentry' — 使用 Sentry 原生 session sid（与 session envelope item 对齐）
      //   'aegis'  — 使用 aegis-sdk 共享 session（与同页面 aegis 上报对齐）
      sessionIdSource: 'sentry',
      // 网络信息采集（可选，默认开启）
      captureNetworkInfo: true,
      // HTTP 请求拦截（默认开启）
      httpConfig: {
        successStatusCodes: [200, 399],  // 成功范围
        errorStatusCodes: [400, 599],    // 错误范围
      },
      // 静态资源采集（默认开启）
      captureStaticResources: true,
      // TTI 测算（默认开启）
      captureTTI: true,
      // 内存 OOM 检测（默认开启，仅 Chrome 支持 performance.memory）
      memoryMonitor: {
        enabled: true,
        // oomThreshold: 180,      // 阈值(MB)，默认设备内存上限的 90%
        // oomCheckInterval: 10000,// 检测间隔(ms)，默认 10s
        // oomCooldown: 300000,    // 冷却时间(ms)，默认 5min
        // sampleRate: 1,          // 采样率，默认全量
      },
      // 自定义标签
      customTags: {
        app_version: '1.0.0',
        environment: 'production',
      },
    }),
  ],
});

Browser Tracing 版本兼容

RUM-Web 的 pageload、navigation timing、resource spans 等指标依赖 Sentry Browser Tracing。

不同 @sentry/browser v7 小版本的接入方式不同：

| @sentry/browser 版本 | 推荐写法 | | --- | --- | | >= 7.99.0 | import { browserTracingIntegration } from '@sentry/browser'; 然后使用 browserTracingIntegration() | | >= 7.44.0 < 7.99.0 | import { BrowserTracing } from '@sentry/browser'; 然后使用 new BrowserTracing() | | < 7.44.0 | 需要额外安装同版本 @sentry/tracing，从 @sentry/tracing 导入 BrowserTracing |

与 httpClientIntegration 的关系

RumWebIntegration 的 HTTP 拦截器（initHTTPInterceptor）已全量拦截 fetch/XHR（成功+失败+耗时+业务返回码），字段格式参照 Sentry 原生 httpClientIntegration（@sentry/integrations），功能完全覆盖，无需再加载 httpClientIntegration。

若两者同时加载，RumWebIntegration 会自动抑制 httpClientIntegration 的重复上报，确保同一个失败请求不会被 captureEvent 两次：

1. setupOnce 时检测到 HttpClient integration 已加载，从 client._integrations 移除并打 warning
2. processEvent 对 httpClientIntegration 仍产生的 event 做去重丢弃（判定：mechanism.type === 'http.client' 且无 tags.httpSuccess）

限制说明：Sentry v7 下 httpClientIntegration.setup() 通过 addFetchInstrumentationHandler / addXhrInstrumentationHandler 注册的全局 handler 注册后无法撤销，且 v7 没有 removeIntegration API。因此上述"抑制"是靠 processEvent 去重实现的，httpClientIntegration 的 fetch/XHR 拦截逻辑仍会执行（仍会创建 event 对象再被丢弃）。建议仍从 integrations 中移除 httpClientIntegration()，以避免这部分无用的 event 创建开销。

自定义事件上报

import { reportEvent } from 'rum-sentry-integration-v7-browser';

// 基本用法
reportEvent('order_placed');

// 带数据
reportEvent('order_placed', {
  tags: { order_id: '12345' },
  ext1: 'shop',
  ext2: 'express',
});

会话 ID 数据源

会话 ID 注入到 event.contexts.app.app_session_id，后端 tam_collect_svr 解析后落库到 RUM 日志的会话 ID 字段。通过 sessionIdSource 选择数据源：

// 默认：使用 Sentry 官方 session sid
// 需在 Sentry.init 中开启 autoSessionTracking
init({
  dsn: 'YOUR_DSN',
  autoSessionTracking: true,
  integrations: [new RumWebIntegration({ sessionIdSource: 'sentry' })],
});

// 或：使用 aegis-sdk 的共享 session
// 适用于同页面已接入 aegis-sdk、希望 Sentry 与 aegis 上报共用同一会话 ID 的场景
init({
  dsn: 'YOUR_DSN',
  integrations: [new RumWebIntegration({ sessionIdSource: 'aegis' })],
});

| 数据源 | 优先级 1 | 优先级 2 | 优先级 3 | |--------|----------|----------|----------| | 'sentry'（默认） | Sentry scope session sid（autoSessionTracking 启用） | sessionStorage RUM_SESSION_ID | 内存 UUID | | 'aegis' | window.__MONITOR_SESSION_V1__.sessionId | sessionStorage __MONITOR_SESSION_V1__ | sessionStorage RUM_SESSION_ID → 内存 UUID |

'aegis' 模式只读取 aegis-sdk 已创建的共享 session，不会创建或刷新它（session 生命周期由 aegis-sdk 管理：60 分钟最大存活 + 15 分钟空闲超时）。aegis-sdk 未加载时自动 fallback。

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | captureDeviceId | boolean | true | 是否采集设备 ID（localStorage 持久化 UUID） | | captureSessionId | boolean | true | 是否采集会话 ID（注入 contexts.app.app_session_id） | | sessionIdSource | 'sentry' \| 'aegis' | 'sentry' | 会话 ID 数据源：'sentry' 使用 Sentry 原生 session sid；'aegis' 使用 aegis-sdk 共享 session（window.__MONITOR_SESSION_V1__）。两者在数据源不可用时均 fallback 到 sessionStorage 持久化 UUID | | captureViewport | boolean | true | 是否收集浏览器视口信息 | | captureUserPreferences | boolean | true | 是否收集用户偏好（语言、主题） | | captureNetworkInfo | boolean | true | 是否收集网络连接信息（effectiveType/downlink/rtt） | | capturePerformanceMemory | boolean | false | 是否收集性能内存信息（仅 Chrome） | | captureStaticResources | boolean | true | 是否采集静态资源成功/失败状态（首次+动态） | | captureTTI | boolean | true | 是否测算并上报 TTI | | memoryMonitor.enabled | boolean | true | 是否启用内存 OOM 检测（仅 Chrome） | | memoryMonitor.oomThreshold | number | 设备上限 90% | OOM 阈值（MB），无法获取设备上限时回退 100MB | | memoryMonitor.oomCheckInterval | number | 10000 | OOM 检测轮询间隔（ms） | | memoryMonitor.oomCooldown | number | 300000 | 两次 OOM 上报最小间隔/冷却时间（ms） | | memoryMonitor.sampleRate | number | 1 | OOM 检测采样率（0-1） | | httpConfig.successStatusCodes | [number, number] | [200, 399] | 成功状态码范围（包含边界） | | httpConfig.errorStatusCodes | [number, number] | [400, 599] | 错误状态码范围（包含边界） | | customTags | Record<string, string> | {} | 附加到每个事件的自定义标签 | | customContext | Record<string, Record<string, unknown>> | {} | 合并到事件 contexts 中的自定义上下文 |

浏览器兼容性

• Chrome 74+, Firefox 67+, Safari 12+, Edge 79+
• 所有采集模块在浏览器 API 不可用时静默降级（try/catch + 特性检测），不阻塞页面渲染
• localStorage 不可用时设备 ID 降级为内存 UUID
• sessionStorage 不可用时 / Sentry session 未启用时 / aegis-sdk 未加载时会话 ID 降级为内存 UUID
• PerformanceObserver 不可用时动态资源/TTI 采集静默跳过

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听变化自动编译）
npm run dev

# 运行测试
npm test

# 监听模式测试
npm run test:watch

License

MIT