用途:按顺序完成 Datadog Browser SDK v4 到 v5 的迁移,每步附带可搜索代码的 grep 模式。
主要能力与关键步骤:
- 更新 SDK 版本。CDN 需把脚本 URL 中的 v4 改为 v5(如 datadoghq-browser-agent.com/us1/v4/datadog-rum.js 改为 .../v5/datadog-rum.js),站点前缀按 us1、eu1、us3、us5、ap1 替换;US1-FED 使用无站点前缀的 datadog-rum-v5.js 等。AP2 在 v5 不可用,需先升 v6。npm 则更新 package.json 依赖为 ^5.0.0 并重装、重建,框架集成如 @datadog/browser-rum-react 也升到 v5。
- 替换废弃初始化参数:proxyUrl→proxy、sampleRate→sessionSampleRate、allowedTracingOrigins→allowedTracingUrls、tracingSampleRate→traceSampleRate、trackInteractions→trackUserInteractions、premiumSampleRate 与 replaySampleRate→sessionReplaySampleRate。
- 替换废弃公开 API:如 DD_RUM.removeUser→clearUser、addRumGlobalContext→setGlobalContextProperty 等;Logs 侧 addLoggerGlobalContext→setGlobalContextProperty、logger.addContext→setContextProperty 等。
- Session Replay 配置变化:defaultPrivacyLevel 默认改为 mask;采样会话自动录制,需手动时设 startSessionReplayRecordingManually:true;sessionReplaySampleRate 默认变 0,需显式设置;使用它时 trackResources、trackLongTasks 不再默认采集,需显式开启。
- 行为变更:beforeSend 需返回布尔值;action 上下文 context.event 改为 context.events 数组;performanceEntry 为原始对象;XHR 上下文移除 startTime;移除 view.in_foreground_periods;trackUserInteractions 自动收集挫折信号;resource.method 全大写;session.plan 移除,改用 @session.sampled_for_replay、@session.has_replay。
- 可信事件:v5 仅监听用户产生的可信事件,程序化事件需加 __ddIsTrusted=true,或设 allowUntrustedEvents:true。
- 基础设施:CSP connect-src 改用新 intake 域名(如 US1 为 https://browser-intake-datadoghq.com);分布式追踪需服务端接受 traceparent 头并加入 Access-Control-Allow-Headers;日志移除 error.origin(改用 origin)和 console 前缀,主 logger 不再被运行时/网络/console 日志继承。
使用方式:按 1-7 步顺序执行,用各步 grep 命令定位受影响代码,升级后核对验证清单(SDK 无报错、无废弃参数与 API、beforeSend 返回布尔、CSP 已更新、仪表盘适配大写 method 等)。
限制:资料未给出具体工具版本支持范围与回滚方案;部分行为需结合自有服务端配置调整。