Browser RUM SDK

MoleSignal Browser RUM SDK 会采集浏览器会话、页面访问、用户交互、前端错误、Web Vitals、网络资源以及用于关联链路的上下文。

准备工作

接入前提：

MoleSignal 部署地址；
稳定的应用标识，例如 checkout-web；
可向目标工作区写入 RUM 数据的专用 Token。

clientToken 会包含在浏览器代码中，所有用户都能看到。不要使用所有者、管理员或个人 Token。请使用数据源接入向导生成的应用绑定 msrum_ Client Token。

安装与初始化

安装依赖

npm install @molesignal/browser-rum

只初始化一次 SDK

import { initRum } from '@molesignal/browser-rum';

const rum = initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  service: 'web-frontend',
  env: 'production',
  version: 'v1.4.0',
  sessionSampleRate: 100,
  trackUserInteractions: true,
});

如果需要采集首次页面访问，请在应用路由器挂载前初始化 SDK。服务端渲染期间可以安全地导入并初始化；只有浏览器 API 可用时，浏览器监测才会启动。

验证第一个会话

打开 RUM → 概览，选择包含当前时间的时间范围，确认应用已经出现，然后进入会话检查第一个会话。

site 可以是 MoleSignal Origin、/api 基础地址或 /api/v1 基础地址。SDK 会自动规范化地址，并将数据发送到 /api/v1/rum 下的 RUM 接口。

识别用户并添加上下文

尽量在初始化时提供用户信息，让第一个会话就带有正确身份。

const rum = initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  user: { id: currentUser.id, plan: currentUser.plan },
  globalContext: { region: 'eu-west-1' },
});

rum.setUser({ id: 'user-42', plan: 'enterprise' });
rum.setGlobalContextProperty('feature_flags', ['new-checkout']);

如果未提供用户，SDK 会在 localStorage 中创建稳定的匿名标识。如果隐私政策不允许持久化匿名身份，请设置 trackAnonymousUser: false。

添加自定义操作、错误和页面访问

rum.addAction('Checkout submitted', {
  cart_size: 3,
  payment_method: 'card',
});

try {
  await submitOrder();
} catch (error) {
  rum.addError(error, { component: 'CheckoutForm' });
}

// trackViewsManually 为 true 时使用。
rum.startView('Order confirmation');

在受控跳转或关闭前，如果需要等待队列中的事件发送完成，请调用 rum.flush()。调用 rum.stop() 会移除监测并刷新客户端队列。

自动采集默认值

数据	配置项	默认值
页面访问	`trackViewsManually`	自动跟踪 History API（`false`）
Fetch、XHR 和资源耗时	`trackResources`	`true`
Long Task	`trackLongTasks`	`true`
Web Vitals	`trackWebVitals`	`true`
点击和表单提交	`trackUserInteractions`	`false`
愤怒点击和无效点击	`trackFrustrations`	与交互跟踪保持一致
运行时错误	内置	已启用
`console.error`	`trackConsoleErrors`	`false`
DOM 会话回放	`sessionReplaySampleRate`	`0`

将浏览器请求关联到链路

Fetch 和 XMLHttpRequest 集成会从传出请求、响应或名为 traceparent 的 Server-Timing 条目中读取 W3C traceparent。对于跨域 API，请显式放行来源并暴露响应头：

Access-Control-Expose-Headers: traceparent, server-timing

allowedTracingUrls: [
  'https://api.example.com',
  /^https:\/\/edge-\w+\.example\.com\//,
]

后续步骤

数据采样

分别控制会话和回放数据量。

隐私

在用户设备上拦截敏感数据。

会话回放

安全地记录和回放 DOM 变化。

Source Maps 与 Symbols

还原压缩后的 Browser 堆栈，并查看统一调试产物流程。

快速上手

观察

可靠性

AI 运维

数据

协作

管理

部署与运维

准备工作

安装与初始化

识别用户并添加上下文

添加自定义操作、错误和页面访问

自动采集默认值

将浏览器请求关联到链路

后续步骤

数据采样

隐私

会话回放

Source Maps 与 Symbols

​准备工作

​安装与初始化

​识别用户并添加上下文

​添加自定义操作、错误和页面访问

​自动采集默认值

​将浏览器请求关联到链路

​后续步骤

数据采样

隐私

会话回放

Source Maps 与 Symbols

准备工作

安装与初始化

识别用户并添加上下文

添加自定义操作、错误和页面访问

自动采集默认值

将浏览器请求关联到链路

后续步骤