Skip to content

Web Application Access

Collect metrics data from web applications to analyze application performance visually.

Prerequisites

Note

If the RUM Headless service has been activated, the prerequisites are automatically configured, and you can directly access the application.

Start Access

  1. Go to RUM > Create Application > Web;
  2. Enter the application name;
  3. Enter the application ID;

  4. Select the application access method:

  5. Public DataWay: Directly receives RUM data without installing the DataKit collector.

  6. Local environment deployment: Receives RUM data after meeting the prerequisites.

Access Methods

  1. Ensure DataKit is installed and configured to be accessible over the public network and install the IP geolocation database;
  2. Obtain parameters like applicationId, env, version, etc., from the console, and start accessing the application;
  3. When integrating the SDK, set datakitOrigin to the domain name or IP of DataKit.
  1. Obtain parameters like applicationId, clientToken, and site from the console, and start accessing the application;
  2. When integrating the SDK, there is no need to configure datakitOrigin; data will be sent to the public DataWay by default.

SDK Configuration

Access Method
 Description
NPM Bundle the SDK code into the front-end project to ensure front-end performance is not affected. May miss requests and error collection before SDK initialization.
CDN Asynchronous Loading Introduce the SDK script asynchronously via CDN without affecting page loading performance. May miss requests and error collection before initialization.
CDN Synchronous Loading Introduce the SDK script synchronously via CDN to completely collect all errors and performance metrics. But may affect page loading performance.

NPM Access

Install and import the SDK in the front-end project:

npm install @cloudcare/browser-rum

Initialize the SDK in the project:

import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.init({
  applicationId: "<Application 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", // Optional, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
  allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, a list of all requests allowed to inject the headers required by the trace collector. Can be the request origin or a regex
})
datafluxRum.startSessionReplayRecording()

CDN Synchronous Loading

Add the script in the HTML file:

<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: "<Application 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", // Optional, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, a list of all requests allowed to inject the headers required by the trace collector. Can be the request origin or a regex
    })
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

CDN Asynchronous Loading

Add the script in the HTML file:

<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: "<Application 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", // Optional, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, a list of all requests allowed to inject the headers required by the trace collector. Can be the request origin or a regex
    })
    window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
  })
</script>

Parameter Configuration

Initialization Parameters

Parameter
Type
Required
Default
 Description
