@arms/rum-browser

v0.1.13

Published

25 days ago

arms rum javascript sdk for browser

0High
0Medium
0Low

@arms/rum-browser

阿里云 ARMS 用户体验监控 Web & H5 SDK。覆盖页面 PV、性能（含 Web Vitals）、JS 异常、白屏、API（XHR/Fetch/SSE）、用户交互、视图停留与滚动深度、会话回放等监控数据，并支持分布式链路追踪。

核心特性

零配置即用：一次 init() 后默认启用 PV / 性能 / Web Vitals / 异常 / API / 静态资源 / 点击 / 视图统计 / 白屏等采集器，无需逐项开关
统一上报通道：批量缓冲 + 失败重试，页面隐藏或卸载时自动完成最终上报，BFCache 与移动端切后台不丢数据
API 监控全覆盖：
- XHR / Fetch 全局 patch，自动产出 type='api' 资源事件
- SSE 流式接口（text/event-stream）独立子采集器，输出 time_to_first_token / inter_token_latency_avg / inter_token_latency_max / message_count 等指标
- evaluateApi 回调把请求/响应内容写入 snapshots，SDK 自动裁剪至 5KB
视图维度增强：view-stats 采集器输出页面停留时长（time_spent）、最大滚动深度、离开页面时的窗口尺寸
会话回放：集成 rrweb 录制全量 DOM 与用户交互，支持 mask / user-input / allowlisted 隐私级别，长会话上报体积通过 deflate 压缩 60%~80%
分布式链路追踪：内置 tracing 配置，支持 W3C tracecontext / B3 / B3 multi / Jaeger / SkyWalking sw8 协议，按 allowedUrls 白名单注入 traceparent 等头
远程配置：支持 ARMS 控制台下发配置，动态调整采样率、采集器开关、过滤规则

安装

提供 CDN 异步 / CDN 同步 / NPM 三种接入方式，详见 docs/接入Web&H5应用.md。

npm install @arms/rum-browser

| 依赖 | 版本要求 | 说明 | |------|----------|------| | 浏览器 | Chrome / Safari / Firefox / Edge 最近 2 个大版本 | 不再支持 IE | | @babel/runtime | ^7.24.5 | peerDependency，由业务侧安装 |

接入流程

第一步：在应用入口尽早 import SDK

init() 务必在业务发起任何 XHR / Fetch 请求之前调用——SDK 通过代理 window.fetch / XMLHttpRequest 实现 API 采集，初始化之前发出的请求采不到。

// src/main.ts
import armsRum from '@arms/rum-browser';

armsRum.init({
  endpoint: '<your-endpoint>',
  env: 'prod',
  version: '1.0.0',
});

第二步：CDN 接入（首屏敏感场景推荐）

将以下片段放在 <head> 中尽可能靠前的位置，SDK 异步加载完成后会自动从 window.__rum.config 读取配置启动：

<script>
!(function(c,b,d,a){
  c[a]||(c[a]={});
  c[a].config={
    endpoint: '<your-endpoint>',
    env: 'prod',
    version: '1.0.0',
  };
  with(b)with(body)with(insertBefore(createElement('script'),firstChild))
    setAttribute('crossorigin','',src=d);
})(window,document,'https://sdk.rum.aliyuncs.com/dist/browser-sdk.js','__rum');
</script>

第三步：（可选）验证数据上报

armsRum.init({
  endpoint: '<your-endpoint>',
  beforeReport(bundle) {
    console.log('[RUM]', bundle);
    return bundle;     // 返回 undefined 不会丢弃；如需丢弃需在回调里显式处理
  },
});

第四步：（可选）启用 SPA 路由追踪

单页应用必须显式声明 spaMode，否则路由切换不会被视作新页面：

armsRum.init({
  endpoint: '<your-endpoint>',
  spaMode: 'history',      // 'hash' | 'history' | 'auto' | true | false
});

