RUM SDK Advanced Configuration

Overview

Flashduty Real User Monitoring (RUM) offers various advanced configuration options that allow you to modify collected data and context based on your requirements, supporting the following scenarios:

Protect sensitive data: Mask personally identifiable information and other sensitive data.

Associate user sessions: Link user sessions with internal user identifiers for support and troubleshooting.

Reduce data volume: Lower RUM data collection through sampling to optimize costs.

Enhance context: Add richer contextual information to data beyond default attributes.

The following sections detail how to implement these capabilities.

Override Default RUM View Names

The Flashduty RUM browser SDK automatically generates view events when users visit new pages or when URLs change in single-page applications (SPAs). View names are calculated from the current page URL by default and automatically remove variable IDs (path segments containing numbers). For example, /dashboard/1234 and /dashboard/9a are normalized to /dashboard/?.

You can manually track view events by setting the trackViewsManually option and specify custom names for views along with their associated services and versions.

Configure Manual View Tracking

When initializing the Flashduty RUM SDK, set trackViewsManually to true:

After enabling manual tracking, you need to call the startView method on each new page or route change (for single-page applications) to start a view. RUM data will begin collecting when the view starts. You can add context to the view and its child events.

Parameter Description

name (string): View name, defaults to the page URL path.

service (string): Service name, defaults to the service specified when creating the RUM application.

version (string): Application version, defaults to the version specified when creating the RUM application.

context (object): Additional context for the view, applied to the view and its child events.

Example: Manually Track Checkout Page View

The following example manually tracks a checkout page view in a RUM application, using checkout as the view name and associating it with the purchase service, version 1.2.3:

React Router Integration

For applications using React Router v6, you can override default view names to match route names defined in your React application through the following steps:

Set trackViewsManually to true during initialization (as shown above).

Start views on route changes using the useLocation and matchRoutes APIs from react-router-dom.

Here's an example:

Set View Name

Use the setViewName method to update the current view's name without starting a new view. The changed view name affects the view and its child events (from the moment of the call onwards).

Enrich and Control RUM Data

The Flashduty RUM browser SDK automatically captures RUM events and populates their main attributes. Through the beforeSend callback function, you can intercept and modify events before they are sent to Flashduty, supporting the following operations:

Enrich events: Add additional context attributes.

Modify events: Change event content or mask sensitive information.

Discard events: Selectively discard specific RUM events.

The beforeSend callback accepts two parameters:

event: The event generated by the RUM browser SDK.

context: The context that triggered the event creation.

Context Types

Different event types correspond to different contexts:

View: Location object.

Action: The triggering Event and handling stack.

Resource (XHR): XMLHttpRequest, PerformanceResourceTiming, and handling stack.

Resource (Fetch): Request, Response, PerformanceResourceTiming, and handling stack.

Resource (Other): PerformanceResourceTiming.

Error: Error object.

Long Task: PerformanceLongTaskTiming.

Enrich RUM Events

You can add context attributes to events through the beforeSend callback. For example, adding data from response headers to resource events:

You can also add attributes to events through the global context API. Note: Only attributes in event.context will be recognized by the RUM SDK.

Modify RUM Event Content

You can modify event content through beforeSend, for example, masking email addresses from view URLs:

Modifiable Attributes

The following attributes can be modified through beforeSend:

view.url (string): Current page URL.

view.referrer (string): Previous page URL.

view.name (string): Current view name.

view.performance.lcp.resource_url (string): Resource URL for Largest Contentful Paint (LCP).

service (string): Application service name.

version (string): Application version.

action.target.name (string): Element involved in user interaction (for automatically collected actions only).

error.message (string): Error message.

error.stack (string): Error stack or supplementary information.

error.resource.url (string): Resource URL that triggered the error.

resource.url (string): Resource URL.

long_task.scripts.source_url (string): Script resource URL for long tasks.

long_task.scripts.invoker (string): Name of the invoking script.

context (object): Attributes added through global context API, view context API, or manually generated events (such as addError, addAction).

Modifications to other attributes will be ignored.

Discard RUM Events

By returning false in beforeSend, you can discard specific RUM events (except view events):

User Sessions

By adding user information to RUM sessions, you can:

Track browsing paths of specific users.

Understand which users are most affected by errors.

Monitor performance for key users.

User Attributes

The following are optional user attributes, with at least one recommended:

usr.id (string): Unique user identifier.

usr.name (string): User-friendly name, displayed by default in the RUM UI.

usr.email (string): User email, displayed if no name is provided.

You can also add additional attributes, such as user plan or user group information, to enhance filtering capabilities.

User Session API

Set User Session

Get User Session

Add/Override User Attributes

Remove User Attributes

Clear User Session

Note:

After user session information changes, subsequent RUM events will include the updated information.

After logout (calling clearUser), the last view will still retain user information, but subsequent views and session-level data will not.

Sampling

By default, Flashduty RUM collects data for all sessions. You can use the sessionSampleRate parameter to set a sampling rate (percentage) to reduce the number of sessions collected. For example, to collect 90% of sessions:

Sampled sessions will not collect any page views and their related telemetry data.