applicationId String Yes Application ID created from the Guance console.
datakitOrigin String Yes DataKit data reporting Origin Note:
Protocol (including ://), domain name (or IP address) [and port number]
For example:
https://www.datakit.com;
http://100.20.34.3:8088.
clientToken String Yes Token for reporting data via openway method, obtained from the Guance console, required (public openway access).
site String Yes Address for reporting data via public openway method, obtained from the Guance console, required (public openway access).
env String No Current environment of the Web application, e.g., prod: production environment; gray: gray environment; pre: pre-release environment; common: daily environment; local: local environment.
version String No Version number of the Web application.
service String No Service name of the current application, defaults to browser, supports custom configuration.
sessionSampleRate Number No 100 Percentage of metric data collection:
100 means full collection; 0 means no collection.
sessionOnErrorSampleRate Number No 0 Error session compensation sampling rate: When a session is not sampled by sessionSampleRate, if an error occurs during the session, it is collected at this rate. Such sessions will start recording events from the time the error occurs and continue until the session ends. SDK version requirement >= 3.2.19
sessionReplaySampleRate Number No 100 Session Replay data collection percentage:
100 means full collection; 0 means no collection.
sessionReplayOnErrorSampleRate Number No 0 Session Replay error session replay compensation sampling rate: When a session is not sampled by sessionReplaySampleRate, if an error occurs during the session, it is collected at this rate. Such replays will record events up to one minute before the error occurs and continue until the session ends. SDK version requirement >= 3.2.19
trackSessionAcrossSubdomains Boolean No false Share cache across subdomains under the same domain name.
usePartitionedCrossSiteSessionCookie Boolean No false Whether to enable partitioned secure cross-site session cookies Details
useSecureSessionCookie Boolean No false Use secure session cookies. This will disable RUM events sent over insecure (non-HTTPS) connections.
traceType Enum No ddtrace Configure the type of tracing tool. If not configured, defaults to ddtrace. Currently supports 6 data types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent.

❗️
1. opentelemetry supports 4 types: zipkin_single_header, w3c_traceparent, zipkin, jaeger.
2. The effectiveness of this configuration depends on the allowedTracingOrigins configuration item.
3. Configuring the corresponding traceType requires corresponding API services. For setting different Access-Control-Allow-Headers, refer to How APM Associates with RUM.
traceId128Bit Boolean No false Whether to generate traceID in 128 bytes, corresponding to traceType, currently supports types zipkin, jaeger.
allowedTracingOrigins Array No [] A list of all requests allowed to inject the headers required by the trace collector. Can be the request origin or a regex, origin: Protocol (including ://), domain name (or IP address) [and port number]. For example:
["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/].*
allowedTracingUrls Array No [] A list of URLs matching requests associated with Apm. Can be the request URL, a regex, or a match function. For example: ["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, function(url) {if (url === 'xxx') { return false} else { return true }}]. This parameter is an extension of the allowedTracingOrigins configuration; either one can be configured.
trackUserInteractions Boolean No false Whether to enable user behavior collection.
actionNameAttribute String No Version requirement: >3.1.2. Add a custom attribute to the element to specify the action name. For specific usage, refer to details.
beforeSend Function(event, context):Boolean No Version requirement: >3.1.2. Data interception and modification, refer to details.
storeContextsToLocal Boolean No Version requirement: >3.1.2. Whether to cache user-defined data to local localstorage, e.g., custom data added by setUser, addGlobalContext APIs.
storeContextsKey String No Version requirement: >3.1.18. Define the key for storage in localstorage. If left blank, it is automatically generated. This parameter is mainly to distinguish the issue of different subpaths sharing the store under the same domain name.
compressIntakeRequests Boolean No Compress RUM data request content to reduce bandwidth usage when sending large amounts of data and reduce the number of data sending requests. Compression is completed in the WebWorker thread. For CSP security policy, refer to CSP security. SDK version requirement >= 3.2.0. datakit version requirement >=1.60. Deployment Plan requirement >= 1.96.178.
workerUrl Sring No Both sessionReplay and compressIntakeRequests data compression are completed in the webwork thread. Therefore, by default, when CSP secure access is enabled, worker-src blob:; needs to be allowed. This configuration allows adding a self-hosted worker address. For CSP security policy, refer to CSP security. SDK version requirement >= 3.2.0.
remoteConfiguration Boolean No Whether to enable the remote configuration function for data collection. Not enabled by default. The remote configuration function can dynamically modify data collection configuration items without releasing a new version. For example, you can modify the sampling rate and whether to enable user behavior collection in the remote configuration. The remote configuration function needs to be enabled in the Guance console environment variable settings. SDK version requirement >= 3.2.20. datakit version requirement >=1.60. How to enable the environment variable function in the Guance console

site Parameter Handling

Node Name Address
China Zone 1 (Hangzhou) https://rum-openway.guance.com
China Zone 2 (Ningxia) https://aws-openway.guance.com
China Zone 4 (Guangzhou) https://cn4-openway.guance.com
China Zone 6 (Hong Kong) https://cn6-openway.guance.one
Overseas Zone 1 (Oregon) https://us1-openway.guance.com
Europe Zone 1 (Frankfurt) https://eu1-openway.guance.one
Asia-Pacific Zone 1 (Singapore) https://ap1-openway.guance.one
Africa Zone 1 (South Africa) https://za1-openway.guance.com
Indonesia Zone 1 (Jakarta) https://id1-openway.guance.com

Application Scenarios

Collect Only Error Session Events

Prerequisite

SDK version requirement: 3.2.19 or above.

When a page triggers an error, the SDK will automatically execute:

  • Continuous recording: Record the full lifecycle data of the session from the moment the error is triggered.
  • Precise compensation: Ensure no error scenarios are missed through an independent sampling channel.

Configuration Example

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Core configuration initialization
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({

   ...
   // Precise collection strategy
   sessionSampleRate: 0,             // Disable regular session collection
   sessionOnErrorSampleRate: 100, // Fully collect error sessions

});

</script>

Data Compression

When collecting a large number of static resources (such as JS, CSS, images, etc.) and enabling full collection, the SDK may generate a lot of data after initialization, causing request backlogs and even affecting the application thread state.

To mitigate this, the following optimization measures can be taken:

  • Delayed reporting: Delay the collection timing through asynchronous methods or NPM access to avoid generating too many requests during the initialization phase.
  • Data compression: Use the zlib algorithm to compress the collected data before reporting, effectively reducing request volume and the number of requests.

Data compression operations are performed in Web Worker and will not block or affect the performance of the browser's main thread.

Configuration Example

Enable compressIntakeRequests: true in the initialization configuration to enable compression:

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
    ...
    compressIntakeRequests: true, // Enable data compression
  });
</script>

Notes

  1. The data compression logic is executed in Web Worker. If CSP security policy is enabled, blob:; needs to be allowed in worker-src. For more information, refer to CSP Security Policy Description.
  2. The SDK supports specifying a self-hosted Worker address through the workerUrl configuration item.
  3. The SDK version required for this feature is >= 3.2.

Custom Adding Data TAGs

Use the setGlobalContextProperty or setGlobalContext API to add custom tags for all RUM events.

// Use setGlobalContextProperty to add a single TAG
window.DATAFLUX_RUM && window.DATAFLUX_RUM.setGlobalContextProperty("userName", "Zhang San")

// Use setGlobalContext to add multiple TAGs
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setGlobalContext({
    userAge: 28,
    userGender: "Male",
  })

Tracking User Operations

Control Whether to Collect Actions

Control whether to collect user click behavior through the trackUserInteractions initialization parameter.

Custom Action Name

  • Customize the Action name by adding the data-guance-action-name attribute or data-custom-name (depending on the actionNameAttribute configuration) to the clickable element.

Use addAction API to Customize Actions

// CDN Synchronous Loading
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.addAction("cart", {
    amount: 42,
    nb_items: 2,
    items: ["socks", "t-shirt"],
  })

// CDN Asynchronous Loading
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"],
  })

