Datadog Error Tracking実装手順：イシュー集約とソースマップ登録、APM/RUM/Logs連携

エラーログを1件ずつ眺めるのをやめる、というのがError Trackingの出発点になります。同じ例外が1万回出ていても、束ねてしまえばイシューは1件です。ただし束ね方は自動で決まるため、スタックトレースの欠けたログを流し込むと粒度が壊れます。フロントエンドではminify後の行番号のままイシューが立ち、原因箇所が読めない。この記事では、Datadog公式ドキュメント（2026年8月16日時点）の記述に沿って、APM・RUM・Logsの3経路での取り込み、ログ側で必須になる属性、datadog-ciによるソースマップ登録、5つのイシュー状態を使ったトリアージ設計、そして専用のエラー監視ツールを選ぶ分岐点までを整理します。

まとめ：Error Tracking導入で先に決めるイシューの粒度と閉じ方

先に決めるのは3点です。ひとつ目は、どのソースからエラーを取るか。公式ドキュメントが挙げるソースはRUM・Logs・APMの3系統で、同じ障害を3経路すべてから拾うとイシューが重複します。バックエンドはAPM、ブラウザはRUM、それ以外の非対応ワークロードだけをLogsで補う、という優先順位を最初に固定してください。

ふたつ目は、束ねる材料を揃えること。イシューは似たエラーメッセージとスタックトレースで自動集約されます。裏を返せば、スタックトレースが本文に潰れて入っているログや、リクエストIDが混ざった動的なメッセージは、束ねられずに散る。ソースマップを上げていないフロントエンドも同じ状態になります。

3つ目が閉じ方の設計です。状態はFOR REVIEW・REVIEWED・RESOLVED・IGNORED・EXCLUDEDの5種類。versionタグを付けていれば、14日以上前のバージョンで最後に報告されたイシューは自動でRESOLVEDへ落ちます。逆にversionタグを付けないまま運用すると、直したはずのイシューが14日間居座り続ける。タグ設計を先に通しておくと、トリアージの手数がそのまま減ります。

個別エラーをイシューへ束ねるError Trackingの構造と3つの取り込み元

Error Trackingは独立したエラー収集基盤ではありません。すでにDatadogへ届いているトレース・セッション・ログの中からエラーを抜き出し、集約層として上に載る機能です。製品全体の中での位置づけはDatadogとは何かで扱うため、ここでは集約の判定条件とソース選定に絞ります。

エラーメッセージとスタックトレースで束ねるイシュー生成の判定条件

集約の単位はイシューです。公式ドキュメントの説明では、似たエラーメッセージとスタックトレースを持つエラーがひとつのイシューにまとめられ、最初に出た時刻・最後に出た時刻・その間の頻度が1画面で読めるようになります。件数の山ではなく「何種類の不具合が生きているか」で数えられる、という変化がこの機能の本体です。

実装側で効くのは、メッセージを安定させることです。NullPointerException: user id 8831 not found のようにIDを埋め込んだメッセージは、ID違いで別イシューに割れます。可変値は例外メッセージから外し、タグや属性へ逃がしてください。逆に、共通の例外ラッパーで全部を同じメッセージに丸めると、無関係な障害が1イシューへ潰れる。どちらに倒しても調査が遅くなるため、メッセージは障害の種類ごとに1つ、という粒度に合わせます。

APM・RUM・Logsの3ソースで異なる取り込み経路と設定の入口

取り込み元によって、必要な計装と得られる情報が変わります。3系統の違いを整理します。

APMのバックエンド計装ではException Replayが使え、本番環境のローカル変数の値を自動でキャプチャします。再現手順を聞き出す往復が減るのはこの経路だけです。dd-traceによる自動計装の入れ方はDatadog APM導入の実装手順で詳述しているため、Error Trackingを有効にする前にそちらでサービス名とenvが正しく載っているかを確認してください。モバイルはAndroid・iOS・Expo・React Native・Flutter・Kotlin Multiplatformに対応しています。

バックエンドとフロントエンドで分かれるError Tracking有効化の実装手順

有効化の作業量は経路で大きく違います。APM計装済みのバックエンドはほぼ設定不要で並び始める一方、ログ経由とフロントエンドは前処理が要ります。詰まるのは決まってこの2つです。

