JavaScript ソースマップのアップロード

JavaScript ソースマップのアップロード

概要

フロントエンドの JavaScript ソースコードが縮小されている場合は、ソースマップを Datadog にアップロードして、さまざまなスタックトレースを難読化できるようにする必要があります。その後、特定のエラーについて、ファイルパス、行番号、および関連するスタックトレースの各フレームのコードスニペットにアクセスできます。

コードのインスツルメンテーション

ソースコードを縮小するときに、関連するソースコードを sourcesContent 属性に直接含むソースマップを生成するように、JavaScript バンドルを構成する必要があります。一般的な JavaScript バンドルのコンフィギュレーションを以下で確認してください。また、関連する縮小ファイルのサイズで拡張された各ソースマップのサイズが、__上限の 50MB__を越えないようにしてください。よく使用される JavaScript バンドルのコンフィギュレーション例については以下を参照してください。

SourceMapDevToolPlugin という名前の組み込みの Webpack プラグインを使用して、ソースマップを生成できます。webpack.config.js ファイルで構成する方法を以下で確認してください。

// ...
const webpack = require('webpack');

module.exports = {
  mode: 'production',
  devtool: false,
  plugins: [
    new webpack.SourceMapDevToolPlugin({
      noSources: false,
      filename: '[file].map'
    }),
    // ...
  ],
  optimization: {
    minimize: true,
    // ...
  },
  // ...
};

: TypeScript を使用している場合は、tsconfig.json ファイルを構成するときに、必ず compilerOptions.sourceMaptrue に設定してください。

Parcel は、ビルドコマンドを実行すると、デフォルトでソースマップを生成します: parcel build <entry file>

アプリケーションをビルドした後、バンドラーは、ほとんどの場合 dist という名前のディレクトリを生成し、対応するソースマップと同じ場所に縮小された JavaScript ファイルを配置します。以下の例を確認してください。

./dist
    javascript.364758.min.js
    javascript.364758.js.map
    ./subdirectory
        javascript.464388.min.js
        javascript.464388.js.map
例えば、javascript.364758.min.jsjavascript.364758.js.mapのファイルサイズの合計が 50MB の制限値を超えた場合は、バンドラーでソースコードを複数の小さなブロックに分割するよう構成してファイルサイズを縮小してください (WebpackJS での操作方法はこちらを参照してください)。

ソースマップのアップロード

ソースマップをアップロードする最良の方法は、CI パイプラインに追加のステップを追加し、Datadog CLI から専用コマンドを実行することです。dist ディレクトリとそのサブディレクトリをスキャンして、関連する縮小ファイルを含むソースマップを自動的にアップロードします。フローは次のとおりです。

  1. package.json ファイルに @datadog/datadog-ci を追加します (必ず最新バージョンを使用してください)。
  2. 新しい専用の Datadog API キーを作成し、DATADOG_API_KEY という名前の環境変数としてエクスポートします。
  3. 次のコマンドを実行します。
datadog-ci sourcemaps upload /path/to/dist \
    --service=my-service \
    --release-version=v35.2395005 \
    --minified-path-prefix=https://hostname.com/static/js
  1. package.json ファイルに @datadog/datadog-ci を追加します (必ず最新バージョンを使用してください)。
  2. 新しい専用の Datadog API キーを作成し、DATADOG_API_KEY という名前の環境変数としてエクスポートします。
  3. 2 つの追加環境変数 export DATADOG_SITE="datadoghq.eu" および export DATADOG_API_HOST="api.datadoghq.eu" をエクスポートして、EU リージョンにファイルをアップロードするために CLI を構成します。
  4. 次のコマンドを実行します。
datadog-ci sourcemaps upload /path/to/dist \
    --service=my-service \
    --release-version=v35.2395005 \
    --minified-path-prefix=https://hostname.com/static/js

: CLI は、CI のパフォーマンスのオーバーヘッドを最小限に抑えるために、必要な数のソースマップを非常に短い時間 (通常は数秒) でアップロードするように最適化されています。

このコマンドをサンプルの dist ディレクトリ (前のセクションを参照) に対して実行することにより、Datadog はサーバーまたは CDN が https://hostname.com/static/js/javascript.364758.min.js および https://hostname.com/static/js/subdirectory/javascript.464388.min.js で JavaScript ファイルを配信することを期待します。ユーザーの 1 人のセッションでエラーが発生すると、RUM SDK は即座にそれを収集します。指定されたエラーがこれらの URL の 1 つからダウンロードされ、version:v35.2395005 および service:my-service のタグが付けられたファイルで発生した場合は常に、関連するソースマップを使用してスタックトレースを難読化します (この場合、javascript.464388.js.map ファイル)。

: エラー追跡 UI でスタックトレースを正しく非縮小するために機能するのは、拡張子が .js.map のソースマップのみです。 .mjs.map など、他の拡張子のソースマップは許容されますが、スタックトレースを非縮小しません。

JavaScript ソースファイルは、環境 (たとえばステージングまたは本番) に基づき異なるサブドメインから利用できます。関連するソースマップをアップロードしたら、完全な URL の代わりに絶対的なプレフィックスパスを使用する (https://hostname.com/static/js の代わりに /static/js を指定) ことで複数のサブドメインに機能させることが可能です。

エラーを簡単にトラブルシューティング

ファイルパスと行番号にアクセスできないため、縮小スタックトレースは役に立ちません。コードベースのどこで何かが起こっているのかを把握するのは簡単ではありません。さらに、コードスニペットは依然として縮小されているため (変換されたコードの 1 行が長い)、トラブルシューティングプロセスがさらに困難になります。縮小スタックトレースの例を以下に示します。

それどころか、非縮小スタックトレースは、高速でシームレスなトラブルシューティングに必要なすべてのコンテキストを提供します。

エラー追跡非縮小スタックトレース

その他の参考資料