跳转至

Web 应用接入


通过收集 Web 应用的指标数据,以可视化方式分析应用性能。

前置条件

注意

若已开通 RUM Headless 服务,前置条件已自动配置,可直接接入应用。

开始接入

  1. 进入用户访问监测 > 新建应用 > Web
  2. 输入应用名称;
  3. 输入应用 ID;
  4. 选择应用接入方式:

  5. 公网 DataWay:直接接收 RUM 数据,无需安装 DataKit 采集器。

  6. 本地环境部署:满足前置条件后接收 RUM 数据。

接入方式

  1. 确保 DataKit 已安装并配置为公网可访问,并安装 IP 地理信息库
  2. 在控制台获取 applicationIdenvversion 等参数,开始接入应用
  3. 集成 SDK 时,将 datakitOrigin 设置为 DataKit 的域名或 IP。

  1. 在控制台获取 applicationIdclientTokensite 等参数,开始接入应用
  2. 集成 SDK 时无需配置 datakitOrigin,数据将默认发送到公网 DataWay。

SDK 配置

接入方式
说明
NPM 将 SDK 代码打包到前端项目中,确保前端性能不受影响。可能错过 SDK 初始化前的请求和错误收集。
CDN 异步加载 通过 CDN 异步引入 SDK 脚本,不影响页面加载性能。可能错过初始化前的请求和错误收集。
CDN 同步加载 通过 CDN 同步引入 SDK 脚本,能完整收集所有错误和性能指标。但可能影响页面加载性能。

NPM 接入

在前端项目中安装并引入 SDK:

npm install @cloudcare/browser-rum

在项目中初始化 SDK:

import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum.init({
  applicationId: '<应用 ID>',
  site: 'http://172.16.212.186:9529',
  clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
  env: 'production',
  version: '1.0.0',
  service: 'browser',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  compressIntakeRequests: true,
  trackInteractions: true,
  traceType: 'ddtrace', // 非必填,默认为ddtrace,目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
  allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填,允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin,也可以是是正则
})
datafluxRum.startSessionReplayRecording()

CDN 同步加载

在 HTML 文件中添加脚本:

<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js" type="text/javascript"></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: '<应用 ID>',
      site: 'http://172.16.212.186:9529',
      clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
      env: 'production',
      version: '1.0.0',
      service: 'browser',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: 'ddtrace', // 非必填,默认为ddtrace,目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填,允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin,也可以是是正则
    })
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

CDN 异步加载

在 HTML 文件中添加脚本:

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(window, document, 'script', 'https://static.guance.com/browser-sdk/v3/dataflux-rum.js', 'DATAFLUX_RUM')
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: '<应用 ID>',
      site: 'http://172.16.212.186:9529',
      clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
      env: 'production',
      version: '1.0.0',
      service: 'browser',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: 'ddtrace', // 非必填,默认为ddtrace,目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填,允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin,也可以是是正则
    })
    window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
  })
</script>

参数配置

初始化参数

