Vue 3 应用上线后，最怕的不是功能缺漏，而是用户已经卡到崩溃，团队却拿不到任何现场数据。Datadog 的 RUM 产品正好填补了这块空白：它能在浏览器端采集核心性能指标，比如 LCP、FID、CLS，也能捕获未处理的 Promise 异常和 Vue 组件的错误生命周期。下面直接进入正题，看看如何用工程化的方式把 Datadog 集成到 Vue 3 项目里，而不是只在 main.js 里塞两行初始化代码就算完事。
Datadog RUM 的核心数据模型：Session 与 View
要真正用好 Datadog，先要理解它收集数据时组织数据的方式。RUM 把一次用户访问抽象成 Session（会话），一个 Session 里又能包含多个 View（视图）。它的概念跟 Vue Router 的路由天然对应：每次路由切换、页面加载或者 reload 都会生成一个新的 View，而 Session 则贯穿用户从进入站点到关闭页签的整个过程。这种数据结构带来的好处是，你可以按 Session 去回放用户操作，也可以按 View 去统计某个页面的 P75 加载耗时。
在 Vue 3 里，View 的自动追踪通常需要依赖框架的事件钩子。Datadog 的官方 SDK 提供了 manual 模式，允许开发者在路由变化时主动调用 datadogRum.startView()。相比全自动模式，手动模式更可控，因为 Vue Router 的 afterEach 钩子能拿到目标路由的 meta 字段，我们可以把页面名称、业务模块等维度塞进 View 参数里。这样在 Datadog 后台就能按业务模块筛选性能数据，而不是只能看到一串 URL。
另外需要注意 Session 的合并机制。如果用户打开页面后切到后台超过了一个阈值，SDK 会认为当前 Session 失效，重新回来时会新建 Session。这个阈值在初始化配置里可以通过 sessionReplaySampleRate 等参数控制，但不建议把采样率调得过高，否则产生的数据量会超出免费额度。工程化实践里，一般用 beforeSend 回调对 Session 做脱敏处理，去掉 URL 上的 token 参数以及用户手机号等敏感信息。
import { datadogRum } from '@datadog/browser-rum'
datadogRum.init({
applicationId: 'your-application-id',
clientToken: 'your-client-token',
site: 'datadoghq.com',
service: 'vue3-web-app',
env: 'production',
version: '1.2.3',
sessionSampleRate: 80, // 80% 会话进行采样
sessionReplaySampleRate: 20, // 只对 20% 的采样会话开启录制
trackUserInteractions: true,
trackResources: true,
trackLongTasks: true,
trackFrustrations: true,
beforeSend: (event) => {
// 去掉查询参数里的 token
if (event.view.url) {
event.view.url = event.view.url.replace(/[?&]token=[^&]*/, '')
}
return event
}
})
router.afterEach((to) => {
datadogRum.startView(to.name || to.path, {
module: to.meta.module || 'unknown',
pageType: to.meta.pageType || 'normal'
})
})
工程化集成：从工具函数到 Vue 插件封装
直接调用 datadogRum 对象当然能工作，但工程化讲究的是统一封装和可测试性。建议在 src/observability 目录下创建一个独立的模块，把 Datadog 的初始化与业务 API 隔离。这样如果后续换用其他监控服务，业务代码不需要改动。比较简单的做法是导出一个 trackEvent 函数，名字起得通用一些，比如 trackError、trackTiming，内部再映射到 Datadog 的对应方法。
更进一步，可以设计一个 Vue 3 插件，并利用 app.provide() 向组件树注入监控实例。组件内需要上报埋点时，通过 inject 获取 $track 对象，而不是直接从网络上 import SDK。这么做的好处是，在单元测试时可以用一个 Mock 对象替换整个监控模块，避免测试环境产生真实的上报请求。与此同时，插件还可以在 app.config.errorHandler 里捕获 Vue 组件渲染期间未被自定义代码捕获的错误，把这些错误连同组件名、props 一并发送给 Datadog。
下面给出一个完整的插件实现，包括错误捕获、页面性能上报和一个自定义指标示例。注意要在 package.json 里声明对 @datadog/browser-rum 的依赖，并且确保 SDK 的版本与 Vue 3 的模块系统兼容。
// src/observability/index.js
import { datadogRum } from '@datadog/browser-rum'
import { createApp } from 'vue'
export function initDatadog(config) {
datadogRum.init({
...config,
beforeSend: config.beforeSend
})
}
export const trackError = (message, context = {}) => {
datadogRum.addError(message, context)
}
export const trackTiming = (name, duration, context = {}) => {
datadogRum.addTiming(name, duration, context)
}
export const observabilityPlugin = {
install(app) {
const $track = {
error: trackError,
timing: trackTiming,
setUser: (user) => datadogRum.setUser(user)
}
app.provide('$track', $track)
app.config.errorHandler = (err, instance, info) => {
trackError(err.message, {
componentName: instance?.type?.name || 'anonymous',
info,
stack: err.stack
})
}
}
}
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { initDatadog, observabilityPlugin } from './observability'
initDatadog({
applicationId: import.meta.env.VITE_DD_APP_ID,
clientToken: import.meta.env.VITE_DD_CLIENT_TOKEN,
site: 'datadoghq.com',
service: 'vue3-ecshop',
env: import.meta.env.MODE,
version: __APP_VERSION__,
trackUserInteractions: true
})
createApp(App)
.use(router)
.use(observabilityPlugin)
.mount('#app')
在上面的代码里，__APP_VERSION__ 需要在 Vite 配置中通过 define 注入，值来自 package.json 的 version 字段，这样每次发布时 Datadog 后台能按版本对比错误率。组件内使用时，直接 const $track = inject('$track') 然后调用 $track.error('buy_click_failed')。这些公共 API 后续要扩展成更细粒度的类型时，只要在插件里增加方法即可。
路由切换与组件性能的深度追踪
很多团队接入 Datadog 之后只看了页面加载总时长，但 Vue 3 应用真正的性能瓶颈往往在路由切换后的组件渲染。Vue 3 的响应式系统用 Proxy 做了重写，组件渲染本身已经很快，但如果你在 onMounted 里发请求、在 watch 里做计算属性派生，这些操作一样会被 Long Task 采集到。Datadog 的 trackLongTasks 会自动记录超过 50ms 的长任务，我们需要做的是把长任务与当前路由关联起来。
做法是在路由 afterEach 钩子里记录导航开始时间，然后在组件挂载完成后调用 performance.mark() 打点。或者更简单一些，直接利用 Datadog 的 addTiming 接口传一个自定义耗时。下面这段代码演示了如何在商品列表页统计从路由进入到首屏商品渲染完成的时间差。注意 requestAnimationFrame 嵌套两次是为了确保 DOM 已经完成布局，否则时间可能偏小。
// components/ProductList.vue
<script setup>
import { onMounted, inject } from 'vue'
import { useRouter } from 'vue-router'
const $track = inject('$track')
const router = useRouter()
let enterTime = 0
router.isReady().then(() => {
enterTime = performance.now()
})
onMounted(() => {
requestAnimationFrame(() => {
requestAnimationFrame(() => {
const renderTime = performance.now() - enterTime
$track.timing('first_product_render', renderTime, {
page: 'product_list',
source: 'auto'
})
})
})
})
</script>
除了手动打点，你还可以利用 Vue 3 的 onErrorCaptured 生命周期钩子捕获嵌套子组件抛出的错误。有些错误不会冒泡到 window.onerror，但如果在某个子组件里 Promise 没有 catch，Vue 的边界会把错误传给 errorHandler，上面插件里已经接住了。还有一类性能分析是针对 Vuex/Pinia 的状态更新频率，Datadog 不直接提供这个能力，但你可以通过 custom metric 自己上报：比如在 store 的 mutation 之后记录当前 store 的 state 节点数量，这些指标在追踪内存泄漏时很有用。
另外，Datadog 的 RUM 还支持 Script 错误追踪。Vue 3 打包后的 chunk 如果加载失败，会产生 Script error 这种没有堆栈的跨域错误，SDK 默认会忽略。工程化处理方式是给 script 标签加上 crossorigin="anonymous" 属性，同时确保服务器返回 Access-Control-Allow-Origin 头。这样 Datadog 能拿到具体的错误详情，而不是一行无意义的 Script error。
采样率、脱敏与隐私合规的权衡
云监控不是采集得越多越好。Datadog 的计费按 Session 数量和数据量结算，如果 100% 采样，大型应用一个月的费用会非常可观。建议按环境区分采样策略：生产环境 70% 采样，灰度环境 100%，开发环境直接关掉。RUM 的 sessionSampleRate 控制是否采集完整 session，而 sessionReplaySampleRate 控制是否开启录屏回放，这两个维度可以独立配置。如果你的核心目标只是错误跟踪，回放采样率可以控制在 5% 以下，节省存储成本。
隐私合规是工程化中常被忽略的问题。用户可能输入身份证号、手机号、支付金额等敏感信息，一旦被 Datadog 录屏采集，就面临数据泄露风险。SDK 提供了 defaultPrivacyLevel 配置，设为 mask-user-input 可以把输入框内容替换成占位符，但第三方组件内部自己创建的 DOM 可能不受控制。这时需要配合 beforeSend 做防御性剥离，比如检测 event 内容里是否包含银行卡号正则，命中后直接把整个 event 丢弃。注意 beforeSend 里不能抛异常，否则会影响 SDK 正常工作。
datadogRum.init({
// 其他配置...
defaultPrivacyLevel: 'mask-user-input',
beforeSend: (event) => {
if (event.type === 'action' && event.action.target && event.action.target.text) {
const text = event.action.target.text
if (/\d{16,19}/.test(text)) {
return false // 丢弃包含银行卡号的交互
}
}
return event
}
})
还有一个常见问题是多环境标识。同一套代码可能部署在多个可用区，通过 service 和 env 标签可以区分，但更细粒度的是在初始化时调用 datadogRum.setUser() 把登录态的用户 ID 传进去。对于未登录用户，不要传空字符串，而是传一个匿名标识，比如 anonymous-${sessionId}。这样在 Datadog 后台可以合并同一用户多次访问的行为轨迹，又避免真实用户信息暴露。
与前端异常监控体系的对比选型
Datadog 并不是唯一选择，Sentry 也提供前端监控，而且自托管成本较低。两者的核心差异在于数据的聚合方式。Datadog 的强项是把基础设施指标、日志、APM 和 RUM 统一在一个平台，如果你已经有后端服务在用 Datadog，前端接入的成本可以摊薄。Sentry 则更专注于错误堆栈的合并和去重，它能把同一错误聚合的智能程度比 Datadog 更高，但是性能监控能力偏弱，自定义面板也没有 Datadog 灵活。
从工程化角度看，如果团队已经建立了自研日志系统，可以考虑只用 Datadog 的 RUM 部分，把错误事件通过 beforeSend 过滤后转发到自研的 Kafka。但要注意这种转发是异步的，不能阻塞主线程。sendBeacon 是推荐的方式，Datadog SDK 内部已经使用了 Beacon，以便在页面 unload 时还能把数据发出去。如果采用混合方案，可以关闭 Datadog 的 Error Tracking 功能，只保留性能数据和 Session Replay，这样能降低单价。
最后需要强调的是，云监控不是一劳永逸的，它需要配套的告警策略。Datadog 的 RUM 可以设置自定义告警，比如某个首屏时间的 p95 连续 5 分钟超过 3 秒就发出通知。建议在部署流水线中加入一个 check 脚本，拉取 Datadog 的官方 API 判断当前版本是否有新增错误，如果错误率高于阈值，自动回滚发布。这种工程闭环才能发挥监控数据的价值，否则采集的数据只是躺在后台里的数字而已。
接入 Datadog 的完整流程并不复杂，难点在于让监控数据与业务上下文结合。通过本文的插件封装、路由追踪和敏感信息脱敏，你应该已经能在一个 Vue 3 项目中稳定运行 RUM 了。下一步可以根据实际业务定义一个标准埋点字典，让产品经理和前端开发共同维护，这样才能确保每个关键交互都有数据可查。