dd-instrument-rum

Datadog 浏览器 RUM 埋点

仅对指定范围内的浏览器应用进行埋点。不要添加 Datadog APM、追踪、LLM Observability、Logs、source-map 上传、用户身份识别、Vercel 元数据、Shopify、Salesforce 或其他无关的 Datadog 产品。

除可选的 RUM 应用创建操作外，所有步骤都使用常规文件检查、编辑和命令工具。创建 RUM 应用时，仅使用 references/common-credentials.md 中所述的 CreateRumApplication；切勿杜撰 Datadog 工具名称。

基本规则

• 编辑前先检查。所有关于框架、版本、入口点、命令和配置的决定都必须以项目文件为依据。
• 严格按照适用参考资料复制包名、导入路径、导出符号和初始化选项键。不要替换包别名，也不要凭记忆重建 SDK API。
• 更改前先发布简短的检查清单，并随着工作的完成更新清单。
• 在浏览器生命周期中，在安全可行的前提下尽早且仅初始化一次 RUM。绝不要在组件渲染、生命周期钩子、路由处理程序或重复调用的回调中放置 init()。
• 保留现有的有效初始化配置。将缺失且兼容的框架插件接线添加到该初始化配置中；绝不要另建一个相互竞争的初始化配置。
• **现有初始化配置的凭据保护规则：**如果已存在一个有效的 RUM 初始化配置，则其 applicationId、clientToken、site、服务标签、采样、隐私、追踪及其他所有现有选项均不可更改。任务提供的凭据仅用于新的初始化配置，不能覆盖现有有效配置。在此情况下，添加插件接线时不得重写凭据所在行。
• 如果无法确定所需凭据、site 无效、框架／插件前提条件未满足、权限不足，或存在多个无法安全合并的冲突初始化调用，则停止且不要编辑。
• 仅安装 Browser RUM 所需的包。@datadog/browser-rum 和所有 @datadog/browser-rum-* 集成包必须使用完全相同的 SDK 版本。
• 将依赖项保存到实际构建所用的清单和锁文件中。不得依赖 node_modules 中碰巧已存在的包。
• 保留应用行为、现有自定义错误处理、格式约定及无关代码。
• 使用可用的文件编辑工具应用更改。如果预期的文本匹配失败，请重新读取文件并根据其当前内容调整，不要重复尝试相同的编辑。
• 不要将项目路径、框架详情、凭据、客户端令牌或 RUM 应用 ID 写入持久记忆。
• 报告成功前，必须运行一个会终止的构建。除非实际观察到遥测数据，否则绝不要声称已收到遥测数据。

第 1 阶段：分析目标

定位浏览器应用

确定会生成浏览器代码的项目根目录。在 monorepo 中，检查工作区配置、脚本、Dockerfile 以及 CI／部署配置，找到实际构建所用的前端清单，而不是想当然地编辑仓库根目录。编辑前记录该清单路径及其包管理器。如果可能存在多个相互独立的浏览器应用，且用户未指定要埋点的应用，请询问用户要处理哪个应用。

排除 Ink CLI 等非浏览器应用，以及没有 HTML／浏览器构建目标的项目。

检测框架和运行时形态

按以下顺序检查依赖项和源代码布局，确保元框架优先于其底层 UI 库：

1. nuxt -> Nuxt
2. next -> Next.js；根据源代码布局区分 App Router 和 Pages Router
3. @angular/core -> Angular；区分独立启动和 NgModule
4. vue -> Vue
5. svelte 或 @sveltejs/kit -> Svelte 或 SvelteKit
6. react -> React
7. 若没有上述框架，但存在浏览器入口点 -> 通用／原生浏览器应用

还要检测：

• 框架、React Router、TanStack Router、Vue Router 和 Node 的精确版本。
• 若存在 tsconfig.json 或 TypeScript 依赖，则使用 TypeScript；否则保留 JavaScript。
• 首先根据已部署清单中的 packageManager 字段确定包管理器；若无此字段，再检查同目录下的锁文件：bun.lock 或 bun.lockb、pnpm-lock.yaml、yarn.lock 或 package-lock.json。只有在没有更明确的项目信号时才使用 npm，且绝不混用包管理器。
• 根据配置和依赖项确定打包工具：Vite、Webpack、Rollup、esbuild、Rspack 或 Create React App（react-scripts）。只有在没有包／打包工具构建流程管理 HTML 时，才将未管理的 HTML 视为 CDN。
• 根据构建配置、HTML 脚本目标、框架约定和导入关系图确定浏览器入口点，而不能只依据文件名。
• 正常情况下会终止流程的构建／类型检查命令。
• 现有的公开环境变量约定。

