はじめに
（前提）Next.js で static export して SPA の Web アプリを開発していて、 Datadog RUM を使ってエラートラッキングをしています。
本記事では、Datadog にソースマップをアップロードして、スタックトレースを追いやすくする設定について解説します。
Datadog 公式ドキュメント[1]に基本的な手順は記載されていますが、Next.js と組み合わせた設定の情報が少なかったため、備忘録としてまとめました。
設定の目的
本番ビルドの JavaScript コードは minify されているため、エラーが発生した際のスタックトレースが読みづらくなります。ソースマップを Datadog にアップロードすることで、元のソースコードの行番号やファイル名を確認できるようになり、調査が容易になります。
設定後のスタックトレースはこのように見えます。
実装内容
主な変更は以下の 3 点です。
- Next.js のソースマップ生成設定
- デプロイスクリプトでのソースマップアップロード処理
- GitHub Actions への環境変数追加
1. Next.js の設定変更
next.config.jsで本番ビルドでもソースマップを生成するように設定を追加します。
module.exports = {
webpack: (config, { dev }) => {
if (!dev) {
config.devtool = 'hidden-source-map';
}
return config;
},
};
hidden-source-mapを指定することで、ソースマップファイルは生成されますが、ブラウザからは参照されなくなります(//# sourceMappingURL=144-a0511772a8390267.js.map のようなコメントが消えます)[2]。エラー報告目的でソースマップを使う場合に適した設定です。
2. バージョン管理の追加
Datadog でソースマップを紐付けるためにバージョン情報が必要です。
export NEXT_PUBLIC_APP_VERSION="$(TZ=Asia/Tokyo date '+%Y%m%d-%H%M%S')-$(git rev-parse --short HEAD)"
このバージョンは Datadog RUM の初期化時にも使用します。
datadogRum.init({
// ...
version: process.env.NEXT_PUBLIC_APP_VERSION,
});
3. 依存関係の追加
Datadog CLI を package.json に追加
pnpm i -D @datadog/datadog-ci
4. GitHub Actions の環境変数
デプロイワークフローに Datadog API Key を追加します。
env:
DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
5. デプロイスクリプトの変更
ビルド後、ソースマップを Datadog にアップロードし、その後削除する処理を追加しました。
pnpm build
# Datadogのソースマップアップロード
pnpm exec datadog-ci sourcemaps upload ./out \
--service=app-frontend \
--repository-url=https://github.com/[org]/[repository] \
--project-path=frontend/ \
--release-version=$NEXT_PUBLIC_APP_VERSION \
--minified-path-prefix=/
# ソースマップはDatadogだけで使うのでdeploy前に削除
find ./out -type f -name "*.js.map" -delete
ソースマップファイルはユーザーがアクセスできる S3 にはアップロードしないため、Datadog へのアップロード後に削除しています[3]。
動作確認
- RUM Debug Symbols にファイルがアップロードされていることを確認
- ソースマップファイルが S3 にアップロードされていないことを確認
- エラーを発生させて、Datadog で元のソースコードの行番号が表示されることを確認
まとめ
Datadog RUM でソースマップを活用することで、本番ビルドのエラー調査が効率化されました。
同じような設定を検討している方の参考になれば幸いです。
Discussion