在追踪前端 JS 错误时,需要通过追踪 JS 代码堆栈来定位报错位置。RUM 支持采集 JS 错误堆栈信息,通过上传的 SourceMap 文件即可解析 JS 堆栈。但由于 RUM 支持管理多个版本的 SourceMap 文件,仅通过文件名往往无法准确关联异常堆栈中的 JS 文件和对应的 SourceMap 文件。通过使用 RUM 前端构建工具插件,可以向打包生成的 JS 文件和 SourceMap 文件注入 UUID,以在两者间建立双向关联,从而在打开 RUM 异常明细界面时能够自动解析和展示堆栈信息,无需手动选择 SourceMap 文件。
前提条件
确保您的Web应用已接入用户体验监控,具体操作,请参见接入Web & H5应用。
支持的前端构建工具类型
目前 RUM Web & H5 SourceMap 自动解析功能支持以下前端构建工具:
Webpack
Vite
使用RUM前端构建工具插件
Webpack
安装 RUM Webpack 前端构建工具插件 npm 包。
npm install @arms/rum-webpack-plugin --save
在 Webpack 配置文件中应用 RUM 前端构建工具插件,并通过设置 devtool 属性使 Webpack 生成 SourceMap 文件。
import { RumWebpackPlugin } from '@arms/rum-webpack-plugin' const config = { plugins: [new RumWebpackPlugin()], devtool: 'source-map', }; export default config
Vite
安装 RUM Vite 前端构建工具插件 npm 包。
npm install @arms/rum-vite-plugin --save
在 Vite 配置文件中应用 RUM 前端构建工具插件,并通过设置 build.sourcemap 属性使 Vite 生成 SourceMap 文件。
import { rumVitePlugin } from '@arms/rum-vite-plugin' export default defineConfig({ plugins: [rumVitePlugin()], build: { sourcemap: true, }, });
自动上传 SourceMap 文件
为简化操作流程,您可以配置 RUM 前端构建工具插件在注入 UUID 后自动将 SourceMap 文件上传至 RUM 的 OSS 存储中。
配置自动上传 SourceMap 操作过程中需要获取账号的AccessKey ID 和 AccessKey Secret,AccessKey是访问阿⾥云 API 的密钥,出于安全考虑,强烈建议您使用RAM用户完成以下操作,并妥善保管AccessKey。
步骤一:打开批量上传开关
为获取 RUM OSS 的写⼊权限,您需要使用RAM用户登录ARMS控制台,并在目标 RUM 应用的应用设置页面开启 OSS 批量上传文件开关。
步骤二:获取RAM用户的AccessKeyID 和 AccessKeySecret
为将⽂件上传⾄ RUM OSS 服务,您需要向 RUM 前端构建⼯具插件提供上一步RAM用户的 AccessKey ID 和 AccessKey Secret。
创建时AccessKey,使用场景需选择本地开发环境中使用。具体获取方法,请参见创建RAM用户的AccessKey。
步骤三:配置插件
在 RUM 前端构建工具插件配置中填入 RUM 应用 ID、AccessKey ID、AccessKey Secret 、版本号(用于在 RUM 控制台中对上传的 SourceMap 文件进行分组管理,默认为 1.0.0)以及应用所在的 Region(默认为 cn-hangzhou)。
Webpack
import { RumWebpackPlugin } from '@arms/rum-webpack-plugin'
const config = {
plugins: [new RumWebpackPlugin({
pid: '', // RUM 应用 ID
accessKeyId: '',
accessKeySecret: '',
version: '',
region: ''
})],
devtool: 'source-map',
};
export default config
Vite
import { rumVitePlugin } from '@arms/rum-vite-plugin'
export default defineConfig({
plugins: [rumVitePlugin({
pid: '', // RUM 应用 ID
accessKeyId: '',
accessKeySecret: '',
version: '',
region: ''
})],
build: {
sourcemap: true,
},
});
手动上传 SourceMap 文件
步骤一:构建项目
通过前端构建工具提供的 build 命令构建项目代码后,RUM 前端构建工具会在 JS 文件和对应的 SourceMap 文件中注入 UUID。
SourceMap 文件中增加 debugId 字段,表示 SourceMap 文件 UUID 注入成功。
{
"version": 3,
"file": "index.js",
"mappings": "AAAAA,QAAQC,IAAI",
"sources": [
"webpack://examples/./src/index.js"
],
"sourcesContent": [
"console.log('Hello World!');\n"
],
"names": [
"console",
"log"
],
"sourceRoot": "",
"debugId": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"
}
通过浏览器打开页面后,能够在全局对象 Window 上观察到 _armsRumDebugIds 属性则表示 JS 文件 UUID 注入成功。
步骤二:手动上传 SourceMap 文件
若不使用自动上传功能,可在 RUM 控制台进行手动上传。在应用设置页面的文件管理区域,上传注入了 UUID的 SourceMap 文件,UUID 列出现对应的 UUID 代表解析成功。
步骤三:自动解析
通过异常统计页面进入目标异常的异常明细页面,堆栈信息中的每一行都会显示其通过 RUM 前端构建工具插件注入的 UUID,显示 "-" 则代表没有成功上报 UUID。
若已上传了带有对应 UUID 的 SourceMap 文件,堆栈信息中的第一行将会自动解析并展示报错的源代码位置,其他行可通过单击所在行展开自动解析结果。
RUM 前端构建工具插件版本说明
版本号 | 说明 | |
0.0.8 | 增加构建项目代码后自动上传 SourceMap 文件功能。 | |
0.0.5 | 支持 Webpack、Vite 前端构建工具,通过注入 UUID 在 JS 文件和对应 SourceMap 文件间建立双向联系。 |