setup-browser-sdk-sourcemaps

Name: setup-browser-sdk-sourcemaps
Author: datadog-labs

github.com/datadog-labs開発18593 回インストール1 日前に更新

setup-browser-sdk-sourcemaps について

setup-browser-sdk-sourcemapsは、フロントエンドビルドでDatadogのsourcemapアップロードを設定する手順を案内するスキルです。対応バンドラーやデプロイ情報を確認し、Next.jsなど対象外の構成も明示します。

主な機能

01対応バンドラー設定の検出
02必須のserviceとリリース値の確認
03sourcemap生成とアップロードの設定
04APIキーをビルドシークレットで管理
05デプロイパスとCI設定への対応
06未対応または曖昧な構成の提示

活用シーン

01ViteビルドへのDatadog sourcemap追加
02webpackやRollupのアップロード設定
03フロントエンドエラーのソース追跡
04ビルドシークレットと配信パスの確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/datadog-labs/agent-skills --skill setup-browser-sdk-sourcemaps

インストール後、Claude Code で/setup-browser-sdk-sourcemapsを入力して読み込まれたか確認します。

詳細

ビルドプラグインを使ってDatadogのソースマップアップロードを設定する

Datadogビルドプラグインを使って、フロントエンドプロジェクトのビルド時にソースマップをアップロードします。ソースマップはビルドの一部としてアップロードされるため、デプロイするたびに、RUMとError Trackingで難読化されていないスタックトレースを確認できます。Gitのメタデータは自動的に付与され、エラーをソースファイルに結び付けます。

手順1～7を順番に実行してください。

作業を始める前に： 以下の各手順に対応するToDo項目を、ちょうど7つ作成してください。7つすべてのToDoを作成するまで、実装を始めないでください。手順をまとめたり、統合したりしないでください。

値を推測してはいけません。 3つのフィールド（service、releaseVersion、minifiedPathPrefix）は、実際のアプリのデプロイ方法に一致している必要があります。リポジトリから値を読み取れない場合は、作業を止めてユーザーに確認してください。プレースホルダーやTODO、推測したホスト名は入力しないでください。

対象範囲

対象：esbuild、Rollup、Rspack、Vite、webpackでビルドされるプロジェクト。これらのいずれかを独自の設定ファイルで直接公開しているメタフレームワーク（例：Remix／React Router v7以降のフレームワークモード、SvelteKit、vite.config.ts／nuxt.config.tsのvite:キーを介したNuxt）も含みます。以下の手順1で設定ファイルを検索し、実際のバンドラー設定が見つかった場合、上位のメタフレームワークに関係なく、通常どおりその設定ファイルにプラグインを組み込んでください。

対象外：Next.jsとTurbopack。上記のメタフレームワークとは異なり、Next.jsではプラグインを組み込める通常のwebpack／Turbopack設定の公開範囲がなく、Next.jsまたはTurbopackとの統合機能もありません。これらの場合は、代わりにpostbuildスクリプトでdatadog-ci sourcemaps upload CLIを使用してください。next.config.jsにwebpackプラグインを組み込もうとしないでください。

ここに挙げられていない別のメタフレームワークをプロジェクトで使用しており、手順1で編集可能な通常のバンドラー設定ファイルが見つからない場合は、対応状況を推測せず、作業を止めてユーザーに確認してください。

手順1：バンドラーを検出する

バンドラーの設定ファイルを検索します。

find . -maxdepth 1 \( -name "vite.config.*" -o -name "rollup.config.*" -o -name "webpack.config.*" -o -name "rspack.config.*" -o -name "esbuild.config.*" \) 2>/dev/null
grep -l -E "\"(vite|rollup|webpack|@rspack/core|esbuild)\"" package.json

findを使用し、これらのグロブパターンを直接指定したlsは使わないでください。zshでは、複数のグロブパターンを指定したlsは、いずれかのパターンに一致するものがないと、2>/dev/nullを付けてもno matches foundで中断します。これは、lsが実行される前のシェルによる単語展開時にエラーが発生するためです。findは内部で独自にパターンマッチングを行うため、bashとzshのどちらでも同じように動作し、バンドラー設定がない場合もエラーではなく何も返しません。

結果を次のように対応付けます。

設定ファイル	バンドラー	インストールするパッケージ	名前付きエクスポート
`vite.config.{js,ts,mjs}`	Vite	`@datadog/vite-plugin`	`datadogVitePlugin`
`webpack.config.{js,ts,mjs}`	webpack	`@datadog/webpack-plugin`	`datadogWebpackPlugin`
`rollup.config.{js,ts,mjs}`	Rollup	`@datadog/rollup-plugin`	`datadogRollupPlugin`
`rspack.config.{js,ts,mjs}`	Rspack	`@datadog/rspack-plugin`	`datadogRspackPlugin`
esbuildのビルドスクリプト	esbuild	`@datadog/esbuild-plugin`	`datadogEsbuildPlugin`