参数
类型
是否必须
默认值
描述
applicationId String 从观测云创建的应用 ID。
datakitOrigin String DataKit 数据上报 Origin 注释:
协议(包括://),域名(或IP地址)[和端口号]
例如:
https://www.datakit.com
http://100.20.34.3:8088
clientToken String 以 openway 方式上报数据令牌,从观测云控制台获取,必填(公共 openway 方式接入)。
site String 以 公共 openway 方式上报数据地址,从观测云控制台获取,必填(公共 openway 方式接入)。
env String Web 应用当前环境,如 prod:线上环境;gray:灰度环境;pre:预发布环境;common:日常环境;local:本地环境。
version String Web 应用的版本号。
service String 当前应用的服务名称,默认为 browser,支持自定义配置。
sessionSampleRate Number 100 指标数据收集百分比:
100 表示全收集;0 表示不收集。
sessionOnErrorSampleRate Number 0 错误会话补偿采样率:当会话未被 sessionSampleRate 采样时,若会话期间发生错误,则按此比例采集。此类会话将在错误发生时开始记录事件,并持续记录直到会话结束。SDK 版本要求>= 3.2.19
sessionReplaySampleRate Number 100 Session Replay 数据采集百分比:
100 表示全收集;0 表示不收集。
sessionReplayOnErrorSampleRate Number 0 Session Replay 错误会话重放补偿采样率:当会话未被 sessionReplaySampleRate 采样时,若会话期间发生错误,则按此比例采集。此类回放将记录错误发生前最多一分钟的事件,并持续记录直到会话结束。SDK 版本要求>= 3.2.19
trackSessionAcrossSubdomains Boolean false 同一个域名下面的子域名共享缓存。
usePartitionedCrossSiteSessionCookie Boolean false 是否开启分区安全跨站点会话 cookie 详情
useSecureSessionCookie Boolean false 使用安全会话 cookie。这将禁用在不安全(非 HTTPS)连接上发送的 RUM 事件
traceType Enum ddtrace 配置链路追踪工具类型,如果不配置默认为 ddtrace。目前支持 ddtracezipkinskywalking_v3jaegerzipkin_single_headerw3c_traceparent 6 种数据类型。

⚠
1. opentelemetry 支持 zipkin_single_headerw3c_traceparentzipkinjaeger 4 种类型。
2. 该配置的生效需依赖 allowedTracingOrigins 配置项。
3. 配置相应类型的 traceType 需要对相应的 API 服务。关于设置不同的 Access-Control-Allow-Headers,可参考 APM 如何关联 RUM
traceId128Bit Boolean false 是否以 128 字节的方式生成 traceID,与 traceType 对应,目前支持类型 zipkinjaeger
allowedTracingOrigins Array [] 允许注入 trace 采集器所需 header 头部的所有请求列表。可以是请求的 origin,也可以是正则,origin: 协议(包括://),域名(或IP地址)[和端口号]。_例如:
["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/]。*
allowedTracingUrls Array [] 与 Apm 关联请求的 Url 匹配列表。可以是请求的 url,也可以是正则,或者是 match function 例如:["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, function(url) {if (url === 'xxx') { return false} else { return true }}] 该参数是 allowedTracingOrigins 配置的扩展,两者配置其一即可。
trackUserInteractions Boolean false 是否开启用户行为采集。
actionNameAttribute String 版本要求:>3.1.2。 为元素添加自定义属性来指定操作的名称。具体使用方式,详情参考
beforeSend Function(event, context):Boolean 版本要求:>3.1.2。 数据拦截以及数据修改,详情参考
storeContextsToLocal Boolean 版本要求:>3.1.2。是否把用户自定义数据缓存到本地 localstorage,例如: setUser, addGlobalContext api 添加的自定义数据。
storeContextsKey String 版本要求:>3.1.18。定义存储到 localstorage 的 key ,默认不填,自动生成, 该参数主要是为了区分在同一个域名下,不同子路径共用 store 的问题
compressIntakeRequests Boolean 压缩 RUM 数据请求内容,以减少发送大量数据时的带宽使用量,同时能够减少发送数据的请求数量。压缩在 WebWorker 线程中完成。关于 csp 安全策略可参考 csp 安全。SDK 版本要求>= 3.2.0。 datakit 版本要求 >=1.60。部署版要求 >= 1.96.178
workerUrl Sring sessionReplay 和 compressIntakeRequests 数据压缩都是在 webwork 线程中完成,所以默认情况下,在开启 csp 安全访问的情况下,需要允许 worker-src blob:; 该配置允许添加自行托管 worker 地址。关于 csp 安全策略可参考 csp 安全。SDK 版本要求>= 3.2.0
remoteConfiguration Boolean 是否开启数据采集的远程配置功能,默认不开启。 远程配置功能可以在不发布新版本的情况下,动态修改数据采集的配置项。例如:可以在远程配置中修改采样率、是否开启用户行为采集等。远程配置功能需要在观测云控制台中开启环境变量设置。SDK 版本要求>= 3.2.20。datakit 版本要求 >=1.60观测云控制台如何开启环境变量功能

site 参数处理

节点名 地址
中国区 1(杭州) https://rum-openway.guance.com
中国区 2(宁夏) https://aws-openway.guance.com
中国区 4(广州) https://cn4-openway.guance.com
中国区 6(香港) https://cn6-openway.guance.one
海外区 1(俄勒冈) https://us1-openway.guance.com
欧洲区 1(法兰克福) https://eu1-openway.guance.one
亚太区 1(新加坡) https://ap1-openway.guance.one
非洲区 1(南非) https://za1-openway.guance.com
印尼区 1(雅加达) https://id1-openway.guance.com

应用场景

仅采集错误会话事件

前提

SDK 版本要求:3.2.19 以上。

当页面触发错误时,SDK 将自动执行:

  • 持续记录:从错误触发起,完整记录会话全生命周期数据。
  • 精准补偿:通过独立采样通道,确保错误场景无遗漏。

配置方案

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// 核心配置初始化
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({

   ...
   // 精准采集策略
   sessionSampleRate: 0,             // 关闭常规会话采集
   sessionOnErrorSampleRate: 100, // 全量采集错误会话

});

</script>

自定义添加数据 TAG

使用 setGlobalContextPropertysetGlobalContext API 为所有 RUM 事件添加自定义 tag

// 使用setGlobalContextProperty添加单个TAG
window.DATAFLUX_RUM && window.DATAFLUX_RUM.setGlobalContextProperty('userName', '张三')

// 使用setGlobalContext添加多个TAG
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setGlobalContext({
    userAge: 28,
    userGender: '男',
  })

跟踪用户操作

控制是否开启采集 Action

通过 trackUserInteractions 初始化参数控制是否采集用户点击行为。

自定义 Action 名称

  • 通过为可点击元素添加data-guance-action-name属性或data-custom-name(取决于actionNameAttribute配置)来自定义 Action 名称。

使用 addAction API 自定义 Action

// CDN 同步加载
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum &&
  datafluxRum.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })

自定义添加 Error

使用 addError API 自定义添加 Error 指标数据 添加自定义 Error

// CDN 同步加载
const error = new Error('Something wrong occurred.')
window.DATAFLUX_RUM && DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  const error = new Error('Something wrong occurred.')
  window.DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
const error = new Error('Something wrong occurred.')
datafluxRum.addError(error, { pageStatus: 'beta' })

自定义用户标识

使用 setUser API 为当前用户添加标识属性(如 ID、name、email)添加自定义 用户信息

// CDN 同步加载
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
  })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })

Web 会话重放

前提

确保您使用的 SDK 版本支持会话重放功能(通常是 > 3.0.0 版本)。

开启录制

在 SDK 初始化后,调用 startSessionReplayRecording() 方法来开启会话重放的录制。您可以选择在特定条件下开启,如用户登录后 开启会话录制

仅采集错误相关的会话重放数据

前提

SDK 版本要求在 3.2.19 以上。

当页面发生错误时,SDK 将自动执行以下操作:

  • 回溯采集:记录错误前 1 分钟的完整页面快照;
  • 持续录制:从错误发生时起持续记录,直至会话结束;
  • 智能补偿:通过独立采样通道确保错误场景无遗漏。

配置示例

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// 初始化 SDK 核心配置
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   ....

   // 采样策略配置
   sessionSampleRate: 100,          // 全量基础会话采集 (100%)
   sessionReplaySampleRate: 0,       // 关闭常规录屏采样
   sessionReplayOnErrorSampleRate: 100, // 错误场景 100% 采样

});

// 强制开启录屏引擎(必须调用)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

注意事项

  • 会话重放功能不涵盖 iframe、视频、音频和画布元素的播放;
  • 为确保重放时能正常访问静态资源(如字体、图片),可能需要配置 CORS 策略;
  • 确保通过 CSSStyleSheet 接口可访问 CSS 规则,以支持 CSS 样式和鼠标悬停事件。

调试优化

  • 利用 SDK 提供的日志和监控工具进行调试,提升应用性能;
  • 根据业务需求调整 sessionSampleRatesessionReplaySampleRate 参数。

文档评价

文档内容是否对您有帮助? ×