ログ側で必須になる3つの属性とスタックトレースを落とさない出力設計

Error Tracking for Logsが処理するのは、スタックトレース付きで正しく整形されたエラーログだけです。判定に使われるのは error.stack・error.message・error.kind の3属性で、これらがDatadogの標準属性としてマッピングされていないログは、Error Trackingの一覧に現れません。ログ検索では見えているのにイシューが0件、という状態はほぼこれが原因です。

対処は2段です。まずアプリ側でJSON構造化ログを出し、例外オブジェクトをメッセージ文字列へ連結せず独立したフィールドとして出力する。次にDatadogのパイプラインで、そのフィールドを標準属性へリマップします。既存のテキストログをGrokパーサーで割る場合、複数行のスタックトレースが行ごとに別ログへ分断されると集約が壊れるため、マルチライン処理を先に通してください。パイプラインとパースの組み方はDatadogログ収集の3経路とパイプライン設計にまとめています。

datadog-ciでソースマップを登録する手順とversionタグの一致

ブラウザのエラーは、ソースマップを上げるまで実質読めません。バンドル後の1行目と巨大なカラム番号だけが並ぶためです。登録は@datadog/datadog-ciで行います。手順は次のとおりです。

1. 専用のDatadog APIキーを発行し、環境変数 DD_API_KEY に設定する
2. @datadog/datadog-ci を package.json へ追加する（最新版を使う）
3. ビルド設定でソースマップを出力する（Viteなら build.sourcemap を true、WebpackならSourceMapDevToolPluginでnoSourcesをfalseにする）
4. datadog-ci sourcemaps upload にビルド成果物のディレクトリを渡し、service・release-version・minified-path-prefix を指定して実行する
5. ブラウザSDK側のservice名とversionを、アップロード時に指定した値と一致させる

5番目が最も落ちます。release-versionはたとえば v35.2395005 のようなリリースタグで、この値がRUMイベント側のversionと食い違うと、ソースマップは保管されているのに紐付きません。service名も同様で、複数サービスがある場合はサービスごとにコマンドを実行する必要があります。CIからの実行方法とdatadog-ciの配布形態はdatadog-ciの導入と使い分け、SDK側のservice・versionの設定はDatadog RUM導入の実装手順を参照してください。

500MB上限と.js.map限定、再アップロードで上書きされない制約

公式ドキュメントが明示している制約が3つあります。1つ目はサイズで、ソースマップと対応するminifiedファイルの合計が500MBを超えると受け付けられません。巨大な単一バンドルを吐いているプロジェクトは、ここでコード分割が必要になります。

2つ目は拡張子です。正常に動作するのは .js.map のみで、.mjs.map はアップロード自体は通るもののサポート対象外とされています。ESMビルドで拡張子を .mjs のまま出しているとこれに当たります。3つ目が上書きの挙動で、versionを変えずに再アップロードしても既存ファイルは置き換わりません。ビルドをやり直したのに古いマッピングのままになる事故はここです。CIではコミットハッシュなどからversionを毎回生成し、同じ値を二度使わない運用にしてください。

5つのイシュー状態と14日で自動解決される条件を踏まえたトリアージ設計

Error Trackingが定着するかどうかは、検知の精度よりも「誰がいつ閉じるか」で決まります。状態の意味と自動遷移の条件を把握しておけば、手で触る件数はかなり減らせます。

FOR REVIEWからRESOLVEDまで5状態の遷移と自動解決の条件

状態は次の5つです。

• FOR REVIEW：新規、または再発したイシュー。着手判断が必要なもの
• REVIEWED：トリアージ済みで、いま直すか後で直すかが決まったもの
• RESOLVED：修正済みで、発生が止まったもの
• IGNORED：これ以上の調査も対応も不要と判断したもの
• EXCLUDED：収集自体を止める状態。使用量と請求にも計上されない

FOR REVIEWからREVIEWEDへは、担当者をアサインするか、そのイシューからケースを作成した時点で自動的に移ります。トリアージ会で「担当を決める」という行為がそのまま状態遷移になる設計です。自動解決の条件は2通りで、versionタグを設定している場合は、14日以上前のバージョンで最後に報告され、かつ新しいバージョンで同じエラーが出ていないイシューがRESOLVEDへ落ちます。versionタグが無い場合は、過去14日間に新規エラーが報告されていないことが判定条件です。閉じたイシューが再び出た場合はRegression Detectionで再オープンされうるため、手で閉じ直す運用は最小限で足ります。

