RUM SDK 高级配置

概述

FlashDuty 真实用户监控（RUM）提供多种高级配置选项，允许您根据需求修改收集的数据和上下文，支持以下场景：

保护敏感数据：屏蔽个人身份信息等敏感数据。

关联用户会话：将用户会话与内部用户标识关联，便于支持和问题排查。

减少数据量：通过采样降低 RUM 数据收集量，优化成本。

增强上下文：为数据添加比默认属性更丰富的上下文信息。

以下章节详细介绍如何实现这些功能。

覆盖默认 RUM 视图名称

FlashDuty RUM 浏览器 SDK 会在用户访问新页面或单页应用（SPA）中 URL 更改时自动生成视图事件。视图名称默认从当前页面 URL 计算，并自动移除变量 ID（包含数字的路径段）。例如，/dashboard/1234 和 /dashboard/9a 会被归一化为 /dashboard/?。

您可以通过设置 trackViewsManually 选项手动跟踪视图事件，并为视图指定自定义名称以及关联的服务和版本。

配置手动跟踪视图

在初始化 FlashDuty RUM SDK 时，设置 trackViewsManually 为 true：

启用手动跟踪后，您需要在每个新页面或路由更改（对于单页应用）时调用 startView 方法以启动视图。RUM 数据将在视图启动时开始收集。您可以为视图及其子事件添加上下文。

参数说明

name（字符串）：视图名称，默认为页面 URL 路径。

service（字符串）：服务名称，默认为创建 RUM 应用时指定的服务。

version（字符串）：应用版本，默认为创建 RUM 应用时指定的版本。

context（对象）：视图的附加上下文，应用于视图及其子事件。

示例：手动跟踪结账页面视图

以下示例在 RUM 应用中手动跟踪结账页面的页面视图，使用 checkout 作为视图名称，并关联 purchase 服务，版本为 1.2.3：

React 路由集成

对于使用 React Router v6 的应用，您可以通过以下步骤覆盖默认视图名称，使其与 React 应用中定义的路由名称一致：

在初始化时设置 trackViewsManually 为 true（如上）。

在路由更改时启动视图，使用 react-router-dom 的 useLocation 和 matchRoutes API。

以下是一个示例：

设置视图名称

使用 setViewName 方法更新当前视图的名称，而无需启动新视图。更改后的视图名称会影响视图及其子事件（从调用时刻起）。

丰富和控制 RUM 数据

FlashDuty RUM 浏览器 SDK 会自动捕获 RUM 事件并填充其主要属性。通过 beforeSend 回调函数，您可以在事件发送到 FlashDuty 之前对其进行拦截和修改，支持以下操作：

丰富事件：添加额外的上下文属性。

修改事件：更改事件内容或屏蔽敏感信息。

丢弃事件：选择性地丢弃特定 RUM 事件。

beforeSend 回调接受两个参数：

event：由 RUM 浏览器 SDK 生成的事件。

context：触发事件创建的上下文。

上下文类型

不同的事件类型对应不同的上下文：

View：Location 对象。

Action：触发事件的 Event 和处理堆栈。

Resource (XHR)：XMLHttpRequest、PerformanceResourceTiming 和处理堆栈。

Resource (Fetch)：Request、Response、PerformanceResourceTiming 和处理堆栈。

Resource (Other)：PerformanceResourceTiming。

Error：Error 对象。

Long Task：PerformanceLongTaskTiming。

丰富 RUM 事件

您可以通过 beforeSend 回调为事件添加上下文属性。例如，为资源事件的响应头添加数据：

您还可以通过全局上下文 API 为事件添加属性。注意：仅 event.context 中的属性会被 RUM SDK 识别。

修改 RUM 事件内容

您可以通过 beforeSend 修改事件内容，例如从视图 URL 中屏蔽电子邮件地址：

可修改的属性

以下属性可以通过 beforeSend 修改：

view.url（字符串）：当前页面的 URL。

view.referrer（字符串）：前一个页面的 URL。

view.name（字符串）：当前视图名称。

view.performance.lcp.resource_url（字符串）：最大内容绘制（LCP）的资源 URL。

service（字符串）：应用的服务名称。

version（字符串）：应用版本。

