name	upgrade-browser-sdk-v5
description	Use when upgrading Datadog Browser SDK from v4 to v5, when encountering removed options like proxyUrl, sampleRate, replaySampleRate, premiumSampleRate, allowedTracingOrigins, or deprecated APIs like addRumGlobalContext, removeUser

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:

v4 pattern	v5 replacement
`datadoghq-browser-agent.com/us1/v4/datadog-rum.js`	`datadoghq-browser-agent.com/us1/v5/datadog-rum.js`
`datadoghq-browser-agent.com/us1/v4/datadog-logs.js`	`datadoghq-browser-agent.com/us1/v5/datadog-logs.js`
`datadoghq-browser-agent.com/us1/v4/datadog-rum-slim.js`	`datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js`

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:

Deprecated parameter (v4)	Replacement (v5)
`proxyUrl`	`proxy`
`sampleRate`	`sessionSampleRate`
`allowedTracingOrigins`	`allowedTracingUrls`
`tracingSampleRate`	`traceSampleRate`
`trackInteractions`	`trackUserInteractions`
`premiumSampleRate`	`sessionReplaySampleRate`
`replaySampleRate`	`sessionReplaySampleRate`

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

Deprecated API (v4)	Replacement (v5)
`DD_RUM.removeUser`	`DD_RUM.clearUser`
`DD_RUM.addRumGlobalContext`	`DD_RUM.setGlobalContextProperty`
`DD_RUM.removeRumGlobalContext`	`DD_RUM.removeGlobalContextProperty`
`DD_RUM.getRumGlobalContext`	`DD_RUM.getGlobalContext`
`DD_RUM.setRumGlobalContext`	`DD_RUM.setGlobalContext`

Logs APIs

Deprecated API (v4)	Replacement (v5)
`DD_LOGS.addLoggerGlobalContext`	`DD_LOGS.setGlobalContextProperty`
`DD_LOGS.removeLoggerGlobalContext`	`DD_LOGS.removeGlobalContextProperty`
`DD_LOGS.getLoggerGlobalContext`	`DD_LOGS.getGlobalContext`
`DD_LOGS.setLoggerGlobalContext`	`DD_LOGS.setGlobalContext`
`logger.addContext`	`logger.setContextProperty`
`logger.removeContext`	`logger.removeContextProperty`

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. You must enable them explicitly:

DD_RUM.init({
  sessionReplaySampleRate: 100,
  trackResources: true,
  trackLongTasks: true,
})

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

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"

Step 6: Handle trusted events

v5 only listens to user-generated (trusted) events. Script-generated events are ignored by default.

If you rely on programmatic events (e.g., dispatchEvent), add the __ddIsTrusted attribute:

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

// TypeScript
const click = new Event('click') as Event & { __ddIsTrusted?: boolean }
click.__ddIsTrusted = true
document.dispatchEvent(click)

Or allow all untrusted events globally:

DD_RUM.init({
  allowUntrustedEvents: true,
})

Search: grep -rn 'dispatchEvent\|new Event\|new MouseEvent\|new KeyboardEvent\|\.click()' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Step 7: Update infrastructure

CSP `connect-src` domains changed

v5 sends data to new intake domains. Update your Content Security Policy:

Datadog site	New `connect-src` domain
US1	`https://browser-intake-datadoghq.com`
US3	`https://browser-intake-us3-datadoghq.com`
US5	`https://browser-intake-us5-datadoghq.com`
EU1	`https://browser-intake-datadoghq.eu`
US1-FED	`https://browser-intake-ddog-gov.com`
US2-FED	`https://browser-intake-us2-ddog-gov.com`
AP1	`https://browser-intake-ap1-datadoghq.com`

CORS headers for distributed tracing

v5 adds tracecontext as a default propagator. If you use allowedTracingUrls, your server must accept the traceparent header. Add it to your existing Access-Control-Allow-Headers — do not replace the full list:

# Add traceparent alongside your existing headers
Access-Control-Allow-Headers: <existing-headers>, traceparent

