upgrade-browser-sdk-v5

将 Datadog Browser SDK 升级到 v5

从 v4 迁移到 v5 的系统性指南。请按顺序完成步骤 1-7。每个步骤都包含用于查找受影响代码的搜索模式。

步骤 1：更新 SDK 版本

CDN 配置 — 更新脚本的 src URL：

v4 模式	v5 替换项
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

将 us1 替换为你的站点：eu1、us3、us5、ap1。对于 US1-FED，模式为扁平格式，不带站点前缀：datadog-rum-v5.js、datadog-logs-v5.js、datadog-rum-slim-v5.js。注意：v5 不支持 AP2 — 如果需要 AP2，请先升级到 v6。

搜索：grep -r "datadoghq-browser-agent.com.*v4" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

npm 配置 — 更新 package.json 依赖项：

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

然后运行你的包管理器（npm install、yarn install 等）并重新构建。

如果使用了框架集成，也请将其升级到 v5：@datadog/browser-rum-react。

搜索：grep -r "@datadog/browser-" --include="package.json" .

步骤 2：替换已弃用的初始化参数

这些 v4 参数名称在 v5 中已不存在。请替换为：

已弃用的参数（v4）	替换项（v5）
proxyUrl	proxy
sampleRate	sessionSampleRate
allowedTracingOrigins	allowedTracingUrls
tracingSampleRate	traceSampleRate
trackInteractions	trackUserInteractions
premiumSampleRate	sessionReplaySampleRate
replaySampleRate	sessionReplaySampleRate

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

注意：sampleRate 匹配范围较广。请重点检查初始化配置对象 — sessionSampleRate 是 v5 中表示会话采样率的名称。

步骤 3：替换已弃用的公共 API

这些 v4 API 方法名称在 v5 中已不存在：

RUM API

已弃用的 API（v4）	替换项（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 API

已弃用的 API（v4）	替代 API（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

搜索：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"

第 4 步：更新 Session Replay 配置

v5 更改了多项 Session Replay 默认值和行为：

4a. defaultPrivacyLevel 更改为 "mask"

在 v4 中，默认值为 mask-user-input。在 v5 中，默认会遮罩所有内容。

要保留 v4 的行为（仅遮罩用户输入）：

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

4b. 自动开始录制

现在，会自动录制抽样到 Session Replay 的会话。无需再调用 startSessionReplayRecording()。

要保留 v4 的行为（手动开始录制）：

DD_RUM.init({
  startSessionReplayRecordingManually: true,
})

4c. sessionReplaySampleRate 的默认值现在为 0

在 v4 中，默认的回放抽样率为 100。在 v5 中，默认值为 0——除非设置该值，否则不会回放。

操作：确保在初始化配置中明确设置 sessionReplaySampleRate：

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

4d. 必须明确设置 trackResources 和 trackLongTasks

使用 sessionReplaySampleRate（而非已移除的 replaySampleRate 或 premiumSampleRate）时，默认不再收集资源和长任务。请明确启用它们——除非 v4 配置已出于特定目的将它们设为 false：

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

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

同时搜索所有 RUM 初始化调用，以查找省略这些选项并依赖 v4 默认值的项目：grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"。对于每个初始化调用，请确认已明确设置 sessionReplaySampleRate、defaultPrivacyLevel 和 trackResources/trackLongTasks。

第 5 步：更新有变更的 API 和行为

5a. beforeSend 必须返回布尔值

beforeSend 回调函数应返回 true 以保留事件，或返回 false 以丢弃事件。如果未返回值，则保留事件。这样可以解决 TypeScript 编译错误。

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

5b. beforeSend 操作上下文：context.event → context.events

借助挫折信号，一个操作事件可以关联多个 DOM 事件。context.event 已替换为 context.events（数组）。

// 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 性能条目现在是 PerformanceEntry 对象

beforeSend 上下文中的 performanceEntry 现在是原始 PerformanceEntry 对象，而非 JSON 表示形式。PerformanceEntryRepresentation 类型已移除。

5d. 从 XHR beforeSend 上下文中移除 startTime

