跳转到主要内容
完成 SDK 接入后,按需配置视图、上下文、采样和分布式追踪。下方初始化示例可合并到您已有的 flashcatRum.init() 配置中。

覆盖默认 RUM 视图名称

RUM 在页面访问或 SPA 地址变化时自动创建视图,并把含数字的路径段归一化为 ?。例如 /dashboard/1234 和 /dashboard/9a 的默认视图名都是 /dashboard/?。需要按路由划分视图时,启用手动视图跟踪;只改名称时用 setViewName()。

配置手动跟踪视图

1

启用手动跟踪

在初始化时设置 trackViewsManually 为 true:
rum-init.js
2

调用 startView 方法

在每个新页面或路由更改时调用 startView 方法:

React Router 集成

RumTracker.jsx

设置视图名称

使用 setViewName 方法更新当前视图的名称,而无需启动新视图:

控制首屏 Web Vitals 采集

trackWebVitals 默认为 true,采集首个视图的 FCP、LCP、FID 和加载时间。预渲染、后台标签页或宿主提前加载的页面,这些值可能偏大,不需要时设为 false。资源、长任务、用户行为、错误和后续视图不受影响。
rum-init.js

丰富和控制 RUM 数据

使用 beforeSend(event, context) 在上报前添加上下文、修改允许的字段,或返回 false 丢弃事件。回调是同步的,不等待 Promise。

上下文类型

第二个参数 context 提供触发事件的浏览器对象:

上下文大小限制

自定义字段(包括 res、req)共享 context 预算。字符数不等于 UTF-8 字节数;不要将 256 KiB 当作响应体额度,也不要依赖压缩扩大采集范围。
请求体和响应体能否写进 event.context,取决于请求类型和 body 形态。两者都只能在同步的 beforeSend 中完成:

为资源事件添加响应头

Fetch 与 XHR 都可在 beforeSend 中同步读取响应头,把需要的字段写入 event.context。请按请求类型查看对应页签。
通过 context.response.headers 读取全部响应头,或用 headers.get(name) 读取单个响应头:
上报后,在查看器中打开该资源事件,详情中可看到 context.responseHeaders:
查看器资源详情页,属性区 context 字段显示上报的 responseHeaders 响应头数据

查看器的资源详情

将接口响应体作为资源上下文上报

在 beforeSend 中读取响应,将需要的字段写入 event.context.res。res 是自定义字段,SDK 不会自动采集响应体。XHR 与 Fetch 的情况不同,请按请求类型查看对应页签。
请求完成时,XHR 的 JSON 或 JSON 文本响应可通过 xhr.response 同步读取。按接口路径筛选请求:
XHR 的 Blob 响应需要异步读取,不在此示例范围内。
XHR 上报后,在查看器的资源详情中可看到 context.res:
资源详情的 JSON 视图中,红框标出包含 res 响应数据的 context 字段

查看器的资源详情

将接口请求体作为资源上下文上报

请求体是前端发出的内容,与响应体无关。能否取得取决于请求类型,请按请求类型查看对应页签。SDK 不会自动采集请求体。
仅当请求以 fetch(url, { body }) 发出、且 body 是字符串时,请求体保留在 beforeSend 第二个参数的 context.requestInit.body 中,可同步解析后把需要的字段写入 event.context(例如 req)。这是 SDK 透传原始调用参数供用户自行提取。
URLSearchParams 可先用 Object.fromEntries(body.entries()) 转换;fetch(new Request(...))、Blob、文件或流,都无法同步取得请求体。上报后,在查看器中打开该资源事件,详情中可看到 context.req:
查看器资源详情页,属性区 context 字段显示从 Fetch 请求体提取的 req 数据

查看器的资源详情

修改 RUM 事件内容

例如,从视图 URL 中屏蔽电子邮件地址:

可修改的属性

丢弃 RUM 事件

通过在 beforeSend 中返回 false,可以丢弃特定 RUM 事件:
视图事件无法被丢弃。

用户会话

设置用户标识后,您可以在 RUM 中关联同一用户的会话和错误。

用户属性

以下属性均可选,建议至少设置一项:

用户会话 API

用户会话信息更改后,之后的 RUM 事件将包含更新后的信息。注销(调用 clearUser)后,最后一个视图仍保留用户信息,但后续视图和会话级别数据不会。

