Web & H5 端 SourceMap 自動解析 - Application Real-Time Monitoring Service

在追蹤前端 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

為防止調試時重複上傳，使用Webpack打包時僅Production模式會自動上傳SourceMap。

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 檔案間建立雙向聯絡。