ここから導ける設計判断は明快です。デプロイのたびにversionタグを更新していないなら、自動解決は「14日間沈黙したら閉じる」という鈍い判定でしか働きません。タグ設計はDatadog運用のベストプラクティスで扱う共通の土台なので、Error Trackingの前に通しておくと効果が二重に効きます。

新規イシューと件数急増を検知するモニターの型と通知先の振り分け

Error Trackingのイベント上にはモニターを設定できます。使う型は実質2つで、新規イシューの発生を拾うものと、エラー件数の急増を拾うものです。前者は「リリース直後に見たことのない例外が出た」を即座に知らせる用途、後者は「既知のイシューだが規模が変わった」を捉える用途になります。

通知先は分けてください。新規イシューはリリース担当のチャンネルへ、件数急増はオンコールへ。同じ宛先に流すと、リリース当日の細かい新規イシューでオンコールが埋まり、本番影響の大きいものが埋もれます。閾値と評価ウィンドウの決め方はDatadogモニターのタイプ選定と閾値設計にまとめました。なお、恒常的に鳴り続ける既知のイシューはIGNORED、収集ごと止めてよいものはEXCLUDEDへ落とし、モニター側の除外条件を増やして複雑にしない方が保守は楽です。

検知したイシューをトレースとセッション、ログの実データへ降ろす調査導線

イシューの一覧は入口にすぎません。実際の修正は、そのイシューを構成する個々のエラーが、どのリクエストのどの処理で出たのかを見に行くところから始まります。導線が切れていると、集約したぶんだけ元データが遠くなる。

トレースとセッション、ログを横断させるサービスとversionのタグ

イシューの詳細画面では、総件数と時系列の推移、影響セッション数、スタックトレース、そして紐付いたログを確認できます。APM由来のエラーであれば、関連するトレースへ直接移動できます。この横断が成立する条件は、service・env・versionの3つが各シグナルで同じ値になっていることです。

ずれる典型は、フロントエンドのビルド時に入れるversionと、バックエンドのデプロイで入れるversionが別体系になっているケース。片方がGitタグ、片方がビルド番号だと、同じリリースなのに突き合わせができません。リリース単位を1つに揃えるか、少なくとも相互に変換できる規則にしておいてください。ソースマップ登録時のrelease-versionもこの値に合わせます。

影響セッション数とCount順の並び替えで直す順番を決める基準

Explorerでは Relevance・Count・Newest・Impacted Sessions で並び替えができ、Sources・Fix available・Teams・Assigned to・Suspected Cause といったフィルタで絞り込めます。優先順位付けで使うのはこのうち2つです。

件数で並べると、リトライで自動的に回復している通信エラーが上に来がちです。ユーザー影響の大きさを見たいなら Impacted Sessions で並べ替えてください。件数が3桁でも影響セッションが数件なら、特定の環境に閉じた問題である可能性が高い。逆に件数が2桁でも影響セッションがほぼ同数なら、それは1人1回で離脱している導線の障害です。件数の多い順に潰していく運用は、この差を見落とします。実務では、Impacted Sessionsで上位を確定させ、そのうえでCountを二次条件に使う順序が扱いやすい。

Error Trackingを見送る条件と専用エラー監視ツールを選ぶ判断の分岐点

ここは条件を付けて言い切ります。Error Trackingは単体で選ぶ機能ではなく、Datadogをどこまで使っているかで採否がほぼ決まります。

既にDatadogを使っているかで分かれる採用条件と見送る場面

すでにAPMかRUMを本番で計装しているなら、採用してください。エラーデータは同じ計装から抜かれるため、追加のSDK導入や新しいエージェントの配布が発生せず、トレースやセッションへの横断もそのまま繋がります。二重に別ツールを入れる理由はここでは見当たりません。

逆に見送るべき場面は2つあります。1つは、ログをDatadogへ送っておらずAPMも未計装で、エラー追跡のためだけにDatadogを新規契約する場合。取り込み量に対する課金が土台に載る構造のため、目的がエラー追跡だけなら費用対効果が合いにくく、Sentryのエラー監視・APM機能のようなエラー特化のツールを単体で入れた方が安く収まります。もう1つは、フロントエンドのソースマップ運用をCIに組み込めない場合。ソースマップ無しのブラウザエラーは行番号が読めず、集約された一覧だけが積み上がります。この状態なら、導入は先送りしてCIの整備を先に済ませてください。

