Upgrade Datadog Browser SDK to v6

Systematic migration guide from v5 to v6. Follow steps 1-6 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, ap2. For US1-FED, the pattern is flat with no site prefix: datadog-rum-v6.js, datadog-logs-v6.js, datadog-rum-slim-v6.js.

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

npm setup — update package.json dependencies:

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

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

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

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

Step 2: Remove deprecated options

Removed from Core (affects both RUM and Logs)

Removed from Logs

Search: grep -rn 'useCrossSiteSessionCookie\|sendLogsAfterSessionExpiration' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Step 3: Update changed defaults

v6 changes several default behaviors. Review each and adjust if needed:

3a. trackUserInteractions, trackResources, and trackLongTasks default to true

In v5, these were false by default. In v6, they are enabled out of the box. This does not impact billing.

To preserve v5 behavior, explicitly disable only the options that were not already enabled in v5. If an option was already true in v5, leave it unchanged:

DD_RUM.init({
  trackUserInteractions: false, // only if not already true in v5
  trackResources: false, // only if not already true in v5
  trackLongTasks: false, // only if not already true in v5
})

3b. traceContextInjection defaults to "sampled"

In v5, trace context was injected for all requests. In v6, it's only injected for sampled traces. If your traceSampleRate is 100% (the default), this has no impact.

To preserve v5 behavior:

DD_RUM.init({
  traceContextInjection: 'all',
})

3c. tracestate header added with tracecontext propagator

The tracecontext propagator now sends an additional tracestate header. Your server must accept it. Add it to your existing Access-Control-Allow-Headers — do not replace the full list:

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

3d. site parameter is strongly typed

The site option has a stricter TypeScript type. If you pass a non-standard value, you get a type error. Use proxy for non-standard intake URLs instead.

Search: grep -rn 'trackUserInteractions\|trackResources\|trackLongTasks\|traceContextInjection\|tracestate\|allowedTracingUrls\|propagatorTypes' --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 relied on the v5 false 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, check whether trackUserInteractions, trackResources, and trackLongTasks are explicitly set — if omitted, they now default to true in v6.

Step 4: Handle Session Replay lazy loading

Session Replay is now lazy-loaded using dynamic imports. The module loads only for sessions sampled for replay, reducing bundle size for others.

npm setup

Ensure your bundler supports dynamic imports (code splitting). Most modern bundlers do:

• Webpack: Code splitting docs
• Esbuild: Splitting option
• Rollup: Code splitting docs
• Parcel: Code splitting docs

CDN setup

No code changes needed. The SDK dynamically loads an additional chunk when recording (e.g., datadogRecorder-<hash>-datadog-rum.js). Update CSP script-src rules if needed to allow the chunk.

Step 5: Review behavioral changes (no code required, but may need attention)

Step 6: Update infrastructure

• Browser support: ES2018 baseline. IE11 is no longer supported.
• CORS: Add tracestate to your existing Access-Control-Allow-Headers if using the tracecontext propagator (do not replace the full list): Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate
• CSP: Allow the dynamically loaded Session Replay chunk (e.g., datadogRecorder-*-datadog-rum.js) in script-src rules.
• Bundler config: Ensure your bundler supports dynamic imports for Session Replay lazy loading.

Verification checklist

After upgrading, confirm:

• SDK loads without console errors
• No references to removed options (useCrossSiteSessionCookie, sendLogsAfterSessionExpiration)
• Session Replay recordings working (if used)
• Distributed tracing working (no CORS errors from tracestate header)
• Bundle size decreased (IE11 polyfills removed)
• Long tasks still collected (now as Long Animation Frames on supported browsers)
• No TypeScript errors from site parameter typing

Common Mistakes