Custom Adding Errors

Use the addError API to customize and add Error metric data Add custom Error.

// CDN Synchronous Loading
const error = new Error("Something wrong occurred.")
window.DATAFLUX_RUM && DATAFLUX_RUM.addError(error, { pageStatus: "beta" })

// CDN Asynchronous Loading
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" })

Custom User Identification

Use the setUser API to add identification properties (such as ID, name, email) for the current user Add custom user information.

// CDN Synchronous Loading
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setUser({
    id: "1234",
    name: "John Doe",
    email: "john@doe.com",
  })

// CDN Asynchronous Loading
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 Session Replay

Prerequisite

Ensure the SDK version you are using supports the session replay feature (usually version > 3.0.0).

Start Recording

After initializing the SDK, call the startSessionReplayRecording() method to start recording the session replay. You can choose to start it under specific conditions, such as after the user logs in Start session recording.

Prerequisite

SDK version requirement: 3.2.19 or above.

When an error occurs on the page, the SDK will automatically perform the following operations:

  • Retrospective collection: Record a complete page snapshot from 1 minute before the error;
  • Continuous recording: Continue recording from the moment the error occurs until the session ends;
  • Intelligent compensation: Ensure no error scenarios are missed through an independent sampling channel.

Configuration Example

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Initialize SDK core configuration
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   ....

   // Sampling strategy configuration
   sessionSampleRate: 100,          // Full base session collection (100%)
   sessionReplaySampleRate: 0,       // Disable regular screen recording sampling
   sessionReplayOnErrorSampleRate: 100, // 100% sampling for error scenarios

});

// Force enable the screen recording engine (must call)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Notes

  • The session replay function does not cover iframes, video, audio, and canvas element playback;
  • To ensure static resources (such as fonts, images) are accessible during replay, CORS policy may need to be configured;
  • Ensure CSS rules are accessible through the CSSStyleSheet interface to support CSS styles and mouse hover events.

Debugging and Optimization

  • Use the logs and monitoring tools provided by the SDK for debugging to improve application performance;
  • Adjust the sessionSampleRate and sessionReplaySampleRate parameters according to business needs.

Feedback

Is this page helpful? ×