action.target.name（字符串）：用户交互的元素（仅限自动收集的操作）。

error.message（字符串）：错误消息。

error.stack（字符串）：错误堆栈或补充信息。

error.resource.url（字符串）：触发错误的资源 URL。

resource.url（字符串）：资源 URL。

long_task.scripts.source_url（字符串）：长任务的脚本资源 URL。

long_task.scripts.invoker（字符串）：调用脚本的名称。

context（对象）：通过全局上下文 API、视图上下文 API 或手动生成事件（如 addError、addAction）添加的属性。

其他属性的修改将被忽略。

丢弃 RUM 事件

通过在 beforeSend 中返回 false，可以丢弃特定 RUM 事件（视图事件除外）：

用户会话

通过为 RUM 会话添加用户信息，您可以：

跟踪特定用户的浏览路径。

了解哪些用户受错误影响最大。

监控关键用户的性能。

用户属性

以下为可选的用户属性，建议至少提供一个：

usr.id（字符串）：唯一用户标识符。

usr.name（字符串）：用户友好名称，默认在 RUM UI 中显示。

usr.email（字符串）：用户电子邮件，若无名称则显示邮件。

您还可以添加额外属性，例如用户计划或用户组信息，以增强过滤能力。

用户会话 API

设置用户会话

获取用户会话

添加/覆盖用户属性

删除用户属性

清除用户会话

注意：

用户会话信息更改后，之后的 RUM 事件将包含更新后的信息。

注销（调用 clearUser）后，最后一个视图仍保留用户信息，但后续视图和会话级别数据不会。

采样

默认情况下，FlashDuty RUM 会收集所有会话的数据。您可以通过 sessionSampleRate 参数设置采样率（百分比）来减少收集的会话数量。例如，采集 90% 的会话：

被采样的会话将不收集任何页面视图及其相关遥测数据。

用户跟踪同意

为遵守 GDPR、CCPA 等隐私法规，FlashDuty RUM 允许在初始化时设置用户跟踪同意状态（trackingConsent）。可选值：

"granted"：开始收集数据并发送到 FlashDuty。

"not-granted"：不收集任何数据。

您可以通过 setTrackingConsent API 在初始化后更改同意状态：

从 "granted" 更改为 "not-granted"：停止 RUM 会话，数据不再发送。

从 "not-granted" 更改为 "granted"：如果没有活跃会话，将创建新会话并恢复数据收集。

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

示例：处理用户同意

视图上下文

视图事件的上下文可修改。您可以通过以下 API 为当前视图及其子事件（如操作、错误、计时）添加或修改上下文：

startView：启动视图时指定上下文。

setViewContextProperty：为当前视图添加或修改上下文属性。

setViewContext：替换当前视图的上下文。

示例：添加视图上下文

示例：替换视图上下文

错误上下文

在捕获错误时，您可以通过 dd_context 属性为错误对象附加本地上下文，RUM SDK 会自动将其合并到最终错误事件上下文中。

全局上下文

全局上下文会附加到所有 RUM 事件上，支持以下操作：

添加全局上下文属性：

删除全局上下文属性：

替换全局上下文：

清除全局上下文：

读取全局上下文：

上下文生命周期

默认情况下，全局上下文和用户上下文存储在当前页面内存中，因此：

页面完全刷新后不会保留。

不同标签页或窗口间不共享。

启用 storeContextsAcrossPages 选项可以将上下文存储到 localStorage，支持：

页面刷新后保留上下文。

同一域名下的标签页间同步上下文。

示例：

限制：

不建议在上下文中存储个人身份信息，因为 localStorage 数据会超出用户会话生命周期。

与 trackSessionAcrossSubdomains 选项不兼容，因为 localStorage 仅在同一域名下共享。

localStorage 容量限制为 5 MiB，需确保应用数据、FlashDuty 上下文及其他第三方数据总和在此范围内。

微前端支持

FlashDuty RUM 支持微前端架构，通过堆栈跟踪（stacktrace）机制识别事件来源。您需要从应用文件路径和文件名中提取 service 和 version 属性。

使用方法

在 beforeSend 中根据堆栈信息覆盖 service 和 version 属性：

在 RUM 浏览器中，您可以使用 service 属性过滤事件。