context.startTime 属性已从 XHR 资源的 beforeSend 上下文中移除。请改用 performanceEntry。

5e. 从 beforeSend 中移除 view.in_foreground_periods

此属性现在由后端计算。请移除任何访问 view.in_foreground_periods 的 beforeSend 代码。

5f. 自动收集挫折信号

设置 trackUserInteractions: true，即可收集所有用户交互，包括挫折信号。不再需要 trackFrustrations 参数。

5g. 资源方法名称为大写

资源的 method 字段现在始终为大写（例如，GET、POST）。请更新任何基于 resource.method 进行筛选的仪表板或监控项。

5h. 已移除 session.plan 字段

v5 中已移除 session.plan 字段（lite/premium），且不会在任何事件类型中发送。请将基于 session.plan 的仪表板或监控项筛选条件替换为以下新的回放字段：

• @session.sampled_for_replay:true — 会话已被抽样用于 Session Replay
• @session.has_replay:true — 会话包含实际回放录制

搜索：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"

步骤 6：处理可信事件

v5 仅监听由用户生成的（可信）事件。默认情况下会忽略脚本生成的事件。

如果你依赖程序化事件（例如，dispatchEvent），请添加 __ddIsTrusted 属性：

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

或者全局允许所有不可信事件：

DD_RUM.init({
  allowUntrustedEvents: true,
})

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

步骤 7：更新基础设施

CSP connect-src 域名已更改

v5 会将数据发送到新的 intake 域名。请更新你的内容安全策略：

Datadog 站点	新的 connect-src 域名
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 标头

v5 将 tracecontext 添加为默认传播器。如果你使用 allowedTracingUrls，服务器必须接受 traceparent 标头。请将其添加到现有的 Access-Control-Allow-Headers 中，不要替换整个列表：

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

日志：已移除 error.origin

请将使用 error.origin 的仪表板或监控项更新为使用 origin。

日志：已移除控制台错误前缀

日志消息中的 "console error:" 前缀已移除。请将使用此前缀的查询更新为使用 @origin:console。

日志：主日志记录器已解除耦合

运行时错误、网络日志、报告日志和控制台日志不再继承主日志记录器的上下文、级别或处理器。请改用全局上下文和专用初始化参数。

搜索可能依赖此继承行为的主日志记录器配置：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"。对于每个匹配项，请确认该设置仅针对主日志记录器；它将不再影响运行时错误、网络日志或控制台日志。

常见错误

错误	问题	修复
设置 sessionReplaySampleRate > 0，但未启用 trackResources 和 trackLongTasks	不会收集资源和长任务，且不会像以前使用 sessionReplaySampleRate 时那样默认设为 true	将 trackResources: true, trackLongTasks: true 与任何非零的 sessionReplaySampleRate 一起添加
在操作事件的 beforeSend 中使用 context.event 而非 context.events	操作上下文属性已重命名，context.event 为 undefined，DOM 事件详情丢失	更新为 context.events（数组）；如果需要所有关联的 DOM 事件，请遍历该数组
未将 CSP connect-src 更新为新的 v5 接收域名	SDK 无法发送数据，且旧接收域名已失效	将 connect-src 更新为适用于你站点的 v5 接收域名（见步骤 7）

验证清单

升级后，请确认：

• SDK 加载时没有控制台错误
• 不存在对已移除初始化参数（proxyUrl、sampleRate、replaySampleRate 等）的引用
• 不存在对已移除 API（addRumGlobalContext、removeUser 等）的引用
• beforeSend 回调返回布尔值
• beforeSend 操作处理程序使用 context.events（而非 context.event）
• 如果使用 sessionReplaySampleRate，则显式设置 trackResources 和 trackLongTasks
• Session Replay 录制正常工作（如果 sessionReplaySampleRate > 0）
• 分布式追踪正常工作（traceparent 标头没有 CORS 错误）
• CSP connect-src 已更新为新的接收域名
• 信息板/监控项已更新，以适配大写的 resource.method
• 不存在使用 error.origin 的查询（请改用 origin）