第五步：（可选）启用会话回放

armsRum.init({
  endpoint: '<your-endpoint>',
  replay: {
    enable: true,
    sampling: 20,                   // 20% 会话录制（百分比，0~100）
    privacy: { level: 'mask' },     // 默认遮蔽所有文本与输入框
  },
});

配置项

init() 接收 IBrowserConfig 配置对象。下表只列出常用字段，完整版见 docs/SDK配置参考.md。

基础配置

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | endpoint | string | 是 | — | ARMS 数据上报地址 | | enable | boolean | 否 | true | 关闭后所有采集器与上报均不工作 | | env | 'prod' \| 'gray' \| 'pre' \| 'daily' \| 'local' \| string | 否 | — | 应用环境标识 | | version | string | 否 | — | 应用版本号 | | app | object | 否 | — | 应用扩展信息（name / channel / framework 等） | | user | object | 否 | — | 用户信息（id / name / tags） |

Web 专属配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | spaMode | false \| true \| 'auto' \| 'hash' \| 'history' | false | SPA 路由追踪模式 | | replay | boolean \| IReplayOption | false | 会话回放配置 | | tracing | boolean \| ITracingOption | — | 分布式链路追踪配置（XHR / Fetch / SSE 共用） | | evaluateApi | (request, response, error?, xhr?) => Promise<IApiAttr> | — | 自定义 API 事件解析回调，返回值由 SDK 裁剪后合并到事件 | | parseViewName | (url: string) => string | — | 自定义页面 name 解析 | | parseResourceName | (url: string) => string | — | 自定义资源 name 解析（默认取 URL pathname） |

采集器开关（collectors）

armsRum.init({
  endpoint: '<your-endpoint>',
  collectors: {
    consoleError: false,             // 关闭 console.error 拦截
    longTask: true,                  // 默认关闭，按需启用
    api: {                           // API 采集器细化配置
      enable: true,
      filters: [/\.internal\.example\.com/],   // 命中则不上报
      xhr: true,
      fetch: true,
      sse: { timeout: 30000 },       // SSE 流 30s 无消息判超时
    },
  },
});

| 采集器 | 默认 | 说明 | |--------|------|------| | jsError | true | 未捕获异常 + 未处理 Promise 拒绝 | | consoleError | true | console.error 拦截上报 | | api | true | XHR + Fetch + SSE 资源事件（type='api'） | | staticResource | true | 静态资源加载（type='resource'） | | perf | true | 页面加载性能 | | webVitals | true | Web Vitals（LCP / FID / CLS） | | click | true | 用户点击事件 | | viewStats | true | 视图停留时长 / 滚动深度（type='view-stats'） | | longTask | false | 长任务（LoAF 优先，降级到 longtask >50ms），按需开启 |

evaluateApi：自定义 payload 写入 snapshots

evaluateApi 用于把请求/响应内容写入事件，SDK 不自动采集 payload——业务侧按需在回调里提取并返回 { snapshots: string }，SDK 自动裁剪至 5KB：

armsRum.init({
  endpoint: '<your-endpoint>',
  async evaluateApi(request, response, error, xhr) {
    const snapshot: Record<string, unknown> = {};
    // Fetch：response.clone().text() 读取
    if (response && typeof (response as Response).text === 'function') {
      try {
        const text = await (response as Response).clone().text();
        snapshot.response = text.slice(0, 1024);
      } catch {}
    }
    // XHR：直接读 xhr.responseText
    if (xhr) snapshot.response = xhr.responseText?.slice(0, 1024);

    return {
      success: error || (response as Response)?.status >= 400 ? 0 : 1,
      snapshots: JSON.stringify(snapshot),
    };
  },
});

字段约定：snapshots 留给 SDK / evaluateApi 写采集元数据，properties 保留给用户业务标签。

链路追踪（tracing）

