Upgrade Browser SDK V5

Upgrade Datadog Browser SDK to v5

Systematic migration guide from v4 to v5. Follow steps 1-7 in order. Each step includes a search pattern to find affected code.

Step 1: Update SDK version

CDN setup — update script src URLs:

Replace us1 with your site: eu1, us3, us5, ap1. For US1-FED, the pattern is flat with no site prefix: datadog-rum-v5.js, datadog-logs-v5.js, datadog-rum-slim-v5.js. Note: AP2 is not available for v5 — upgrade to v6 first if you need AP2.

Search: grep -r "datadoghq-browser-agent.com.*v4" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

npm setup — update package.json dependencies:

"@datadog/browser-rum": "^5.0.0"
"@datadog/browser-logs": "^5.0.0"
"@datadog/browser-rum-slim": "^5.0.0"

Then run your package manager (npm install, yarn install, etc.) and rebuild.

Also upgrade framework integrations to v5 if used: @datadog/browser-rum-react.

Search: grep -r "@datadog/browser-" --include="package.json" .

Step 2: Replace deprecated init parameters

These v4 parameter names no longer exist in v5. Replace them:

Search: grep -rn 'proxyUrl\|sampleRate\|allowedTracingOrigins\|tracingSampleRate\|trackInteractions\|premiumSampleRate\|replaySampleRate' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Note: sampleRate matches broadly. Look specifically for init config objects — sessionSampleRate is the v5 name for the session sampling rate.

Step 3: Replace deprecated public APIs

These v4 API method names no longer exist in v5:

RUM APIs

Logs APIs

Search: grep -rn 'removeUser\|addRumGlobalContext\|removeRumGlobalContext\|getRumGlobalContext\|setRumGlobalContext\|addLoggerGlobalContext\|removeLoggerGlobalContext\|getLoggerGlobalContext\|setLoggerGlobalContext\|\.addContext\|\.removeContext' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Step 4: Update Session Replay configuration

v5 changes several Session Replay defaults and behaviors:

4a. defaultPrivacyLevel changed to "mask"

In v4, the default was mask-user-input. In v5, all content is masked by default.

To preserve v4 behavior (only mask user input):

DD_RUM.init({
  defaultPrivacyLevel: 'mask-user-input',
})

4b. Recording starts automatically

Sessions sampled for Session Replay are now automatically recorded. You no longer need to call startSessionReplayRecording().

To preserve v4 behavior (manual recording start):

DD_RUM.init({
  startSessionReplayRecordingManually: true,
})

4c. Default sessionReplaySampleRate is now 0

In v4, the default replay sample rate was 100. In v5, it's 0 — no replays unless you set it explicitly.

Action: Ensure sessionReplaySampleRate is explicitly set in your init config:

DD_RUM.init({
  sessionReplaySampleRate: 100, // or your desired rate
})

4d. trackResources and trackLongTasks must be explicit

When using sessionReplaySampleRate (instead of the removed replaySampleRate or premiumSampleRate), resources and long tasks are no longer collected by default. Enable them explicitly — unless the v4 config already set them to false intentionally:

DD_RUM.init({
  sessionReplaySampleRate: 100,
  trackResources: true, // omit if v4 explicitly had trackResources: false
  trackLongTasks: true, // omit if v4 explicitly had trackLongTasks: false
})

Search: grep -rn 'sessionReplaySampleRate\|startSessionReplayRecording\|defaultPrivacyLevel\|trackResources\|trackLongTasks' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Also search for all RUM init calls to catch projects that omit these options and rely on v4 defaults: grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte". For each init call, verify that sessionReplaySampleRate, defaultPrivacyLevel, and trackResources/trackLongTasks are explicitly set.

Step 5: Update changed APIs and behaviors

5a. beforeSend must return a boolean

beforeSend callback functions should return true to keep the event or false to discard it. If no value is returned, the event is kept. This resolves TypeScript compilation errors.

beforeSend: (event, context) => {
  // return true to keep, false to discard
  return true
}

5b. beforeSend action context: context.event → context.events

With frustration signals, an action event can be associated with multiple DOM events. context.event is replaced by context.events (array).

// v4
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvent = context.event
  }
}

// v5
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvents = context.events // array
  }
}

5c. beforeSend performance entry is now a PerformanceEntry object

The performanceEntry in beforeSend context is now the raw PerformanceEntry object, not a JSON representation. The PerformanceEntryRepresentation type has been removed.

5d. startTime removed from XHR beforeSend context

The context.startTime property has been removed from XHR resource beforeSend context. Use the performanceEntry instead.

5e. view.in_foreground_periods removed from beforeSend

This attribute is now computed by the backend. Remove any beforeSend code that accesses view.in_foreground_periods.

5f. Frustration signals collected automatically

Set trackUserInteractions: true to collect all user interactions, including frustration signals. The trackFrustrations parameter is no longer needed.

5g. Resource method names are uppercase

Resource method field is now always uppercase (e.g., GET, POST). Update any dashboards or monitors filtering on resource.method.

5h. session.plan field removed

The session.plan field (lite/premium) is removed in v5 and not emitted on any event type. Replace any dashboard or monitor filter on session.plan with the new replay fields:

• @session.sampled_for_replay:true — session was sampled for Session Replay
• @session.has_replay:true — session has an actual replay recording

Search: grep -rn 'beforeSend\|trackFrustrations\|PerformanceEntryRepresentation\|in_foreground_periods\|context\.event\b\|startTime' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"