采样

使用 sessionSampleRate 设置会话采样百分比,默认 100。例如,以下配置采集 90% 的会话:
未被普通采样抽中的会话默认不上报;开启下方异常补采后,可在报错时补报。

异常会话补采

需要 Web SDK 0.3.0 及以上。以下两个选项默认均为 false,只补采对应采样率未抽中的会话或回放。已抽中的会话保持正常采集。 例如,保留 20% 的普通会话,并补采其余会话中的异常会话及回放:
  • 未抽中的候选数据先缓存在内存中,首次符合条件的错误触发补报。最多回溯一分钟,不保证完整保留,也无法恢复 SDK 初始化或录制开始前的数据。
  • 只有 RUM 错误事件触发补采,例如 JavaScript 错误或 addError()。被 beforeSend 丢弃、被限流或 SDK 自身的错误不触发;失败请求和 HTTP 5xx 资源事件也不触发。
  • sessionOnError 候选会话始终未报错时,事件和回放不上传、不计费。仅开启 sessionReplayOnError 时,无错误的候选回放不上传、不计费;普通采样已抽中的 RUM 会话仍正常上报和计费。
  • 同一会话只计一次,不因重复报错重复计数。异常补采会话按实际数量统计,不按 1 / sessionSampleRate 放大。
sessionSampleRate: 100 时,sessionOnError 没有额外作用;sessionReplaySampleRate: 100 时,sessionReplayOnError 没有额外作用。sessionSampleRate: 0 且未开启 sessionOnError 时,仅开启 sessionReplayOnError 也不会采集任何会话。若只想保留异常会话及回放,可将两个采样率都设为 0,同时开启两个补采开关。

已知限制

两个开关也可以通过远程配置调整。

远程配置

需要 Web SDK 0.4.0 及以上。设置 remoteConfigurationEnabled: true(默认 false),可使用控制台发布的采样、回放、隐私和自定义配置覆盖初始化值。新配置对下一个新会话生效,支持项与发布步骤见应用管理。

用户跟踪同意

需要先获得用户同意时,将 trackingConsent 初始化为 "not-granted",同意后调用 setTrackingConsent("granted"):

示例:处理用户同意

同意状态不会在标签页间同步或持久化,您需要在初始化或通过 setTrackingConsent 提供用户决定。

视图上下文

以下 API 为当前视图及其子事件添加或修改上下文:

错误上下文

捕获错误时,可通过 dd_context 属性为错误对象附加上下文:

全局上下文

全局上下文会附加到所有事件:

上下文生命周期

全局上下文和用户信息默认不跨页面刷新保留,也不在标签页间共享。设置 storeContextsAcrossPages: true 可将其保存到 localStorage:
  • 不建议在上下文中存储个人身份信息,因为 localStorage 数据会超出用户会话生命周期
  • 与 trackSessionAcrossSubdomains 选项不兼容
  • localStorage 容量限制为 5 MiB

微前端支持

在 beforeSend 中按事件的调用堆栈设置 service 和 version,区分微前端应用:
以下事件无法归因于特定来源:自动收集的操作事件、非 XHR/Fetch 的资源事件、视图事件、CORS 和 CSP 违规事件。

集成 RUM 与分布式追踪

配置 allowedTracingUrls 后,SDK 会为匹配的请求注入追踪头,把浏览器请求与后端 Trace 关联起来。

使用方法

把当前应用的 API 域名填入 allowedTracingUrls:
CDN 接入使用相同的初始化参数,加载方式见 SDK 接入指南。 allowedTracingUrls 匹配完整 URL,接受以下类型:

追踪协议

SDK 在匹配的请求上添加 traceparent 和 tracestate 请求头,字段含义与示例见 分布式追踪。

如何验证

在浏览器 Network 面板检查匹配请求是否携带 traceparent 和 tracestate 追踪头。
分布式追踪验证
跨域请求需确保服务端允许跨域,并能处理预检请求。

相关文档

SDK 接入指南

了解如何快速接入 RUM SDK

数据收集

了解 SDK 收集的数据类型和属性

问题排查

解决常见问题和调试技巧
SDK 源码与版本见 Flashduty SDK GitHub 仓库。