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

このドキュメントは最新ではありません。最新版はこちらをクリックして英語版をご覧ください。

概要

フロントエンドの JavaScript ソースコードが縮小化されている場合は、スタックトレースの難読化を解除するために、Datadog にソースマップをアップロードします。任意のエラーについて、ファイルパス、行番号、関連するスタックトレースの各フレームのコードスニペットにアクセスすることができます。Datadog は、スタックフレームをリポジトリ内のソースコードにリンクすることもできます。

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

ソースコードを縮小するときに、sourcesContent 属性に関連するソースコードを直接含むソースマップを生成するように JavaScript バンドラーを構成します。

各ソースマップのサイズと関連する縮小化されたファイルのサイズの合計が 500 MB の制限を超えないようにしてください。

一般的な 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.sourceMap を true に設定します。

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

    build.sourcemap ファイル内で vite.config.js オプションを構成することにより、ソースマップを生成できます。

    構成サンプルを参照してください。

    // vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    sourcemap: true, // generates .js.map files
    minify: 'terser', // or 'esbuild'
  }
})

    注: TypeScript を使用している場合は、tsconfig.json ファイル内で compilerOptions.sourceMap が true に設定されていることを確認してください。

    アプリケーションをビルドした後、バンドラーは縮小化された JavaScript ファイルを、対応するソースマップと同じ場所に配置したディレクトリ (通常 dist という名前) を生成します。

    次の例をご覧ください。

    ./dist
    javascript.364758.min.js
    javascript.364758.js.map
    ./subdirectory
        javascript.464388.min.js
        javascript.464388.js.map
    javascript.364758.min.js と javascript.364758.js.map のファイルサイズの合計が 500 MB の制限を超える場合は、バンドラーを構成してソースコードを複数の小さなチャンクに分割するようにし、サイズを削減します。詳細については、WebpackJS によるコード分割を参照してください。

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

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

    1. package.json ファイルに @datadog/datadog-ci を追加します (最新バージョンを使用していることを確認してください)。

    2. 専用の Datadog API キーを作成し、DATADOG_API_KEY という名前の環境変数としてエクスポートします。

    3. アプリケーションで、1 サービスにつき 1 回、以下のコマンドを実行します。

      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. CLI を構成して サイトにファイルをアップロードできるようにするため、export DATADOG_SITE= および export DATADOG_API_HOST=api.の 2 つの環境変数をエクスポートします。
    4. アプリケーションで、1 サービスにつき 1 回、以下のコマンドを実行します。
      datadog-ci sourcemaps upload /path/to/dist \
  --service my-service \
  --release-version v35.2395005 \
  --minified-path-prefix https://hostname.com/static/js

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

    注: バージョンに変更がない場合、ソースマップを再アップロードしても既存のものはオーバーライドされません。

    --service および --release-version パラメーターは、Error Tracking イベント、RUM イベント、およびブラウザーログの service および version タグと一致する必要があります。これらのタグの設定方法についての詳細は、Browser SDK 初期化ドキュメントまたはBrowser ログ収集ドキュメントを参照してください。

    アプリケーションで複数のサービスを定義している場合、アプリケーション全体のソースマップのセットが 1 つであっても、サービスの数だけ CI コマンドを実行します。

    例の dist ディレクトリに対してコマンドを実行することで、Datadog はサーバーまたは CDN が JavaScript ファイルを https://hostname.com/static/js/javascript.364758.min.js および https://hostname.com/static/js/subdirectory/javascript.464388.min.js で配信することを期待しています。

    .js.map 拡張子を持つソースマップのみが、スタックトレースを正しく縮小化解除するために機能します。.mjs.map のような他の拡張子を持つソースマップも受け入れられますが、スタックトレースは縮小化解除されません。

    異なるサブドメインから同じ JavaScript ソースファイルを提供する場合、関連するソースマップを一度アップロードし、完全な URL の代わりに絶対プレフィックスパスを使用することで複数のサブドメインで動作するようにしてください。例えば、 /static/js を https://hostname.com/static/jsの代わりに指定します。

    アップロードされたすべてのシンボルを確認し、ソースマップを管理するには、RUM デバッグシンボルを確認ページを参照してください。

    Git 作業ディレクトリ内で datadog-ci sourcemaps upload を実行すると、Datadog はリポジトリメタデータを収集します。datadog-ci コマンドは、リポジトリの URL、現在のコミットハッシュ、およびソースマップに関連するリポジトリ内のファイルパスのリストを収集します。Git メタデータ収集の詳細については、datadog-ci ドキュメントを参照してください。

    Datadog は、縮小化解除されたスタックフレームにソースコードへのリンクを表示します。

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

    ファイルパスと行番号にアクセスできない場合、縮小化されたスタックトレースはコードベースのトラブルシューティングには役立ちません。また、コードスニペットは縮小化されており (つまり、変換されたコードが 1 行の長い形式になっています)、トラブルシューティングがより困難になります。

    次の例では、縮小化されたスタックトレースを表示しています。

    Error Tracking 縮小化スタックトレース

    一方、縮小化解除されたスタックトレースは、迅速でシームレスなトラブルシューティングに必要なすべてのコンテキストを提供します。ソースコードに関連するスタックフレームについて、Datadog はリポジトリへの直接リンクも生成します。

    Error Tracking 縮小化解除スタックトレース

    参考資料

    お役に立つドキュメント、リンクや記事:

    エラー追跡を開始するドキュメント more more エクスプローラーでエラー追跡データを視覚化するドキュメント more more ソースマップのコマンドリファレンスソースコード more more JavaScript Web Applications の RUM を使用してエラーを追跡するラーニングセンター more more