イシューを閉じ続ける体制の確保と運用の一部を外部へ預ける判断基準

導入後に効いてくるのは人の側です。FOR REVIEWのイシューを毎週さばく担当が決まっていない現場では、数週間でリストが数百件に膨らみ、以後は誰も開かなくなります。自動解決は14日の沈黙で働きますが、それは「直った」ではなく「出ていない」を意味するだけ。放置されたイシューは自動的に消えても、原因は残ります。

目安を1つ置くなら、週に30分、イシュー一覧を上から見て担当を割り当てる時間が確保できるかどうか。確保できないなら、モニターは新規イシューの通知だけに絞り、一覧のトリアージは見ない前提で設計した方が実態に合います。開発と並行して監視の当番まで回せない体制であれば、保守運用・内製化支援のように運用の一部を外部に預け、切り分けまでを委託して修正判断だけ社内に残す分担も選べます。監視基盤を入れること自体より、鳴った後を誰が持つかを先に決めてください。

よくある質問

Error Trackingの導入検討で実際に問い合わせの多い論点を5つ挙げます。

Error Trackingを使うのに追加の契約は必要ですか？

Error Trackingは独立した収集基盤ではなく、APM・RUM・Log Managementのいずれかで収集済みのエラーデータを集約する層として動きます。したがって、まず前提となるいずれかの経路を有効にしておくことが必要です。バックエンド向けにはスタンドアロンの導入経路も用意されています。金額は改定されるため、契約前にDatadogの料金ページで時点を確認してください。課金の考え方そのものは取り込み量とインデックス量が土台になる構造です。

Sentryから乗り換える意味はありますか？

すでにDatadogでAPMやRUMを運用しているなら意味があります。エラーからトレース、セッション、ログへ1画面で降りられる導線は、ツールが分かれていると再現できません。一方、Datadogを使っておらずエラー追跡だけが目的なら、乗り換える理由は薄いままです。判断軸は機能比較ではなく、既存の計装をどこまで共有できるかに置いてください。

ソースマップを上げてもminifyされたままなのはなぜですか？

多くはservice名かversionの不一致です。アップロード時に指定した値と、ブラウザSDKが送るイベント側の値が一致していないと紐付きません。次に多いのが、versionを変えずに再アップロードしたケースで、この場合は既存ファイルが上書きされず古いマッピングが残ります。拡張子も確認してください。正常に動くのは .js.map のみで、.mjs.map は受理されてもサポート対象外です。

イシューが勝手にResolvedになるのを止められますか？

自動解決の条件はversionタグの有無で変わります。タグを設定している場合は14日以上前のバージョンで最後に報告され新バージョンで再報告がないこと、未設定なら過去14日間の新規エラーが無いことが条件です。閉じた後に同じエラーが再発すればRegression Detectionで再オープンされうるため、取りこぼしを過度に心配する必要はありません。恒常的に残したいものはIGNOREDへ移し、状態の意味を分けて管理してください。

ログにスタックトレースが無いとError Trackingは使えませんか？

Logs経由では使えません。Error Tracking for Logsが処理するのはスタックトレース付きで正しく整形されたエラーログで、error.stack・error.message・error.kind の標準属性へのマッピングが前提になります。ただしバックエンドをAPMで計装していれば、ログの形式に関係なくトレース側から例外を拾う構成です。ログ整形の改修が重いなら、APM計装を先に入れる順序の方が早く立ち上がります。

関連記事

• Datadogとは何か？機能やメリット、導入の背景：製品全体の中でError Trackingの位置づけを確認したいとき
• Sentryとは？エラー監視・APMの機能・料金・使い方：エラー追跡に特化した別製品と比較検討するとき
• Datadog APM導入の実装手順｜dd-trace自動計装：バックエンドのエラーを取り込む前提となる計装
• Datadog RUM導入の実装手順｜ブラウザSDK設定：フロントエンドのエラー収集とversion設定
• Datadogログ収集の3経路とパイプライン設計：ログ経由で取り込む際の整形とリマップ