Application Real-Time Monitoring Service:Web および H5 プラグインによるソースマップの自動アップロード

Webpack

1. RUM Webpack ビルドツールプラグインの npm パッケージをインストールします。

   npm install -D @arms/rum-webpack-plugin

2. Webpack プラグインを組み込み、設定します。

   プロダクションビルドでは、JavaScript 出力にソースマップ URL を公開しないように hidden-source-map を使用してください。

   const { rumWebpackPlugin } = require('@arms/rum-webpack-plugin');
   
   module.exports = {
     mode: 'production',
     devtool: 'hidden-source-map',
     plugins: [
       rumWebpackPlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   };

   Webpack は、mode === 'development' または NODE_ENV === 'development' の場合、ソースマップの処理とアップロードをスキップします。プロダクション用ソースマップをアップロードするには、development 以外のビルドを使用してください。

Vite

1. RUM Vite ビルドツールプラグインの npm パッケージをインストールします。

   npm install -D @arms/rum-vite-plugin

2. Vite プラグインを組み込み、設定します。

   import { defineConfig } from 'vite';
   import { rumVitePlugin } from '@arms/rum-vite-plugin';
   
   export default defineConfig({
     build: {
       sourcemap: true,
     },
     plugins: [
       rumVitePlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   });

   build.sourcemap は true または 'hidden' に設定できます。'inline' には設定しないでください。

ソースマップファイルの確認

clearSourceMap: false の場合は、ビルド出力ディレクトリ内の .map ファイルを開きます。トップレベルに正しい形式の debugId が存在すれば、注入は成功です。例：

{
  "version": 3,
  "file": "index.js",
  "sources": ["webpack://app/src/index.ts"],
  "sourcesContent": ["throw new Error('test');"],
  "mappings": "AAAA",
  "debugId": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"
}

sourcesContent は存在し、かつ空でない必要があります。ない場合や空の場合、RUM はファイル位置の復元しかできず、ソースコードのコンテキストを表示できないことがあります。

ブラウザーランタイムの確認

デプロイ済みのページを開き、ブラウザーのコンソールで次を実行します：

window._armsRumDebugIds;

返されたオブジェクトに UUID のマッピングが含まれている場合、現在のページ上の JavaScript ファイルが debugId を登録したことになります。プラグインは、iframe およびマイクロフロントエンドのシナリオをサポートするために、debugId を globalThis、self、global、document.defaultView、およびアクセス可能な親ウィンドウやトップウィンドウにも登録します。

アップロード結果の確認

RUM アプリケーションの [ファイル管理] ページで、以下を確認します：

• ソースマップファイルが表示されていること。

• ファイルのバージョンは、プラグインで設定されたversion と一致します。

• UUID は、ビルド出力内の debugId と一致します。

ビルドログでソースマップファイルが見つからないと報告される

ビルドツールが個別の .map ファイルを生成しているかどうかを確認してください。インラインまたは eval ソースマップを使用せず、JavaScript ファイルと .map ファイルのファイル名とパスが後処理スクリプトによって変更されていないことを確認してください。

アップロードは成功したが、例外の詳細ページにソースコードが表示されない

次の順に確認してください：

1. .map ファイルには、空ではない sourcesContent が含まれていますか？

2. ソースマップの debugId は、例外スタックトレースで報告される UUID と一致しますか？

3. workspace、serviceId、version、および region は、ターゲットの RUM アプリケーションと一致していますか？

4. アップロードしたファイルは、対象のアプリケーションの[ファイル管理]ページに表示されますか？

Webpack がファイルをアップロードしない

mode も NODE_ENV も development に設定されていないこと、および外部ソースマップファイルが生成されていることを確認してください。

カスタム OSS バケットを使用できますか？

いいえ。アップロードエンドポイントとフォームパラメータは OpenAPI によって返されます。プラグインではバケット設定を公開していません。

ソースマップがインターネット上で公開されるのを防ぐにはどうすればよいですか？

Webpack では、hidden-source-map を使用します。また、clearSourceMap: true に設定します。アップロードが成功するたびに、プラグインは対応するローカルの .map ファイルを削除します。

現在の Node.js バージョンが特定の機能をサポートしていないというエラーが表示される

ビルド環境を Node.js 20 LTS または Node.js 22 以降にアップグレードしてください。このプラグインが使用する依存関係は、Node.js 18 や 21 などの古いバージョンをサポートしていません。

ソースマップファイルがサイズ制限を超える

1つのソースマップファイルのサイズは 50 MiB を超えることはできません。コード分割、インラインソースコンテンツの削減、またはビルド設定の調整によって、ファイルサイズを削減できます。ソースコードのコンテキストを表示するには、十分な sourcesContent を保持する必要があります。

チャンク URL に括弧が含まれると、ソースマップの自動マッチングに失敗する

webpack チャンク URL に、Next.js App Router で使用されるルートグループ形式 (/app/(groupName)/page/) のような、丸括弧などの特殊文字が含まれている場合、ARMS は報告された JS エラーの binary_images フィールドから UUID を正しく解析できません。その結果、ソースマップの自動照合が失敗します。同じ例外内の、丸括弧を含まないチャンク URL は正常に解析されます。

これは ARMS の既知の解析上の制限です。この問題を回避するには、webpack を設定してチャンクの命名パスから括弧を除外します。たとえば、Next.js のルートグループディレクトリの名前を変更して、(groupName) 形式にならないようにします。