阅读 references/rum-core.md，然后只阅读适用的框架参考文档：

目标	参考文档
React、React Router、TanStack Router	references/rum-react.md
Next.js App 或 Pages Router	references/rum-nextjs.md
Angular	references/rum-angular.md
Vue	references/rum-vue.md
Nuxt	references/rum-nuxt.md
Svelte、原生应用、通用 SPA、iframe 托管应用	references/rum-other-frameworks.md

在配置凭据或编辑文件之前，先验证所选参考文档中的所有前提条件。不要升级框架；若检测到的框架插件不兼容，也不要悄悄退回到仅使用核心 RUM 的方案。

检测现有 RUM 埋点

搜索源代码、HTML 和配置文件，同时排除依赖项、构建产物、生成文件和覆盖率目录，例如 node_modules、dist、build、.next、.nuxt 和 coverage。

检查以下内容：

• 来自 @datadog/browser-rum 的导入或 require，包括重命名和命名空间绑定。
• 来自任何 @datadog/browser-rum-* 集成包的导入。
• 绑定到导入的 datadogRum.init 的调用，包括别名和本地包装模块。
• DD_RUM.init、window.DD_RUM.init、DD_RUM.onReady 以及 Datadog CDN 加载器 URL。
• 现有插件注册、路由包装器／提供程序／组件，以及框架错误钩子。

仅有软件包并不足以证明已在使用：依赖项可能未被使用。

• 没有 init： 根据所选参考文档添加一个。
• 一个有效的 init： 保留其位置和所有现有值。不要查找或应用替换凭据。只向其中添加缺少且兼容的插件／路由／错误处理接线。
• 一个 init，但缺少或包含无效的必需凭据／站点： 停止并报告无效配置；不要再叠加另一个 init。
• 多个 init 调用或混用 npm／CDN 方案： 停止并报告每个位置，除非能证明它们属于同一互斥方案。不要猜测应该采用哪种方案。
• 配置完整： 不做任何更改；仍须运行适用的验证。

阶段 2：接入

仅在分析成功后，才通过 references/common-credentials.md 获取凭据。如果分析发现一个有效的现有初始化，则复用其现有凭据，并完全跳过凭据替换。仅在创建新的初始化时，才可使用任务中提供的凭据。然后：

1. 使用检测到的包管理器，根据已部署的前端清单安装核心 SDK 和兼容的框架包。对于有效的现有初始化，只安装缺失的集成包；绝不替换已有的有效 RUM 包或配置。
2. 按照 references/rum-core.md 应用规范配置和安装方式。对于有效的现有初始化，只向同一对象应用缺失的兼容字段；不要将凭据或规范选项占位符复制到现有值上。
3. 应用所选框架的参考说明，包括路由器跟踪，以及在相关功能存在时安全地集成框架错误处理。
4. 使用同一包管理器更新锁文件。绝不手动编辑生成的锁文件。
5. 根据清单脚本（如 lint:fix、fix 或 format）以及 ESLint/Prettier 配置检测已配置的格式化工具。仅对本次工作修改的文件运行项目的格式化或修复命令。

不要添加 allowedTracingUrls，也不要添加任何后端/CORS/跟踪配置；这些属于 APM 接入工作流。

阶段 3：验证并报告

按照 references/common-verify-report.md 执行。报告成功前，请检查最终差异，并与编辑前的项目进行对比。如果发现有效的现有初始化，请验证所有预先存在的初始化值（包括两项凭据）均逐字节保持不变，且唯一的设置变更是补齐所需的集成配置（以及任何严格必要的依赖项/锁文件变更）。如果任何现有值发生变化，请在报告成功前将其恢复。只有在所需包已写入项目、最终设置中恰好包含一个初始化，且常规构建成功时，才能报告成功。