対応するバンドラーのバージョン：

バンドラー	対応範囲
esbuild	すべて
Rollup	`>= 3 < 5`
Rspack	`1.x`または`2.x`
Vite	`>= 5 <= 8`
webpack	`>= 5 < 6`

次の場合は作業を止めて、ユーザーに確認してください： バンドラー設定が見つからない場合、複数見つかった場合（モノレポの場合は、どのアプリに組み込むかを確認してください）、Next.jsまたはTurbopackが検出された場合（上記のとおり対象外）、またはバンドラーのバージョンが対応範囲外の場合。

ステップ 2：必須の 3 つの値を収集する

この 3 つの値がないと、プラグインはビルドできません。リポジトリから値を確認し、確認できないものがあればユーザーに尋ねてください。

service — datadogRum.init() に渡される service と一致している必要があります。Datadog はこの値を使って、アップロードされたソースマップを受信したエラーと照合します。値が一致しないと、ソースマップは正常にアップロードされますが、使用されることはありません。

grep -rn "datadogRum.init" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 15

リポジトリ内のどこにも datadogRum.init() の呼び出しが見つからない場合は、そこで作業を止めてください。このスキルは既存の RUM 設定にソースマップのアップロードを追加するもので、RUM 自体の計測設定は行いません。まず Browser RUM を設定してから、このスキルを再実行するようユーザーに伝えてください。

datadogRum.init() に service がない場合は、そこで作業を止めてユーザーに伝えてください。service がないとソースマップを照合できないため、先に RUM の初期化に追加する必要があります。

releaseVersion — datadogRum.init() に渡される version と一致している必要があります。通常は git コミット SHA、リリースタグ、または CI ビルド ID です。ここで設定するか、トップレベルの metadata.version として一度だけ設定できます。両方が設定されていて値が異なる場合、ビルドは sourcemaps.releaseVersion must match metadata.version when both are configured というエラーで失敗します。

minifiedPathPrefix — ビルドされた JS が配信される URL のプレフィックスです。完全な URL にするか、/ で始める必要があります。そうでない場合、ビルドは sourcemaps.minifiedPathPrefix must be a valid URL or start with '/' というエラーで失敗します。

例：dist/main.js が https://example.com/static/main.js で配信される場合、minifiedPathPrefix は https://example.com/static/ または /static/ です。JS がサーバールートから配信される場合は、/ が有効です。

この項目は最も間違いやすく、バンドラーの設定だけからは判断できません。ユーザーに尋ねる前に、実際のデプロイ方法をリポジトリで確認してください。

