概要

フロントエンドの 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 によるコード分割を参照してください。

ソースマップをアップロードする

ソースマップをアップロードするには、Debug ID (推奨) またはサービスとバージョンのいずれかの照合方法を選択します。Debug ID を使用すると、複数マイクロフロントエンド間でのソースマップ解決が可能になります。

Debug ID は、バンドル URL、サービス、またはリリースバージョンに依存せずに、JavaScript バンドルとそのソースマップを関連付けます。

以下のアップロード方法のいずれかを選択します。

Datadog ビルドプラグイン

Datadog ビルドプラグインは、ビルド中に Debug ID を埋め込み、ソースマップを直接アップロードできます。datadog-ci を別途インストールまたは実行する必要はありません。

Debug ID のサポートには、Datadog ビルドプラグインバージョン 3.3.0 以降が必要です。

ビルドプラグインで Debug ID のインジェクションとソースマップのアップロードを有効にします。

datadogWebpackPlugin({
  auth: {
    apiKey: process.env.DATADOG_API_KEY,
    site: 'datadoghq.com',
  },
  sourcemaps: {
    debugId: true,
    upload: true,
  },
});

プラグインは、対応する JavaScript バンドルに埋め込まれた Debug ID を使用して、各ソースマップをアップロードします。

この例では Webpack を使用します。ほかのサポートされているバンドラーのインストールおよび構成手順については、「Datadog ビルドプラグイン」を参照してください。

datadog-ci

Debug ID のサポートには、@datadog/datadog-ci バージョン 5.24.0 以降が必要です。

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

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

  3. US1 以外のサイトの場合は、Datadog サイトを指定して DD_SITE をエクスポートし、CLI を構成します。

  4. ビルド後に Debug ID を埋め込みます。

    datadog-ci sourcemaps inject /path/to/dist
    
  5. ソースマップと対応する JavaScript バンドルをアップロードします。

    datadog-ci sourcemaps upload /path/to/dist --debug-id
    

--service、--release-version、または --minified-path-prefix を --debug-id と一緒に渡さないでください。

inject コマンドは、JavaScript バンドルとソースマップをその場で変更します。ビルドの実行後で、かつ SRI ハッシュ、圧縮済みアセット、署名、チェックサムマニフェストといった、バイト列に依存する成果物を生成する前に実行してください。アップロードするものと同じ変更済みアーティファクトをデプロイします。

サービスとバージョンを使用してソースマップをアップロードするには、datadog-ci sourcemaps upload コマンドを実行するステップを CI パイプラインに追加します。このコマンドは dist ディレクトリおよびそのサブディレクトリをスキャンし、関連する縮小化されたファイルとともにソースマップを自動的にアップロードします。

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

  2. 専用の Datadog API キーを作成し、DD_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 キーを作成し、DD_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を指定します。

Explore RUM Debug Symbols ページで、アップロードされたすべてのシンボルを確認してソースマップを管理します。

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

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

Debug ID アップロードをトラブルシューティングする

ローカルソースマップを検査する

特定の Debug ID のローカルソースマップを見つけるには、以下を実行します。

datadog-ci sourcemaps find /path/to/dist --debug-id 12345678-1234-1234-1234-123456789abc

Debug ID を含まないソースマップを見つけるには、以下を実行します。

datadog-ci sourcemaps find /path/to/dist --missing-debug-id

find コマンドは、ローカルの *.js.map ファイルのみを検査します。Datadog がアーティファクトを受信したかどうかは確認しません。

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

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

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

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

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

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

参考資料