Skip to main content
skill CX Codex

upgrade-browser-sdk-v5 — Claude Code skill: migration and install

The upgrade-browser-sdk-v5 Claude Code skill guides a Datadog Browser SDK upgrade from v4 to v5. It applies when a project still uses retired options, APIs, or CDN paths containing /v4/.

MIT 124 installs ★ 185 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v5 -a claude-code
Open on GitHub

What upgrade-browser-sdk-v5 does

The skill walks through moving Datadog Browser SDK from v4 to v5. It updates CDN versions and package.json dependencies, then maps retired configuration options and methods to their v5 replacements. Search patterns use grep to locate affected code across project files.

Session Replay needs a separate pass: v5 changes privacy behavior, starts recording automatically, and sets sessionReplaySampleRate to 0 by default. The guide also covers resource and long-task collection settings. AP2 is unavailable in v5; using it requires upgrading to v6 first.

What it helps with

  • find CDN references that still use /v4/
  • replace retired SDK options and methods
  • update Datadog dependencies in package.json
  • review Session Replay settings after migration

Example prompts for the agent

  • Upgrade this project’s Datadog Browser SDK from v4 to v5.
  • Find deprecated Datadog options and replace them with their v5 names.
  • Review the Session Replay configuration for the v5 upgrade.

How to install upgrade-browser-sdk-v5

1Skills CLI (Vercel)

npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v5 -a claude-code

2Manually: put the files in place

~/.claude/skills/upgrade-v5/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/upgrade-v5/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about upgrade-browser-sdk-v5

How do I install upgrade-browser-sdk-v5 in Claude Code?

Run npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v5 -a claude-code. The skill file is at ~/.claude/skills/upgrade-v5/SKILL.md.

What does upgrade-browser-sdk-v5 do?

It guides a Datadog Browser SDK migration from v4 to v5, including dependency versions, retired options and APIs, and Session Replay configuration changes.

Does Datadog Browser SDK v5 support AP2?

AP2 is unavailable in v5. Upgrade to v6 first if AP2 is required.

Source text

SKILL.md · MIT
---
name: upgrade-browser-sdk-v5
description: >
  Upgrade Datadog Browser SDK from v4 to v5. Use when encountering removed options like
  proxyUrl, sampleRate, replaySampleRate, premiumSampleRate, allowedTracingOrigins, or
  deprecated APIs like addRumGlobalContext, removeUser, or when a project references
  datadoghq-browser-agent.com CDN with /v4/ paths.
metadata:
  version: "1.0.0"
  author: datadog-labs
  repository: https://github.com/datadog-labs/agent-skills
  tags: datadog,browser-sdk,rum,logs,migration,v5,upgrade
---

# 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` |

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

| 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`        |

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):

```js
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):

```js
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:

```js
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:

```js
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.

```js
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).

```js
// 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:

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

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

Or allow all untrusted events globally:

```js
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.

Search for main logger configuration that may have been relying on this inheritance: `grep -rn 'DD_LOGS\.logger\.setLevel\|DD_LOGS\.logger\.setHandler\|DD_LOGS\.logger\.setContext\|DD_LOGS\.logger\.setContextProperty' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`. For each match, verify the setting is intentional for the main logger only — it will no longer affect runtime errors, network logs, or console logs.

## 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:

- [ ] SDK loads without console errors
- [ ] No references to removed init parameters (`proxyUrl`, `sampleRate`, `replaySampleRate`, etc.)
- [ ] No references to removed APIs (`addRumGlobalContext`, `removeUser`, etc.)
- [ ] `beforeSend` callbacks return boolean values
- [ ] `beforeSend` action handlers use `context.events` (not `context.event`)
- [ ] `trackResources` and `trackLongTasks` explicitly set if using `sessionReplaySampleRate`
- [ ] Session Replay recording works (if `sessionReplaySampleRate` > 0)
- [ ] Distributed tracing working (no CORS errors from `traceparent` header)
- [ ] CSP `connect-src` updated to new intake domains
- [ ] Dashboards/monitors updated for uppercase `resource.method`
- [ ] No queries using `error.origin` (use `origin` instead)

© datadog-labs · MIT · datadog-labs/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set41

The whole set →
agent-observability-build-eval-from-annotations agent-observability-build-eval-from-annotations fits a Datadog LLM-Obs evaluator to human labels using iterative error analysis. Scales manual queue reviews into an automated LLM judge. CX Codex +1 254installs agent-observability-online-experiment The agent-observability-online-experiment skill initiates online experiments, or A/B tests, for LLM applications within Claude Code. It allows comparing prompt or model versions using live traffic. CX Codex +1 170installs upgrade-browser-sdk-v6 upgrade-browser-sdk-v6 — a skill for Claude Code and Cursor migrating Datadog Browser SDK from version 5 to 6. Used during dependency upgrades or deprecated option cleanup. CX Codex +1 134installs dd-product-recommender The dd-product-recommender skill analyzes codebases and project goals to recommend fitting Datadog products. CX Codex +1 130installs dd-instrument-rum The dd-instrument-rum Claude Code skill configures Datadog Browser RUM in web applications. It activates for requests to add, repair, or check RUM, Browser Monitoring, or Session Replay. CX Codex +1 116installs dd-account-setup The dd-account-setup Claude Code skill checks Datadog credentials and the account region. It runs before Datadog setup or instrumentation, and can address a 403 caused by a region mismatch. CX Codex +1 113installs setup-browser-sdk-sourcemaps setup-browser-sdk-sourcemaps is a Claude Code skill that configures JavaScript sourcemap uploads to Datadog. It addresses minified stack traces in RUM and Error Tracking. CX Codex +1 108installs dd-aws-integration dd-aws-integration is a Claude Code skill that sets up the Datadog AWS integration using Terraform. CX Codex +1 105installs

Project sponsors

Companies that keep this analytics open