Skip to content

Web Application Access

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

Prerequisites (Datakit Access)

Start Access

  1. Go to RUM > Create > Web.
  2. Enter the application name.
  3. Enter the application ID.
  4. Choose the application access method:
  5. Public DataWay: Directly receives RUM data without installing a DataKit collector.
  6. Local environment deployment: Receives RUM data after meeting the prerequisites.

Access Methods

  1. Ensure DataKit is installed and configured to be publicly accessible, with the IP geolocation database installed.
  2. Obtain parameters like applicationId, env, version from the console, and start accessing the application.
  3. When integrating the SDK, set datakitOrigin to the DataKit's domain name or IP.
  1. Obtain parameters like applicationId, clientToken, and site from the console, and start accessing the application.
  2. No need to configure datakitOrigin when integrating the SDK; 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 errors before SDK initialization.
CDN Asynchronous Loading Asynchronously load the SDK script via CDN, not affecting page loading performance. May miss requests and errors before initialization.
CDN Synchronous Loading Synchronously load the SDK script via CDN, enabling complete collection of all errors and performance metrics. 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 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types.
  allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject headers required by the trace collector. Can be request origins or 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 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types.
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject headers required by the trace collector. Can be request origins or 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 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types.
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject headers required by the trace collector. Can be request origins or 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 Guance.
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, obtained from the Guance console, required (public openway access).
site String Yes Address for reporting data via public openway, 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.
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 trace tool type. If not configured, defaults to ddtrace. Currently supports ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 data types.

❗️
1. opentelemetry supports zipkin_single_header, w3c_traceparent, zipkin, jaeger 4 types.
2. This configuration takes effect depending on the allowedTracingOrigins configuration.
3. Configuring the corresponding traceType requires corresponding API services. For setting different Access-Control-Allow-Headers, refer to APM How to Associate RUM.
traceId128Bit Boolean No false Whether to generate traceID in 128 bytes, corresponding to traceType, currently supports types zipkin, jaeger.
allowedTracingOrigins Array No [] List of all requests allowed to inject headers required by the trace collector. Can be request origins or 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 [] Url matching list for requests associated with Apm. Can be request urls, regex, or 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 interaction collection.
actionNameAttribute String No Version requirement: >3.1.2. Add custom attributes to elements to specify action names. 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, defaults to auto-generated if not filled. This parameter is mainly to distinguish shared store issues under the same domain with different sub-paths.
compressIntakeRequests Boolean No Compress RUM data request content to reduce bandwidth usage when sending large amounts of data, while also reducing the number of data sending requests. Compression is done in the WebWorker thread. For csp security policy refer to csp security. SDK version requirement >= 3.2.0. datakit version requirement >=1.60. Deployment version requirement >= 1.96.178.
workerUrl Sring No sessionReplay and compressIntakeRequests data compression are both done in the webwork thread, so by default, when csp secure access is enabled, worker-src blob:; needs to be allowed. This configuration allows adding self-hosted worker addresses. For csp security policy refer to csp security. SDK version requirement >= 3.2.0.
remoteConfiguration Boolean No Whether to enable remote configuration for data collection, defaults to off. Remote configuration allows dynamically modifying data collection configuration items without releasing a new version. For example, sampling rate, whether to enable user interaction collection, etc., can be modified in remote configuration. Remote configuration 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 environment variable function in 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 time 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, // Full collection of 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 backlog 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 number.

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. 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 Explanation.
  2. The SDK supports specifying a self-hosted Worker address through the workerUrl configuration item.
  3. The SDK version using this feature needs to be >= 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 Names

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

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 custom 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 versions > 3.0.0).

Start Recording

After initializing the SDK, call the startSessionReplayRecording() method to start session replay recording. You can choose to start it under specific conditions, such as after user login 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 time 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) can be accessed normally during replay, CORS policy may need to be configured.
  • Ensure CSS rules are accessible via 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? ×