Logs: `error.origin` removed

Update dashboards/monitors using error.origin to use origin instead.

Logs: console error prefix removed

The "console error:" prefix is removed from log messages. Update queries using this prefix to use @origin:console instead.

Logs: main logger decoupled

Runtime errors, network logs, report logs, and console logs no longer inherit the main logger's context, level, or handler. Use global context and dedicated init parameters instead.

Common Mistakes

Mistake	What goes wrong	Fix
Setting `sessionReplaySampleRate > 0` without enabling `trackResources` and `trackLongTasks`	Resources and long tasks are silently not collected — they no longer default to `true` when using `sessionReplaySampleRate`	Always add `trackResources: true, trackLongTasks: true` alongside any non-zero `sessionReplaySampleRate`
Using `context.event` instead of `context.events` in `beforeSend` for action events	Action context property renamed — `context.event` is `undefined`, DOM event details are lost	Update to `context.events` (array); iterate if you need all associated DOM events
Not updating CSP `connect-src` to the new v5 intake domains	SDK silently fails to send data — old intake domains are no longer valid	Update `connect-src` to the v5 intake domain for your site (see Step 7)

Verification checklist

After upgrading, confirm:

Navigation Menu

Uh oh!

Upgrade Datadog Browser SDK to v5

Step 1: Update SDK version

Step 2: Replace deprecated init parameters

Step 3: Replace deprecated public APIs

RUM APIs

Logs APIs

Step 4: Update Session Replay configuration

4a. `defaultPrivacyLevel` changed to `"mask"`

4b. Recording starts automatically

4c. Default `sessionReplaySampleRate` is now `0`

4d. `trackResources` and `trackLongTasks` must be explicit

Step 5: Update changed APIs and behaviors

5a. `beforeSend` must return a boolean

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

5c. `beforeSend` performance entry is now a `PerformanceEntry` object

5d. `startTime` removed from XHR `beforeSend` context

5e. `view.in_foreground_periods` removed from `beforeSend`

5f. Frustration signals collected automatically

5g. Resource method names are uppercase

5h. `session.plan` field removed

Step 6: Handle trusted events

Step 7: Update infrastructure

CSP `connect-src` domains changed

CORS headers for distributed tracing

Logs: `error.origin` removed

Logs: console error prefix removed

Logs: main logger decoupled

Common Mistakes

Verification checklist

Uh oh!

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

Upgrade Datadog Browser SDK to v5

Step 1: Update SDK version

Step 2: Replace deprecated init parameters

Step 3: Replace deprecated public APIs

RUM APIs

Logs APIs

Step 4: Update Session Replay configuration

4a. defaultPrivacyLevel changed to "mask"

4b. Recording starts automatically

4c. Default sessionReplaySampleRate is now 0

4d. trackResources and trackLongTasks must be explicit

Step 5: Update changed APIs and behaviors

5a. beforeSend must return a boolean

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

5c. beforeSend performance entry is now a PerformanceEntry object

5d. startTime removed from XHR beforeSend context

5e. view.in_foreground_periods removed from beforeSend

5f. Frustration signals collected automatically

5g. Resource method names are uppercase

5h. session.plan field removed

Step 6: Handle trusted events

Step 7: Update infrastructure

CSP connect-src domains changed

CORS headers for distributed tracing

Logs: error.origin removed

Logs: console error prefix removed

Logs: main logger decoupled

Common Mistakes

Verification checklist

4a. `defaultPrivacyLevel` changed to `"mask"`

4c. Default `sessionReplaySampleRate` is now `0`

4d. `trackResources` and `trackLongTasks` must be explicit

5a. `beforeSend` must return a boolean

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

5c. `beforeSend` performance entry is now a `PerformanceEntry` object

5d. `startTime` removed from XHR `beforeSend` context

5e. `view.in_foreground_periods` removed from `beforeSend`

5h. `session.plan` field removed

CSP `connect-src` domains changed

Logs: `error.origin` removed