Overview

Follow this guide to migrate between major versions of the Browser RUM and Browser Logs SDKs. See the SDK documentation for details on its features and capabilities.

From v4 to v5

V5 introduces the following changes and more:

• New configurations and privacy defaults for Session Replay
• Automatic collection of frustration signals
• Updated performance metrics
• Updated SDK parameters and APIs

Take notice of the below breaking changes as you upgrade your SDK. Changes are grouped by area of impact.

General

SDK initialization parameters

Action to take: Replace the deprecated parameters with the new equivalent parameters in v5. The old parameter names are no longer available in v5.

Public APIs

Action to take: Replace the deprecated APIs with the new equivalent APIs. The old APIs are no longer available in v5.

Intake domains

V5 sends data to different intake domains than previous versions.

Action to take: Update any Content Security Policy (CSP) connect-src entries to use the new domain.

Trusted events

To avoid collecting incorrect or illegitimate data, v5 only listens to events generated by user actions, ignoring events created by scripts. See trusted events for more details.

Action to take: If you rely on any programmatic events and want them to be taken into account by the SDK, add the __ddIsTrusted attribute to them, like below:

const click = new Event('click')
click.__ddIsTrusted = true
document.dispatchEvent(click)

Action to take: If you rely heavily on programmatic events, such as in an automated UI test environment, for example, you can allow all untrusted events by setting allowUntrustedEvents: true.

beforeSend return type

beforeSend callback functions should return a boolean value:

beforeSend(event: any, context?: any) => boolean

The implementation has not changed. If no value is returned, the event is not discarded.

Action to take: Ensure that beforeSend returns true to keep the event and false to discard it. This resolves related TypeScript compilation errors.

Session Replay

Session Replay masking

The default Session Replay masking setting defaultPrivacyLevel has been changed from mask-user-input to mask. This hides all data in Session Replay recordings by default, making recordings less sensitive to view. For more information, see Session Replay Browser Privacy Options.

Action to take: If you want to see more unmasked data in Session Replay, like non-sensitive HTML content or user-entered text, set defaultPrivacyLevel to mask-user-input or allow.

Automatic recording of sessions sampled for Session Replay

Sessions that are sampled for Session Replay using sessionReplaySampleRate are automatically recorded at the start of the session. This means that you don’t have to call the startSessionReplayRecording() method to capture a recording. In other words, you won’t accidentally miss any recordings.

Action to take: If you want to continue using the old recording behavior and customize when your recording starts, set startSessionReplayRecordingManually to true.

Only pay for Session Replay when the session captures a recording

In previous SDK versions, sessions are determined to be Session Replay sessions through the sampling mechanism. In v5, sessions are only counted as Session Replay sessions if a recording is captured during the session. This makes it easier to track your Session Replay usage.

No action needed: This behavior automatically takes effect in v5.

Default Session Replay sampling rate

In v5, the default sessionReplaySampleRate is 0 instead of 100. If you don’t include a sampling rate, no replays are recorded.

Action to take: To use Session Replay, set a sampling rate explicitly with sessionReplaySampleRate: 100 (or another sampling rate).

RUM

APM integration

To promote the support and usage of OpenTelemetry, the default propagator types have been changed to include tracecontext in addition to datadog.

Action to take: If you are not already specifying the desired propagator on the allowedTracingUrls initialization parameter, configure your server Access-Control-Allow-Headers to also accept traceparent header. For more information, see connect RUM and Traces.

Session plan field

In relation to Session Replay changes, the session.plan field is only available for session events.

Action to take: Update any monitor or dashboard queries you have saved to exclude the session.plan field for non-session events.

Frustration signals are collected automatically

You only need to set trackUserInteractions: true to collect all user interactions, including frustration signals. You no longer need to set the trackFrustrations parameter separately.

Action to take: To track frustration signals, set trackUserInteractions: true. The trackFrustrations parameter can be removed.

Resource durations are omitted for frozen pages

Resource collection omits durations of resources that were extended due to the page going into the background, for example, when the user clicks on a separate tab while the page is loading.

No action needed: This behavior automatically takes effect in v5.

Resources and long task tracking

When using sessionReplaySampleRate instead of replaySampleRate or premiumSampleRate (both deprecated), you must configure resources and long tasks explicitly.

Action to take: To collect these events, ensure that trackResources and trackLongTasks are set to true.

Resource method names are in uppercase

In order to avoid having different values for the same method name depending on the case (POST vs post), method names are now consistently sent in uppercase.

Action to take: Update monitor or dashboard queries to use the resource.method field with uppercase values.

beforeSend action event

The beforeSend API allows access to contextual information of the collected events (see Enrich and control RUM data).

With the introduction of frustration signals, an action event can be associated with several DOM events.

Along with this update, the context.event attribute has been removed in favor of the context.events attribute.

Action to take: Update beforeSend code to use context.events instead of context.event.