To comply with privacy regulations such as GDPR and CCPA, Flashduty RUM allows setting user tracking consent status (trackingConsent) during initialization. Available values:

"granted": Begin collecting data and sending it to Flashduty.

"not-granted": Do not collect any data.

You can change the consent status after initialization using the setTrackingConsent API:

Changing from "granted" to "not-granted": Stops the RUM session, and data is no longer sent.

Changing from "not-granted" to "granted": If there is no active session, a new session will be created and data collection resumes.

Note: Consent status is not synchronized between tabs or persisted; you need to provide the user's decision during initialization or through setTrackingConsent.

View Context

View event context can be modified. You can add or modify context for the current view and its child events (such as actions, errors, timings) through the following APIs:

startView: Specify context when starting a view.

setViewContextProperty: Add or modify a context property for the current view.

setViewContext: Replace the context for the current view.

Example: Add View Context

Example: Replace View Context

Error Context

When capturing errors, you can attach local context to error objects through the dd_context attribute, and the RUM SDK will automatically merge it into the final error event context.

Global Context

Global context is attached to all RUM events and supports the following operations:

Add global context attribute:

Remove global context attribute:

Replace global context:

Clear global context:

Read global context:

Context Lifecycle

By default, global context and user context are stored in the current page memory, therefore:

They are not retained after a complete page refresh.

They are not shared between different tabs or windows.

Enabling the storeContextsAcrossPages option stores context in localStorage, supporting:

Context retention after page refresh.

Context synchronization between tabs under the same domain.

Example:

Limitations:

It is not recommended to store personally identifiable information in context, as localStorage data exceeds the user session lifecycle.

Not compatible with the trackSessionAcrossSubdomains option, as localStorage is only shared within the same domain.

localStorage capacity is limited to 5 MiB, so ensure that the total of application data, Flashduty context, and other third-party data remains within this range.

Micro-frontend Support

Flashduty RUM supports micro-frontend architecture by identifying event sources through stacktrace mechanism. You need to extract service and version attributes from application file paths and filenames.

Usage

Override service and version attributes in beforeSend based on stack information:

In the RUM browser, you can filter events using the service attribute.

Limitations

The following events cannot be attributed to specific sources and therefore do not contain handling stacks:

Automatically collected action events.

Resource events other than XHR and Fetch.

View events (can be resolved by overriding view names).

CORS and CSP violation events.

Integrate RUM with Distributed Tracing

Integrating RUM with distributed tracing allows you to correlate requests from your web and mobile applications with their corresponding backend traces. This combination enables you to view complete frontend and backend data at a glance.

Use frontend data from RUM along with backend, infrastructure, and log information from trace ID injection to identify issues anywhere in your stack and understand user experience.

Usage

Initialize the RUM SDK. Configure the allowedTracingUrls initialization parameter with the list of internal first-party origins called by your browser application.

allowedTracingUrls matches the complete URL (<scheme>://<host>[:<port>]/<path>[?<query>][#<fragment>]). It accepts the following types:

String: Matches any URL that starts with this value, for example https://api.example.com matches https://api.example.com/v1/resource.

RegExp: Uses the regex test() method to check if the URL matches.

Function: Accepts the URL as a parameter and executes the callback function, returning true indicates a successful URL match.

Considerations

Ensure correct configuration of applicationId and clientToken to avoid data upload failures.

Adjust sampling rate and privacy settings according to application requirements, balancing data volume with compliance.

For micro-frontends or complex frontend frameworks, it is recommended to implement startView logic at the framework routing level.

More Information

For more detailed information about Flashduty RUM, please visit Flashduty SDK.

Advanced Configuration

Overview#

Override Default RUM View Names#

Configure Manual View Tracking#

Parameter Description#

Example: Manually Track Checkout Page View#

React Router Integration#

Set View Name#

Enrich and Control RUM Data#

Context Types#

Enrich RUM Events#

Modify RUM Event Content#

Modifiable Attributes#

Discard RUM Events#

User Sessions#

User Attributes#

User Session API#

Set User Session#

Get User Session#

Add/Override User Attributes#

Remove User Attributes#

Clear User Session#

Sampling#

User Tracking Consent#

Example: Handling User Consent#

View Context#

Example: Add View Context#

Example: Replace View Context#

Error Context#

Global Context#

Context Lifecycle#

Example:#

Limitations:#

Micro-frontend Support#

Usage#

Limitations#

Integrate RUM with Distributed Tracing#

Usage#

Considerations#

More Information#

Overview

Override Default RUM View Names

Configure Manual View Tracking

Parameter Description

Example: Manually Track Checkout Page View

React Router Integration

Set View Name

Enrich and Control RUM Data

Context Types

Enrich RUM Events

Modify RUM Event Content

Modifiable Attributes

Discard RUM Events

User Sessions

User Attributes

User Session API

Set User Session

Get User Session

Add/Override User Attributes

Remove User Attributes

Clear User Session

Sampling

User Tracking Consent

Example: Handling User Consent

View Context

Example: Add View Context

Example: Replace View Context

Error Context

Global Context

Context Lifecycle

Example:

Limitations:

Micro-frontend Support

Usage

Limitations

Integrate RUM with Distributed Tracing

Usage

Considerations

More Information