まず、バンドラー自体の base／publicPath／baseURL 設定を確認してください。設定されていれば、それで答えがわかります。
それ以外の場合は、実際のデプロイコマンドと対象ディレクトリをデプロイ／CI 設定で確認してください：.github/workflows/*.yml、.gitlab-ci.yml、vercel.json、netlify.toml、wrangler.toml、Dockerfile。デプロイ手順でバンドラーの出力ディレクトリをそのまま公開している場合（例：pages deploy ./dist、netlify deploy --dir=build）、プレフィックスはそのディレクトリのルートが配信される URL です（サーバールートにデプロイされる場合は /）。Vite の assets/ のようなアセット用サブフォルダーは追加しないでください。プラグインは出力ディレクトリ内の各ファイルのパスを追加するため、/assets/ を指定すると /assets/assets/index-*.js がアップロードされます。
ステップ 2 の答えを上書きする可能性のあるパス書き換え設定を確認してください：Cloudflare の _routes.json／_redirects、Netlify の _redirects、vercel.json の Vercel rewrites。いずれかがある場合は、ビルド出力のパスではなく、書き換えルールからプレフィックスを再導出してください。
上記で判断できない場合（コミットされたデプロイ設定がない、カスタムドメイン／CDN がホスティングのダッシュボードでしか設定されていないなど）は、作業を止めてユーザーに尋ねてください。ただ尋ねるだけではなく、具体的な確認方法も伝えてください。公開サイトをブラウザーの開発者ツールで開き、Network タブに移動して再読み込みし、メインの JS バンドルが実際に読み込まれている URL を確認してもらいます。

上記をすべて確認した後でも、プレースホルダー、TODO、推測したホスト名を設定してはいけません。

ステップ 3：プラグインをインストールする

npm install --save-dev @datadog/<bundler>-plugin

プロジェクトのパッケージマネージャーを使用してください：yarn add -D、pnpm add -D、または bun add -d。

Step 4: バンドラーがソースマップを出力するように設定する

これは最もよくある、気づきにくい失敗です。 プラグインはビルドで生成された .map ファイルをすべてアップロードします。バンドラーがソースマップを出力するよう設定されていない場合、プラグインはファイルを見つけられず、No sourcemaps to upload という警告だけをログに出して、ビルドは成功します。Datadog には何も表示されず、その理由を説明するエラーもありません。

これらはバンドラー固有の設定であり、プラグインのオプションではありません。Datadog ビルドプラグインが設定することも、ドキュメントに記載することもありません。

バンドラー	設定
webpack	`devtool: 'source-map'`
Rspack	`devtool: 'source-map'`
Vite	`build.sourcemap: true`
Rollup	`output.sourcemap: true`
esbuild	`sourcemap: true`

設定されていない場合は追加してください。プロジェクトで本番環境のソースマップを意図的に無効にしている場合は、そこで作業を止めてユーザーに相談してください。非公開のソースマップが公開状態で配信されるのは実際に懸念すべき問題です。また、プラグインはアップロード後にファイルを削除しないため、デプロイ時に削除されなければ .map ファイルはそのまま配信されます。

Step 5: プラグインを設定に組み込む

plugins 配列の先頭にプラグインを登録してください。プラグインの README でも、完全なビルドレポートを得るため、5 つすべてのバンドラーで先頭に登録することを推奨しています。

API キーを設定ファイルに記述しないでください。プラグインは環境変数から DATADOG_API_KEY（または DD_API_KEY）を読み取り、環境変数は設定値より優先されます。キーを設定ファイルに含めなければ、認証情報をバージョン管理に含めずに済みます。

Vite（vite.config.js）：

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

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    datadogVitePlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
});

webpack（webpack.config.js）：

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

module.exports = {
  devtool: 'source-map',
  plugins: [
    datadogWebpackPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
};

Rspack（rspack.config.js）— webpack と同じですが、@datadog/rspack-plugin の datadogRspackPlugin を使用します。

Rollup（rollup.config.js）：

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

export default {
  output: { sourcemap: true },
  plugins: [
    datadogRollupPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
};

esbuild（ビルドスクリプト）：

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

require('esbuild').build({
  sourcemap: true,
  plugins: [
    datadogEsbuildPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
});

step 2 で収集した値にすべて置き換えてください。'my-service' や '/static/' をそのまま残さないでください。

ユーザーから求められた場合に限り、次のサブオプションを指定できます。

オプション	デフォルト	効果
`dryRun`	`false`	アップロード以外のすべての処理を行うとドキュメントに記載されています。安全性の確認にこれを当てにしないでください。step 7 を参照してください
`bailOnError`	`false`	最初のアップロードエラーでビルドを失敗させます
`maxConcurrency`	`20`	同時アップロード数

Step 6: ビルド環境で認証情報を設定する

アップロードには API キーが必要です。アプリケーションキーは必要ありません。

変数	用途
`DATADOG_API_KEY` または `DD_API_KEY`	必須です。設定されていない場合、アップロードは `No authentication token provided` で失敗します。
`DATADOG_SITE` または `DD_SITE`	US1 以外の組織では必須です。デフォルトは `datadoghq.com` です。該当するリージョンに応じて、`datadoghq.eu`、`us3.datadoghq.com`、`us5.datadoghq.com`、`ap1.datadoghq.com`、`ap2.datadoghq.com`、`ddog-gov.com` を使用してください。

これらは CI／ビルドのシークレットとして設定してください。キーをコミットするファイルに記述しないでください。

ユーザーに尋ねる前に、リポジトリを確認し、ビルドコマンド（build スクリプト）が実際にどこで実行されるかを調べてください。シークレットを注入する必要があるのはその場所であり、最終的なホスティング先と同じとは限りません。GitHub Actions のワークフローでビルドを実行し、その後、別のステップで生成物を Cloudflare Pages／Netlify／Vercel／S3 にデプロイする場合は、シークレットをホストではなくワークフローに設定します。

リポジトリで見つかった手がかり	ビルドが実際に実行される場所	シークレットの追加先
ビルド／インストールのステップを含む `.github/workflows/*.yml`	GitHub Actions	Repo Settings → Secrets and variables → Actions
`.gitlab-ci.yml`	GitLab CI	Settings → CI/CD → Variables
`vercel.json` がある、または CI ファイルがなく Vercel 独自のビルドでデプロイしている	Vercel	Project Settings → Environment Variables
`netlify.toml` がある、または CI ファイルがなく Netlify 独自のビルドでデプロイしている	Netlify	Site Settings → Environment variables
`Dockerfile`／`docker-compose.yml` があり、それを呼び出す CI ワークフローがない	Docker。イメージのビルド場所によります	デプロイパイプラインによります。確認してください

推測せず、検出したプロバイダーをユーザーに確認してください。 リポジトリには、すでに使われていないプロバイダーの設定が残っている場合があります。該当するものがない場合は、そこで作業を止め、ビルドがどこで実行されるかを確認してください。

ステップ 7：検証

Git メタデータは自動的に付加されます。enableGit はトップレベルのオプションで、デフォルトは true です。そのため、有効化する必要はなく、壊さないようにするだけです。ステップ 7 で以下の特定のエラーが発生した場合を除き、設定しないでください。

安全にテストする方法として、dryRun: true に頼らないでください。 「アップロード以外のすべてを実行する」と説明されていますが、これは信頼できません。少なくとも 1 つの実際に公開されたプラグインバージョンでは、このフラグが完全に無視され、認証済みの本番アップロードが行われます。安全性の観点から、dryRun は未検証のものとして扱ってください。インストールされているバージョンによって、ネットワーク呼び出しが実際にスキップされるかどうかは異なる場合があります。

検出をテストし、アップロードが絶対に発生しないと保証できる唯一の方法は、ビルドが実行される環境のどこにも DATADOG_API_KEY／DD_API_KEY が設定されていないことを確認することです。これを明示的に確認してください。関係のないローカルツール（例：個人用の datadog-ci セットアップ）で使っていたキーが残っている場合も該当し、気づかないうちに使われます。キーにアクセスできなければ、dryRun の動作にかかわらず、プラグインは認証できません。その状態で通常の本番ビルドを実行してください（dryRun は不要です）。

No sourcemaps to upload とログに出る場合、ステップ 4 が正しくありません。プラグインが .map ファイルを見つけられていません。この確認は、認証情報の有無にかかわらず、ネットワーク呼び出しの前にローカルで行われます。
これがログに出ない場合、Git メタデータに関する警告の後、ビルドが No authentication token provided で失敗することがあります。これはステップ 4 と 5 が正しいことを示します。プラグインはソースマップを見つけており、キーにアクセスできなかったために停止しただけです。キーが設定されていない場合は、これが想定どおりの安全な結果です。

これが通った場合にのみ、実際のアップロード経路のテストに進んでください。また、必ず意図的に行ってください。これは本番環境での操作であり、気軽に実行する検証手順ではありません。使用するキーをユーザーに明確に確認してください。

ローカルで実際のアップロード経路を検証したい場合は、このテストのために、自分自身の有効な DATADOG_API_KEY（US1 以外の場合は DATADOG_SITE も）をシェルでエクスポートする必要があります。
関係のないツールのためにシェルですでにキーが設定されている場合、そのキーもここで使われます。そのキーが属する組織にアップロードされ、サンドボックス環境や CI 専用の送信先ではなく、キーが設定されるとすぐにアップロードされるため、本当に意図したものか、続行する前に確認してください。

ビルドが Error: No git remotes available で失敗する場合： ビルド環境に Git リモートがありません。浅い CI クローンやコンテナビルドでよくある状況です。優先順に 2 つの方法があります。ビルド環境で Git リモートを利用できるようにする（エラーからソースへのリンクを維持できるため、こちらを推奨します）か、プラグイン設定のトップレベルで enableGit: false を設定し、Git の収集を完全に無効化してください。

datadogWebpackPlugin({
  enableGit: false,
  errorTracking: { sourcemaps: { /* ... */ } },
})

エンドツーエンドで確認します。デプロイ済みアプリでエラーを発生させ、Datadog Error Tracking のスタックトレースが難読化解除されていることを確認してください。

よくある間違い

service または releaseVersion の値を datadogRum.init() の値と異なるものにしてしまう。アップロードは成功しますが、ソースマップがどのエラーにも紐付けられません。これは警告されません。
ステップ 4 でバンドラーのソースマップ設定を忘れる。警告が表示されるだけで、ビルドは成功します。
配信 URL ではなく、出力ディレクトリから minifiedPathPrefix を推測する。dist/ は URL プレフィックスではありません。
apiKey をビルド環境ではなく、コミットする設定ファイルに記述する。
チケットに「Git を有効にする」と書かれていたため、enableGit: true を設定する。すでにデフォルトで有効になっているため、設定しても何も変わりません。
releaseVersion と metadata.version の両方に異なる値を設定し、ビルドが失敗する。
Next.js でビルドプラグインを使おうとする。このプラグインには Next.js との統合機能がありません。

検証チェックリスト

Markdown 対応

ログインしてコメント

基本情報

作者: datadog-labs
リポジトリ: datadog-labs/agent-skills
カテゴリ: 開発
インストール数: 93
GitHub スター: 185

問題を報告