beforeSend: (event, context) => {
  if (event.type === 'action' && event.action.type === 'click') {
    // accessing browser events related to the action event
    // before, single event: context.event
    // now, multiple events: context.events
  }
}

beforeSend in foreground periods

The view.in_foreground_periods attribute is computed directly from the backend, not sent by the SDK.

Action to take: Remove view.in_foreground_periods from beforeSend code. If you were relying on this attribute for a specific use case, reach out to Support for assistance.

beforeSend performance entry

The beforeSend context performanceEntry attribute has been updated from the JSON representation to include the performance entry object directly.

The exported PerformanceEntryRepresentation type has been removed in favor of the standard PerformanceEntry type.

Action to take: In beforeSend code, use the PerformanceEntry type directly instead of the PerformanceEntryRepresentation type.

Logs

Remove console error prefix

The “console error:” prefix in log messages has been removed. This information can be found in the origin attribute.

Action to take: Update monitor or dashboard queries using the "console error:" prefix to use @origin:console instead.

Remove error.origin

Since the introduction of the origin attribute on all logs, error.origin was redundant and has been removed.

Action to take: Update monitor or dashboard queries using error.origin to use origin instead.

Decouple main logger

When the SDK collects runtime errors or network, report, or console logs, it does not append the context specific to the main logger (DD_LOGS.logger), and it does not use the level or handler set for that logger.

Action to take: If you relied on the main logger level to exclude non-logger logs, use dedicated initialization parameters instead.

Action to take: If you relied on the main logger context to add context to non-logger logs, use global context instead.

From v3 to v4

Several breaking changes were made to the RUM and Logs Browser SDK with the v4 version.

Changes

Intake URLs

The URLs for where the RUM Browser SDK data is sent has changed. Ensure that your Content Security Policy is up to date.

Minimal Typescript version support

The RUM Browser SDK v4 is not compatible with TypeScript earlier than v3.8.2. If you use TypeScript, ensure that the version is at least v3.8.2.

Tags syntax

The version, env, and service initialization parameters are sent as tags to Datadog. The RUM Browser SDK slightly sanitizes them to ensure that they don’t generate multiple tags, and prints a warning if those values don’t meet the tag requirements syntax.

Stricter initialization parameters typing

TypeScript types representing initialization parameters are stricter and may reject previously accepted unsupported parameters. If you get type-checking errors, ensure you are providing supported initialization parameters.

Privacy options precedence

When multiple privacy options are specified on the same element, Datadog applies the most restrictive option to avoid unexpectedly leaking sensitive data. For example, if both dd-privacy-allow and dd-privacy-hidden classes are specified on the same element, it is hidden instead of allowed.

Action names computation

When computing action names, the RUM Browser SDK removes text of child elements with the data-dd-action-name attribute from inner text.

For example, for the following container element, where previously the computed action name would be Container sensitive data, in v4, the computed action name is Container:

<div id="container">
  Container
  <div data-dd-action-name="sensitive">sensitive data</div>
</div>

Removals

XHR _datadog_xhr field

The RUM Browser SDK previously used a _datadog_xhr property on XMLHttpRequest objects representing its internal state. This property has been removed without replacement as it wasn’t intended to be used externally.

proxyHost initialization parameter

The proxyHost initialization parameter has been removed. Use the proxyUrl initialization parameter instead.

Privacy options support

The privacy options input-ignored and input-masked are no longer valid. Instead, use the mask-user-input privacy option.

Specifically, replace:

• dd-privacy-input-ignored and dd-privacy-input-masked class names with dd-privacy-mask-user-input
• dd-privacy="input-masked" and dd-privacy="input-ignored" attribute values with dd-privacy="mask-user-input"

From v2 to v3

The Browser SDK v3 introduces Session Replay. With this major version update, several breaking changes were made to the RUM and Logs Browser SDKs.

Changes

RUM errors

The RUM Browser SDK no longer issues RUM errors for failed XHR and Fetch calls. These failed network requests are still collected as RUM resources, which contain the status code attribute.

To continue seeing the failed network requests as RUM errors, Datadog recommends intercepting the resource with the beforeSend API, checking the status_code property, and manually sending an error with the addError API.

beforeSend: (event) => {
    if (event.type === 'resource' && event.resource.status_code >= 500) {
        datadogRum.addError(`${event.resource.method} ${event.resource.url} ${event.resource.status_code}`); // "GET https://www.example.com/ 504"
    }
}

RUM error source attribute

The RUM Browser SDK no longer lets you specify the source of an error collected with the addError API. All errors collected with this API have their source attribute set to custom. The addError API accepts a context object as its second parameter, which should be used to pass extra context about the error.

Removals

RUM API

Initialization options

TypeScript types

Further Reading

Additional helpful documentation, links, and articles:

Visualize your RUM data in the ExplorerDOCUMENTATION Use Datadog Session Replay to view real-time user journeysBLOG