RUM Setup for Web

The Kloudfuse RUM SDK is available as a package for Web; include the Kloudfuse RUM SDK dependency in your application.

Browser support

The Kloudfuse RUM SDK targets ES2018. Internet Explorer and other browsers that do not support ES2018 are not supported.

Install

To begin instrumenting your frontend application, include the Kloudfuse RUM SDK dependency in your application:

npm install --save kf-browser-sdk

Configure

You must initialize the SDK to begin gathering frontend telemetry. Make this happen as early as possible in your applications loading phase. Customize and include the following code snippet:

import kfuseRumSDK from 'kf-browser-sdk';

kfuseRumSDK.init({
  config: {
    applicationId: '<APPLICATION_ID>',
    clientToken: '<CLIENT_TOKEN>',
    proxy: '<KFUSE_RUM_ENDPOINT>',
    service: '<APPLICATION_NAME>',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    defaultPrivacyLevel: 'mask-user-input',
    enableSessionRecording: true,
    enableLogCollection: true,
  },
});
javascript

The possible configuration options are:

After adding new application to RUM, copy the Integration Code, and use it to specify the applicationId, clientToken, and service. See RUM Applications.
applicationId

A UUID that uniquely identifies a specific frontend application. All RUM telemetry will be associated with it.

clientToken

A token that identifies valid producers of RUM telemetry. You may supply the value dummy if authenticated ingestion is not enabled during Kloudfuse install. When authenticated ingestion is enabled, this value must match one of the configured authentication tokens for RUM. See Enable Authenticated Ingestion.

proxy

The Kloudfuse ingest endpoint for RUM events; its value would be https://<kfuse-public-endpoint>/ddrumproxy.

Your frontend application must not restrict POST requests to this endpoint. Specifically, when using a Content-Securiy-Policy, your frontend application must allow requests to this endpoint.
service

A "friendly" name, unique to the instrumented frontend application.

env

The name that identifies a logical source of RUM events. For example, the test environment or production environment.

version

The string that represents the unique frontend application build, such as 1.0.0.

sessionSampleRate

The percentage of user sessions that generate RUM telemetry; valid range is 0 to 100.

defaultPrivacyLevel

Privacy level for session replays. Can be one of the following three values:

mask

Masks all HTML text, user input, images, links and data-* attributes. Text on your application is replaced with X, rendering the page into a wireframe.

mask-user-input

Masks most form fields: inputs, text areas, and checkbox values, while recording all other text "as is". Inputs are replaced using three asterisks, and text areas are obfuscated using space-preserving x characters.

allow

Records everything unmasked.

enablePrivacyForActionName

When true, action names default to Masked Element unless the element (or a parent) sets data-dd-action-name. Defaults to false. See RUM Action Names.

trackViewsManually

When true, disables automatic view tracking so you can drive view boundaries from your application using kfuseRumSDK.startView(). Defaults to false.

excludedActivityUrls

Array of URL strings or regular expressions. Requests matching an entry are ignored when computing view loading time and "page activity" — useful for excluding polling, analytics beacons, or long-poll endpoints that would otherwise keep views from completing.

allowedTracingUrls

List of URL patterns whose outbound HTTP requests should carry distributed-tracing headers so RUM events can be linked to their backend APM traces. See Trace Linking for the full configuration, including supported propagators.

traceSampleRate

Percentage of traced requests for which the SDK injects propagation headers; valid range is 0 to 100. See Trace Linking.

enableSessionRecording

Controls whether Kloudfuse records the user’s session.

enableLogCollection

Controls whether Kloudfuse collects frontend logs.

beforeSend

Optional callback (event, context) ⇒ boolean invoked before each RUM event is sent. Mutate the event to enrich or scrub it, or return false to discard it. See Modify Event Attributes.

Associate User Information

As soon as your application has access to user information, you can provide that information to the SDK and enrich all generated telemetry.

To do this, add the following code snippet:

kfuseRumSDK.setUser({
  id: "joebarra",
  email: "joe.barra@kloudfuse.com",
})
javascript

Trace Linking

Trace linking lets you pivot from a frontend user session directly to the backend APM trace it generated. It is currently supported only for the Web SDK. See Connect RUM and Traces for how the linkage works and how to view linked traces in the UI.

In your kfuseRumSDK.init({ …​ }) call, add the tracing configuration:

kfuseRumSDK.init({
    config: {
      applicationId: '<APPLICATION_ID>',
      clientToken: '<CLIENT_TOKEN>',
      service: '<APPLICATION_NAME>',
      proxy: 'https://<KLOUDFUSE_ENDPOINT>/ddrumproxy',
      env: 'production',
      version: '1.0.0',
      sessionSampleRate: 100,
      defaultPrivacyLevel: 'mask-user-input',
      enableSessionRecording: true,
      enableLogCollection: true,

      // RUM <-> APM linking
      allowedTracingUrls: [
        { match: /https:\/\/api\.example\.com/, propagatorTypes: ['tracecontext', 'datadog'] },
      ],
      traceSampleRate: 100,
    },
  });