armsRum.init({
  endpoint: '<your-endpoint>',
  tracing: {
    enable: true,
    sample: 10,                                   // 10% 采样（百分比）
    propagatorTypes: ['tracecontext', 'b3'],
    allowedUrls: [/^https:\/\/api\.example\.com/],  // 仅向白名单注入追踪头
  },
});

| 字段 | 类型 | 说明 | |------|------|------| | enable | boolean | 是否启用链路追踪 | | sample | number | 采样率（0~100，百分比） | | propagatorTypes | Array<'tracecontext' \| 'b3' \| 'b3multi' \| 'jaeger' \| 'sw8'> | 传播协议 | | allowedUrls | Array<MatchOption \| TraceOption> | 允许注入追踪头的 URL/path 规则 | | tracestate / baggage | boolean | 是否携带 W3C tracestate / baggage |

XHR / Fetch / SSE 共用同一份 tracing 决策。allowedUrls 未配置时不会向任何 URL 注入追踪头——避免向第三方域名泄漏内部 traceId。

会话回放（replay）

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enable | boolean | false | 是否启用 | | sampling | number | 100 | 录制采样率（0~100，百分比） | | url | string | — | replay 数据上报地址（不指定则与主上报通道共享） | | privacy.level | 'allow' \| 'mask' \| 'user-input' \| 'allowlisted' | 'mask' | 隐私保护级别 | | privacy.allowlisted | any[] | — | level: 'allowlisted' 时的允许录制元素选择器 |

录制时长上限 单会话录制最长 1 小时，超时自动停止录制。生产环境务必配合 sampling 控制采样率。

运行时 API

import armsRum, { sendEvent } from '@arms/rum-browser';

// 修改单个字段
armsRum.setConfig('enable', false);

// 批量修改
armsRum.setConfig({ env: 'staging', version: '1.1.0' });

// 读取当前完整配置
const config = armsRum.getConfig();

// 获取某个采集器实例（扩展 / 调试用）
const replay = armsRum.getCollector('replay-collector');

// 业务侧自定义事件上报（所有 SDK 实例都会收到）
sendEvent({
  event_type: 'custom',
  type: 'business-event',
  name: 'order-submit',
});

CDN 加载方式下，sendEvent 也可通过全局对象访问：window.RumSDK.sendEvent(event)。

注意事项

init() 务必尽早执行：SDK 通过代理 window.fetch / XMLHttpRequest 实现 API 采集，初始化之前发出的请求采不到。
CDN 异步加载 vs 同步加载：异步加载不阻塞渲染，但 SDK 启动前的早期错误可能漏采；如对早期错误敏感，可在 <head> 顶部加临时 window.onerror / unhandledrejection 缓冲，SDK 启动后通过 RumSDK.sendEvent() 补报。
spaMode 必须与路由实现一致：错配会导致 view 事件采到错误的 path（如把 React BrowserRouter 当成 hash）。
evaluateApi 内禁止同步阻塞：回调如抛错会被静默捕获回退到原始事件；读取大 body 请用流式或限制大小，否则会拖慢上报队列。
replay 会显著增加上报量：生产环境务必配合 sampling 控制采样率；隐私级别默认 'mask' 不要随意调成 'allow'。
tracing.allowedUrls 必须显式声明：未配置时不会注入追踪头，避免向不可控第三方域名泄漏内部 traceId。
longTask 默认关闭：长任务事件量大，按需开启；开启后优先用 LoAF，不支持时降级到 longtask（>50ms）。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@arms/rum-browser

核心特性

安装

接入流程

第一步：在应用入口尽早 import SDK

第二步：CDN 接入（首屏敏感场景推荐）

第三步：（可选）验证数据上报

第四步：（可选）启用 SPA 路由追踪

第五步：（可选）启用会话回放

配置项

基础配置

Web 专属配置

采集器开关（collectors）

evaluateApi：自定义 payload 写入 snapshots

链路追踪（tracing）

会话回放（replay）

运行时 API

注意事项