限制

以下事件无法归因于特定来源，因此不包含处理堆栈：

自动收集的操作事件。

非 XHR 和 Fetch 的资源事件。

视图事件（可通过覆盖视图名称解决）。

CORS 和 CSP 违规事件。

集成RUM与分布式追踪

集成 RUM 与分布式追踪，可让您将 Web 和移动应用程序的请求与其对应的后端跟踪关联起来。这种组合让您能够一目了然地查看完整的前端和后端数据。

使用来自 RUM 的前端数据以及来自跟踪 ID 注入的后端、基础设施和日志信息来查明堆栈中任何地方的问题并了解用户的体验。

使用方法

初始化 RUM SDK。使用 allowedTracingUrls 来初始化参数，需配置当前应用的API服务域名。

NPM

CDN同步加载

CDN异步加载

allowedTracingUrls 匹配完整 URL（<scheme>://<host>[:<port>]/<path>[?<query>][#<fragment>]）。它接受以下类型：

String： 匹配任何以该值开头的 URL，例如 https://api.example.com 匹配 https://api.example.com/v1/resource。

RegExp： 使用正则表达式的 test() 方法检查 URL 是否匹配。

Function： 接收 URL 作为参数执行回调函数，当函数返回 true 时表示 URL 匹配成功。

如何关联

分布式追踪协议通过在Header上添加对应的头部字段(traceparent、tracestate)实现，以下是对相应header的说明:

traceparent:[version]-[trace id]-[parent id]-[trace flags]

version: 当前为00

trace id: 128 bits 的trace ID通过16进制处理后变成32个字符

parent id: 64 bits的span ID, 16进制处理后为16个字符

trace flags: 代表是否有降采样, 01代表命中采样，00代表非采样

tracestate: dd=s:[sampling priority]; o:[origin]

sampling priority: 1代表trace被采样

origin: 始终为RUM，代表通过RUM SDK采集

示例：
traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331s-01
tracestate: dd=s:1;o:rum

如何验证

添加配置后，可查看从应用中发送的请求，如能正确携带对应的header则说明配置无误。

📌

如您的http请求涉及到跨域问题，您需要确保请求可通过跨域检测，确保对应的server 有跨域相关配置，支持预检请求请求访问。

注意事项

确保正确配置 applicationId 和 clientToken，以避免数据上传失败。

根据应用需求调整采样率和隐私设置，平衡数据量与合规性。

对于微前端或复杂前端框架，建议在框架路由级别实现 startView 逻辑。

高级配置

概述#

覆盖默认 RUM 视图名称#

配置手动跟踪视图#

参数说明#

示例：手动跟踪结账页面视图#

React 路由集成#

设置视图名称#

丰富和控制 RUM 数据#

上下文类型#

丰富 RUM 事件#

修改 RUM 事件内容#

可修改的属性#

丢弃 RUM 事件#

用户会话#

用户属性#

用户会话 API#

设置用户会话#

获取用户会话#

添加/覆盖用户属性#

删除用户属性#

清除用户会话#

采样#

用户跟踪同意#

示例：处理用户同意#

视图上下文#

示例：添加视图上下文#

示例：替换视图上下文#

错误上下文#

全局上下文#

上下文生命周期#

示例：#

限制：#

微前端支持#

使用方法#

限制#

集成RUM与分布式追踪#

使用方法#

如何关联#

如何验证#

注意事项#

更多信息#

概述

覆盖默认 RUM 视图名称

配置手动跟踪视图

参数说明

示例：手动跟踪结账页面视图

React 路由集成

设置视图名称

丰富和控制 RUM 数据

上下文类型

丰富 RUM 事件

修改 RUM 事件内容

可修改的属性

丢弃 RUM 事件

用户会话

用户属性

用户会话 API

设置用户会话

获取用户会话

添加/覆盖用户属性

删除用户属性

清除用户会话

采样

用户跟踪同意

示例：处理用户同意

视图上下文

示例：添加视图上下文

示例：替换视图上下文

错误上下文

全局上下文

上下文生命周期

示例：

限制：

微前端支持

使用方法

限制

集成RUM与分布式追踪

使用方法

如何关联

如何验证

注意事项

更多信息