javascript

Also configure a backend APM Agent to read the propagation headers the SDK injects — see APM Instrumentation.

Supported propagators

The Kloudfuse RUM SDK supports multiple trace context propagation formats. Configure the format(s) per URL using the propagatorTypes field on each entry in allowedTracingUrls. The backend tracer must be configured to read at least one of the formats the SDK is injecting for that request, otherwise the trace will not be linked.

Propagator Headers injected Notes

datadog

x-datadog-trace-id, x-datadog-parent-id, x-datadog-sampling-priority, x-datadog-origin

Datadog-native format. Use this when the backend is instrumented with a Datadog (or Datadog-compatible) APM tracer.

tracecontext

traceparent, tracestate

W3C standard. Widely supported by OpenTelemetry and most modern APM tracers.

b3

b3 (single-header form)

Zipkin B3 single-header format.

b3multi

x-b3-traceid, x-b3-spanid, x-b3-sampled, x-b3-parentspanid

Zipkin B3 multi-header format.

all

All of the above, simultaneously

Default in SDK v6. Injects every supported format on each request so any compatible backend can pick the trace up. Costs a few extra request headers.

Redaction and Masking

Data redaction permanently removes sensitive information, making it irretrievable. Data masking temporarily disguises it with fake data for controlled use. Both techniques are vital for cybersecurity, protecting sensitive information and ensuring compliance with data privacy regulations.

Use the following options on the SDK to control the captured data.

PII data may be captured in two places; each have separate approaches for restricting what data to capture:

  • As attributes of RUM events like view.url_path or action.name

  • As visual capture during session recording

The scenarios where PII could appear in RUM Events are:

  • Action names on buttons

  • Names in URLs

  • Sensitive information captured during session recording

RUM Action Names

RUM action names derive from information in the DOM, such as labels and so on.

To control action names, configure enablePrivacyForActionName on RUM SDK. Setting enablePrivacyForActionName to true defaults the action names to Masked Element, unless the element or its parent has a specific DOM attribute data-dd-action-name="My Custom Action Name".

kfuseRumSDK.init({
  config: {
    ...
    enablePrivacyForActionName: true,
  },
});
javascript

Modify Event Attributes

You can modify all events before they leave the browser, by attaching a beforeSend hook. This hook function receives the RUM event object for you to modify as required. For example, if any URL contains PII or ids, you can use this method to sanitize those attributes.

To enable the beforeSend hook, implement the kfuseRumSDK function in your code:

kfuseRumSDK.init({
  config: {
    ...
    beforeSend: function(event, context) {
		if (event.type == "view") { (1)
			event.view.url = removePIIFromURL(event.view.url) (2)
		}
	    return true (3)
    },
  },
});
javascript
1 Add code to modify the event
2 removePIIFromURL: Custom function to remove PII
3 Return true to send the modified event. Return false to drop the event itself.

For more information, see Datadog documentation on Event and context structure.

Redaction in Session Replay

Using this approach ignores the Datadog SDK configuration attribute defaultPrivacyLevel.

To control redaction and masking in session replay, annotate your HTML with one of the RRWeb class names: .rr-block, .rr-ignore, or .rr-mask.

For more information, see RRWeb documentation on Privacy.

RUM redaction covers data captured in the browser. For masking card numbers, credentials, and personal data in server-side logs and traces before they are sent, and for controlling access to what arrives, see Keeping Sensitive Data Out of Kloudfuse.

Upload Source Maps

Source maps help unmangle minified JavaScript files in error stack traces, making debugging easier. Use the Kloudfuse CLI tool to upload source maps for your web application.

Install KF CLI

Install the Kloudfuse CLI tool:

npm install kf-cli

Configure Environment

Set your Kloudfuse API key as an environment variable:

export KF_API_KEY=<a valid kloudfuse RUM application client token>

Usage

Upload source maps using the kf-cli sourcemaps upload command:

kf-cli sourcemaps upload <directory> --baseUrl <base-url> --service <service-name> --release-version <version> --minified-path-prefix <url-prefix>

Options

<directory>

Path to the directory containing your JavaScript source maps (.js.map files).

--baseUrl <url>

Kloudfuse cluster base URL.

--service <service-name>

Name of your frontend service (this should match the service parameter in your kfuse browser SDK initialization call).

--release-version <version>

Version/release identifier for your application build.

--minified-path-prefix <url-prefix>

URL prefix where your minified JavaScript files are served (e.g., https://example.com/static/js or /static/js).

Example

Upload all source maps in the current directory:

kf-cli sourcemaps upload \
  ./dist \
  --service example-app \
  --minified-path-prefix /assets \
  --release-version 1.2.3

This will upload all sourcemap files found in the dist folder and set up the source mapping such that a RUM error event with the attributes service=example-app and version=1.2.3 that has stack frames with a minified js bundle URL such as https://example.com/assets/a.js will reference the sourcemap available at ./dist/a.js.map.