ソースマップ

概要

ソースマップビルドプラグインは、ビルド中に JavaScript ソースマップを Datadog に自動アップロードし、Error Tracking および RUM におけるスタックトレースの難読化解除を可能にします。これにより、ソースマップアップロードのために datadog-ci sourcemaps upload を手動で実行したり CI/CD パイプラインを構成したりする必要がなくなります。

このプラグインはビルドプロセスにフックし、ビルド出力から対応する .map ソースマップファイルを持つすべての .js ファイルを検出し、Git メタデータと共に Datadog にアップロードします。デバッグ ID またはサービスとバージョンによって、ソースマップをイベントに関連付けることができます。

前提条件

  • auth.apiKey または DATADOG_API_KEY 環境変数で設定された Datadog API キー。
  • バンドラー設定で有効になっているソースマップ。このプラグインはソースマップをアップロードしますが、生成は行いません。バンドラー固有のソースマップ生成設定については、JavaScript ソースマップをアップロードする を参照してください。
  • デバッグ ID によるアップロードを行う場合は、ビルドプラグインでデバッグ ID のインジェクションを有効にしてください。
  • サービスとバージョンによるアップロードを行う場合は、プラグイン構成と一致する service および version パラメーターを使用して RUM SDK を初期化してください。
  • インストールおよびバンドラーに登録されている Datadog ビルドプラグイン。インストール手順については、ビルドプラグイン を参照してください。

構成

以下の環境変数は、構成値を上書きします。

  • DATADOG_SITE または DD_SITE: インテーク URL の auth.site を上書きします。
  • DATADOG_SOURCEMAP_INTAKE_URL: インテーク URL 全体を直接上書きします。

デバッグ ID またはサービスとバージョンのいずれかのソースマップアップロード照合方法を選択してください。これらのアップロード方法は相互に排他的です。

デバッグ ID は、バンドル URL、サービス、またはバージョンに依存することなく、各 JavaScript バンドルとそのソースマップを関連付けます。新しい構成にはこの方法を使用してください。

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

sourcemaps で以下のオプションを構成します。

パラメータータイプ必須デフォルト説明
debugIdブール値Yesなし各 JavaScript バンドルにデバッグ ID を挿入するには、true に設定します。
uploadブール値Yes (アップロード)falseビルド中にソースマップをアップロードするには、true に設定します。省略した場合、プラグインはデバッグ ID の挿入のみを行います。
bailOnErrorブール値Nofalsetrue の場合、ソースマップのアップロードエラーが発生するとビルドが失敗します。
dryRunブール値Nofalsetrue の場合、プラグインは Datadog にデータを送信することなくアップロードプロセスを実行します。構成の確認にはこれを使用してください。
maxConcurrency数値No20同時にアップロードできるソースマップの最大数。

debugId と upload を true に設定して、ビルド中にデバッグ ID を挿入し、ソースマップをアップロードします。

    // webpack.config.js
const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
  plugins: [
    datadogWebpackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};

    // vite.config.js
import { datadogVitePlugin } from '@datadog/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    datadogVitePlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
});

    // esbuild.config.js
const { datadogEsbuildPlugin } = require('@datadog/esbuild-plugin');

require('esbuild').build({
  plugins: [
    datadogEsbuildPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
});

    // rollup.config.js
import { datadogRollupPlugin } from '@datadog/rollup-plugin';

export default {
  plugins: [
    datadogRollupPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};

    // rspack.config.js
const { datadogRspackPlugin } = require('@datadog/rspack-plugin');

module.exports = {
  plugins: [
    datadogRspackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};

    サービスとバージョン

    サービスとバージョンの照合を使用してソースマップをアップロードするには、errorTracking.sourcemaps オブジェクトを構成します。

    パラメータータイプ必須デフォルト説明
    service文字列Yesなしサービス名。RUM SDK の service 初期化パラメーターと一致する必要があります。
    releaseVersion文字列Yes (metadata.version が設定されている場合を除く)なしリリースバージョン。RUM SDK の version 初期化パラメーターと一致する必要があります。
    minifiedPathPrefix文字列Yesなしミニファイされた JavaScript ファイルが提供される URL またはルート相対パスのプレフィックス。たとえば、https://example.com/static/ や /static/ などです。
    bailOnErrorブール値Nofalsetrue の場合、ソースマップのアップロードエラーが発生するとビルドが失敗します。
    dryRunブール値Nofalsetrue の場合、プラグインは Datadog にデータを送信することなくアップロードプロセスを実行します。構成の確認にはこれを使用してください。
    maxConcurrency数値No20同時にアップロードできるソースマップの最大数。
    // webpack.config.js
const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
  plugins: [
    datadogWebpackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      errorTracking: {
        sourcemaps: {
          service: 'my-application',
          releaseVersion: '1.0.0',
          minifiedPathPrefix: 'https://example.com/static/',
        },
      },
    }),
  ],
};
    この例ではwebpackを使用します。構成オブジェクトは、サポートされているすべてのバンドラーで同一です。異なるのはインポートとプラグインの関数名のみです。バンドラーのインストール手順については、ビルドプラグインを参照してください。

    Error Tracking のスタックトレースにインラインソースコードも表示するには、サービスとバージョンのソースマップのアップロードを ソースコードコンテキスト プラグインと組み合わせて使用してください。

    参考資料

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

    JavaScript ソースマップをアップロードする (手動方式)ドキュメント more more Error Trackingドキュメント more more Datadog ビルドプラグイン GitHub リポジトリソースコード more more