Backstage 集成 Datadog RUM为开发者门户接入前端真实用户监控的完整指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageDatadog Real User MonitoringRUM能够实时可视化并分析每位用户的访问性能与完整用户旅程帮助你在 Backstage 开发者门户上持续监控真实用户体验。Backstage 内置了基础的 Datadog RUM 集成本文将以docs/integrations/datadog-rum/installation.md为主线结合仓库内 packages/app/public/index.html 与 packages/cli/package.json 中的配置 Schema 源码完整讲解从配置到验证的全过程。Datadog RUM 能为你带来什么在 Backstage 中启用 Datadog RUM 后你可以追踪真实用户在门户中的完整浏览路径与操作行为用户旅程分析页面加载时间、前端错误等关键性能指标定位影响体验的瓶颈通过会话回放Session Replay还原用户实际操作画面辅助问题排查。Backstage 已经在官方文档的 可观测性章节 中列出了 Datadog RUM Events 的安装指引本文即该指引的完整实操展开。前置条件获取 Datadog RUM 凭据在开始配置之前你需要在 Datadog 控制台的 Real User Monitoring 页面创建一个 RUM 应用遵循 Datadog 官方的 Browser Monitoring 配置流程创建完成后会生成两个核心凭据clientTokenDatadog RUM 的客户端令牌用于在浏览器端上报事件applicationIdRUM 应用的唯一标识。这两个值将用于下文的所有配置步骤。快速开始在 app-config.yaml 中启用 Datadog RUMBackstage 内置的 Datadog RUM 集成通过根配置文件启用。在仓库根目录的 app-config.yaml 中追加以下配置app: datadogRum: clientToken: 123456789 applicationId: qwerty # site: datadoghq.eu # env: staging # sessionSampleRate: 100 # sessionReplaySampleRate: 0配置完成后Backstage 前端在构建时就会把 Datadog RUM 的初始化代码注入到应用的 HTML 入口中。如果你的app-config.yaml中没有这一段配置那么你需要手动调整 packages/app/public/index.html将 Datadog RUM 的init()代码段加入其中具体做法见下文「手动注入方案」。配置项详解Backstage CLI 在 packages/cli/package.json 的configSchema中正式声明了app.datadogRum的全部字段及其类型、可见性与必填要求。综合官方文档与 Schema 定义各配置项说明如下配置项类型是否必填说明clientTokenstring必填Datadog RUM 客户端令牌来自 Datadog RUM 页面applicationIdstring必填RUM 应用 ID来自 Datadog RUM 页面sitestring可选你所在组织的 Datadog 站点默认值为datadoghq.com例如欧盟站点为datadoghq.euenvstring可选Datadog 事件的运行环境标签无默认值且必须在构建时指定sessionSampleRatenumber可选Datadog RUM 事件采集的采样率默认 100sessionReplaySampleRatenumber可选在已采样的 RUM 事件基础上进行会话回放Session Replay的采样率默认 0从 Schema 中可以确认两点关键实现事实上述所有字段的visibility均为frontend即它们会被注入到前端构建产物中供浏览器读取required仅包含clientToken与applicationId两项其余参数均可省略并回退到默认值。其中site与env是仅有的两个可选参数官方文档进一步明确site你所在组织的 Datadog 站点未配置时默认使用datadoghq.comenvDatadog 事件的应用环境标签无默认值。内置注入机制源码层面的实现原理在 Backstage 仓库中Datadog RUM 的初始化代码已经内置在 packages/app/public/index.html 的head标签内并通过 EJS 模板语法与运行时配置联动% if (config.has(app.datadogRum)) { % script (function (h, o, u, n, d) { h h[d] h[d] || { q: [], onReady: function (c) { h.q.push(c); }, }; d o.createElement(u); d.async 1; d.src n; n o.getElementsByTagName(u)[0]; n.parentNode.insertBefore(d, n); })( window, document, script, https://www.datadoghq-browser-agent.com/datadog-rum-v3.js, DD_RUM, ); DD_RUM.onReady(function () { DD_RUM.init({ clientToken: % config.getString(app.datadogRum.clientToken) %, applicationId: % config.getString(app.datadogRum.applicationId) %, site: % config.getOptionalString(app.datadogRum.site) || datadoghq.com %, service: backstage, env: % config.getString(app.datadogRum.env) %, sampleRate: % config.getOptionalNumber(app.datadogRum.sessionSampleRate) || 100 %, sessionReplaySampleRate: % config.getOptionalNumber(app.datadogRum.sessionReplaySampleRate) || 0 %, trackInteractions: true, }); }); /script % } %这段代码揭示了几个重要的实现细节使用config.has(app.datadogRum)作为条件开关只有配置了app.datadogRum时才会加载 Datadog 浏览器代理脚本datadog-rum-v3.js通过config.getString/config.getOptionalString/config.getOptionalNumber在构建时读取配置并渲染进 HTML其中site、sessionSampleRate、sessionReplaySampleRate均有兜底默认值分别为datadoghq.com、100、0service固定为backstagetrackInteractions固定为true启用交互追踪这两个值不暴露为可配置项脚本采用异步加载d.async 1不会阻塞页面首屏渲染。为什么 env 必须在构建时指定官方文档明确强调env的值必须在构建时build time指定。从上面的模板代码可以推断其根本原因env通过% config.getString(app.datadogRum.env) %在 HTML 模板渲染阶段就被固化为字面量并且它是唯一一个没有默认值兜底的必填读取项。一旦构建完成运行时再去修改env配置也不会生效。因此如果你需要在不同环境staging、production 等打上不同的环境标签必须在各自环境的构建流程中注入对应的env值。手动注入方案当事件仍未捕获时如果你已经按照上述方式正确配置但 Datadog 后台仍然收不到事件官方文档给出的兜底方案是将上面的初始化代码段手动复制并粘贴到 packages/app/public/index.html 的head标签下注意该文件在仓库中默认已包含此代码段此操作主要面向模板缺失或自定义入口文件的场景。手动注入时请确保代码段被% if (config.has(app.datadogRum)) { % ... % } %包裹这样只有当配置存在时才会加载脚本同时注意保持clientToken、applicationId等取值表达式与上文的模板语法完全一致否则构建时将无法正确渲染配置值。故障排查与验证清单完成配置后可以按以下顺序自检确认 app-config.yaml 中存在app.datadogRum且clientToken、applicationId填写正确两者为 Schema 中声明的必填项确认env已在构建时正确注入运行期修改不会生效确认构建产物index.html的head中已渲染出完整的DD_RUM.init({...})代码块打开门户页面在浏览器开发者工具的 Network 面板中观察是否向 Datadog 的浏览器代理端点发起了请求若事件仍未被捕获将上文的手动注入代码段粘贴至入口 HTML 的head标签下重新构建后再次验证。通过以上步骤你就可以在 Backstage 开发者门户上建立完整的真实用户监控能力持续洞察每一位用户的实际体验。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考