--- title: "Datadog APM導入の実装手順｜dd-trace自動計装からサンプリング設計まで" url: "https://www.issoh.co.jp/tech/details/16578/" published: 2026-08-15 updated: 2026-09-27 categories: ["監視・オブザーバビリティ"] publisher: "株式会社一創" --- # Datadog APM導入の実装手順｜dd-trace自動計装からサンプリング設計まで Datadog APMは、アプリケーションの処理をトレースとスパンに分解し、どのサービスのどの処理で時間を失っているかを追跡するプロダクトです。Agentを入れてトレーサーを読み込ませれば、コードを書き換えずにスパンは流れ始めます。詰まるのはその後。タグをどう揃えるか、サービスマップが描画されないときに何を疑うか、取り込み量をAgentとSDKのどちらで絞るか。2026年8月時点の公式ドキュメントの記述をもとに、実装目線で整理します。 ## まとめ：Datadog APM導入で先に決める計装方式とサンプリング設定 結論を先に置きます。導入で最初に決めるのはトレーサーの入れ方ではありません。`DD_ENV`・`DD_SERVICE`・`DD_VERSION`の命名規則、自動計装を使うか手動計装へ切り替えるか、そしてサンプリングをAgent側とSDK側のどちらで制御するか。この3つを決めないまま本番へ投入すると、サービス名の重複でサービスマップが読めなくなり、取り込み量が想定を超えて課金が膨らみます。 実装順序はこうです。まずAgentのAPM受信を有効にして疎通を確認し、Single Step Instrumentationまたは言語別トレーサーで最小構成のスパンを送る。次に3つのタグを環境変数で固定し、サービス名がDatadog側で意図どおり分かれているかを確認する。サンプリングを絞るのは最後です。先に絞ると、そもそもトレースが届いているかの切り分けができなくなります。 採否の線引きも先に述べます。サービスが3つ以上に分かれ、障害の再現がログだけでは追えない構成ならAPMは投資に見合う。単一プロセスのモノリスで、外形監視とエラートラッキングで検知が足りている状態なら見送りが妥当です。理由は判断章で条件付きに示します。 ## Datadog APMが扱うトレース・スパンとインフラ監視との守備範囲 設定値の話に入る前に、Datadogが何を1件として数えているかを押さえます。この単位が、検索の単位にも課金の単位にもそのまま効いてきます。 ### トレース・スパン・サービスという3つの処理単位と課金対象の関係 スパンは処理の一区間です。HTTPリクエストの受信、SQLの発行、外部APIの呼び出し。それぞれが開始時刻と終了時刻を持つ1本のスパンになります。これらを親子関係でつないだ木構造がトレースで、木の根にあたるものがルートスパンです。サービスは、スパンに付く`service`タグの値でDatadog側が自動的に束ねる集計単位にすぎません。 課金で効くのは、この3つのうちスパンです。Datadog APMはホスト単位の課金に加えて、検索対象として保持するIndexed Spansが従量で乗る構造になっています。取り込んだスパンをすべて検索可能な状態で保持するとコストが伸びるため、後述のサンプリングとリテンションフィルタで絞ることになります。課金単位ごとの内訳は[Datadogの料金体系と費用が膨らむ課金単位](https://www.issoh.co.jp/tech/details/16574/)で整理しているため、見積もりを作る段階ではそちらを参照してください。 APMという手法そのものの定義や、メトリクス・ログ・トレースという3種の監視データの関係は、製品非依存で[APM（アプリケーション性能監視）とは](https://www.issoh.co.jp/tech/details/15414/)にまとめています。本記事はDatadog製品での実装に絞ります。 ### インフラメトリクス監視では追えないサービス間の待ち時間の所在 CPU使用率もメモリ使用量も正常。それでもレスポンスが3秒かかる。この状態でインフラ監視のダッシュボードを眺めても答えは出ません。時間を失っている場所がプロセスの内側ではなく、サービスとサービスの間にあるからです。 トレースはここを可視化します。注文APIが在庫APIを呼び、在庫APIがRDSへクエリを投げ、そのクエリが2.4秒かかっている。この因果を1本の木として保持するのがAPMの守備範囲で、ホスト単位のメトリクスでは原理的に到達できません。逆に、ディスク使用率の逼迫やノードの再起動はメトリクス側の担当です。Datadogの製品構成における両者の位置付けは[Datadogとは何か](https://www.issoh.co.jp/tech/details/6476/)で全体像を確認できます。 ## dd-traceによる自動計装の3方式と言語別トレーサーの起動設定 計装の入れ方は大きく3つに分かれます。Agent側から自動で差し込む方式、アプリケーションの起動コマンドにトレーサーを噛ませる方式、そしてコードへ直接スパンを書く方式。運用の手間と制御の細かさが逆相関するため、どこまで自動に任せるかを最初に決めます。 ### Single Step Instrumentationでコード変更なしに計装する条件 Single Step Instrumentation（SSI）は、Agentのインストールまたは更新時にAPM計装を有効化しておくと、Agentが対象プロセスへDatadog SDKを読み込ませる仕組みです。公式ドキュメントは「コード変更なしにサービスからトレースデータを取得して送信できる」と説明しており、アプリケーション側のDockerfileやデプロイスクリプトに手を入れずに済みます。対応する配置形態はLinux・Docker・Kubernetes・Windowsの4種です（2026年8月時点）。 制約が1つあります。カスタム計装が検出された場合、SSIは自動的に無効化されます。既存のコードにトレーサーの初期化を書いている環境でSSIへ切り替えるなら、先に既存の計装コードを取り除く必要があるという順序です。両方を残したまま切り替えて「なぜかSSIが効かない」と詰まるのが典型パターンになります。 ### Python・Java・Node.jsで使う言語別トレーサーの起動方法 SSIを使わず明示的に入れる場合、起動時にトレーサーを噛ませます。言語ごとの入口は次のとおりです（2026年8月時点の各トレーサーの標準的な起動方法）。 | 言語 | 導入物 | 起動時の指定 | | ------- | ----------------- | --------------------------- | | Python | ddtrace | `ddtrace-run python app.py` | | Java | dd-java-agent.jar | JVM引数でエージェントを指定 | | Node.js | dd-trace | エントリポイント先頭で初期化 | | Ruby | datadog gem | 初期化ファイルで`Datadog.configure` | Javaでは起動コマンドに「java -javaagent:/path/dd-java-agent.jar -jar app.jar」を指定します。Node.jsではエントリポイント先頭で「require(‘dd-trace’).init()」を実行します。 いずれの方式でも、トレースの送信先はAgentのAPM受信ポート（既定で8126）です。コンテナ環境で「トレーサーは動いているのにDatadogに何も出ない」場合、まず疑うのはアプリケーションコンテナからAgentへの到達性で、次がAgent側のAPM受信の有効化。この2点で大半が解決します。そのAgent自体をホスト・Docker・DaemonSetのどれで配置するかは、[Datadog Agent導入の実装手順](https://www.issoh.co.jp/tech/details/16580/)で整理しています。 ### 手動計装へ切り替える判断と、OTLP経由で送る場合の分岐条件 自動計装が拾うのは、フレームワークやライブラリが提供する境界です。独自のバッチ処理、社内製のメッセージング層、キューのワーカーといった箇所は自動では区切られません。ここに時間が溜まっているなら、該当区間だけ手動でスパンを開いて名前を付けます。全面的な手動計装へ移行する必要はなく、自動計装を土台にして穴の空いた区間を足すのが実務上の落としどころです。 ベンダー中立の計装をあらかじめ選ぶなら、Datadogトレーサーではなく OpenTelemetry SDK を入れてOTLPで送る構成も取れます。送信方式は4通りあり、それぞれで失われる機能が異なるため、[Datadog OpenTelemetry連携の4方式](https://www.issoh.co.jp/tech/details/16564/)で差分を確認してから決めてください。将来の乗り換え余地を残したい組織はこちらの分岐に入ります。 ## env・service・versionを揃えるタグ設計と環境の切り分け Datadog APMで最初に壊れやすいのはタグです。サービス名が揃っていないだけで、サービスマップは意味をなさなくなります。 ### DD\_ENV・DD\_SERVICE・DD\_VERSIONを揃える3つの環境変数 Unified Service Taggingは、`env`・`service`・`version`という3つのタグをメトリクス・トレース・ログの全てに共通で付ける取り決めです。設定は環境変数`DD_ENV`・`DD_SERVICE`・`DD_VERSION`で行い、Kubernetesならマニフェストのラベルから引き渡します。 命名で決めておく規則は2つ。`env`の値をproduction・prod・prdのように揺らさないこと、`service`にホスト名やコンテナ名を入れないことです。後者は特に事故が多い箇所で、同じアプリケーションがPod数だけ別サービスとして分裂し、サービスマップが数十ノードの網になります。`service`に入れるのは論理的なサービス名であって、実行単位ではありません。 ### バージョンタグで回すデプロイ単位の劣化検知と切り戻し判断基準 `DD_VERSION`を入れておくと、デプロイ前後でレイテンシとエラー率を版ごとに並べられます。運用で効いてくるのはこの1点です。「今朝からレスポンスが遅い」という報告に対し、版を軸に分解すれば、直近リリースの影響なのか外部要因なのかが数分で切り分けられます。 値にはGitのコミットハッシュかタグを入れる運用が扱いやすい。連番のビルド番号だけだと、Datadog上で異常を見つけた後にどのコードかを追う手間が残ります。切り戻しの意思決定まで含めて設計するなら、版の値からリポジトリの状態へ一意にたどれる形にしてください。 ## サービスマップとトレース検索でボトルネックを絞り込む実務手順 データが入り始めたら、次は読み方です。障害対応の現場で使う順序はほぼ固定できます。 ### サービスマップが描画されない典型パターンとルートスパンの欠落 サービスマップは、ルートスパンを含む完全なトレースをもとに描画されます。公式ドキュメントは、指定したクエリ期間中にスパンが欠けている場合、その期間のマップ表示が利用できないことがあると明記しています。つまり「マップが真っ白」という症状は、Datadog側の不具合ではなく、木の根が届いていないことを示す信号です。 疑う順序は3つ。入口のサービス（ロードバランサ直下のAPIなど）が未計装ではないか。トレースIDを伝播するヘッダが、途中のプロキシやメッセージキューで落ちていないか。サンプリングを絞りすぎて、木の一部だけが取り込まれていないか。3番目は特に、SDK側でサービスごとに異なるサンプリング率を設定したときに起きます。 ### フレームグラフで待ち時間の内訳を読む最短の絞り込み順序の考え方 個別トレースを開いたら、上から順に読む必要はありません。実務では次の順で見ます。 1. トレース全体の所要時間と、その内訳で最も長い子スパンを特定する 2. そのスパンが自プロセスの処理か、外部呼び出しの待ち時間かを区別する 3. 外部呼び出しなら呼び先サービスのトレースへ移動し、同じ手順を繰り返す 4. 自プロセス内なら、DBクエリのスパンとその実行回数を確認する 4番目でよく出てくるのが、1リクエスト中に同種のクエリが数十本並ぶ形です。これは処理時間の問題ではなく実装の問題なので、インデックス追加ではなくクエリ発行箇所の修正へ回します。クエリ単位の合計時間や実行計画まで見て切り分けるなら、[Datadog Database Monitoringの実装手順](https://www.issoh.co.jp/tech/details/16605/)を併せて参照してください。フロントエンド側の体感速度まで含めて追跡するなら、ブラウザ側の計測とトレースを紐付ける構成もあり、実装手順は[Datadog RUM導入の実装手順](https://www.issoh.co.jp/tech/details/16576/)にまとめています。 ## 取り込み量を決めるヘッドベースサンプリングの設定値と課金への効き方 Datadog APMのサンプリングは、Agent側とSDK側の二層で効きます。ここを一層だと思って設定すると、絞ったはずの取り込み量が減らない、あるいは減らしすぎてトレースが断線するという事態になります。 ### Agent側のDD\_APM\_TARGET\_TPSとSDK側のサンプリングルールの二層 Agent側の既定は、全体でおよそ毎秒10トレースを目標とし、トラフィック量に応じて各サービスへ配分する動作です。この目標値は環境変数`DD_APM_TARGET_TPS`、または`datadog.yaml`の`target_traces_per_second`で変更できます。既定値は10（2026年8月時点の公式ドキュメント記載）。 SDK側では、サービス単位・リソース単位のサンプリング率を`DD_TRACE_SAMPLING_RULES`で指定します。同時に`DD_TRACE_RATE_LIMIT`がサービスインスタンスあたりの毎秒トレース数の上限として働き、未指定時の既定は毎秒100トレースです。なお公式ドキュメントは`DD_TRACE_SAMPLE_RATE`を非推奨とし、`DD_TRACE_SAMPLING_RULES`への移行を案内しています。古い記事を写経すると非推奨の設定を掴むため、設定名は必ず現行ドキュメントで突き合わせてください。 | 層 | 設定 | 既定値（2026年8月時点） | 効く範囲 | | ----- | ------------------------- | -------------- | ---------------- | | Agent | `DD_APM_TARGET_TPS` | 毎秒10トレース | Agent全体からサービスへ配分 | | SDK | `DD_TRACE_SAMPLING_RULES` | 未設定 | サービス／リソース単位の率 | | SDK | `DD_TRACE_RATE_LIMIT` | 毎秒100トレース | サービスインスタンス単位の上限 | ### エラーとレアトレースを取りこぼさないサンプラーの既定値を確認する 率で絞ると、頻度の低い異常が消えます。この穴を埋めるのが、Agent側で動く2つの補助サンプラーです。 エラーサンプラーは`DD_APM_ERROR_TPS`で制御し、既定はAgentあたり毎秒10トレース。0を指定すると無効化されます。レアサンプラーは`DD_APM_ENABLE_RARE_SAMPLER`で有効化する仕組みで、既定では無効、有効時の取り込みはAgentあたり毎秒5トレースまでです。低頻度のエンドポイントを取りこぼしたくない環境では、後者を明示的に有効化する判断になります。 取り込まれたスパンには`ingestion_reason`タグが付き、`auto`・`rule`・`error`・`rare`・`manual`・`single_span`・`rum`・`synthetics`などの値で理由が判別できます。コストを調べるときは、まずこのタグで内訳を出す。どの経路が量を押し上げているかが分からないまま率だけ下げても、消えるのは見たかったトレースの側です。 ### Indexed Spansの膨張を抑える設定順序と削り方の優先度 削る順序には優先度があります。最初に手を付けるのはヘルスチェックのような定型リクエストで、ここは監視上の価値がほぼ無いにもかかわらず件数だけが多い。次に、内部バッチや管理画面など、外部ユーザーの体験に直結しない経路。全体の率を一律に下げるのは最後です。 一律の引き下げを先にやると、トラフィックの少ないサービスから順にトレースが消え、サービスマップの一部が描画されなくなります。件数の多い経路を個別に絞れば、絞った分だけ課金対象が減り、見たい経路の解像度は保てる。この順序を守るだけで、同じ削減幅でも運用上の使い勝手が変わります。課金単位ごとの単価構造と抑制策は[Datadogの料金体系と費用が膨らむ課金単位](https://www.issoh.co.jp/tech/details/16574/)を併読してください。 ## Datadog APMを採用する条件と、実装を見送るべき場面の切り分け ここは条件を付けて言い切ります。APMは入れれば必ず効く道具ではなく、構成と障害の性質によっては投資が回収できません。 ### 採用してよい条件：分散構成とログだけでは再現できない障害への判断 次の2つが同時に当てはまるなら、Datadog APMは導入して回ります。1つ目は、リクエストが3つ以上のプロセスやサービスをまたぐ構成であること。2つ目は、直近の障害対応で「どのサービスが遅かったのか特定に半日以上かかった」経験があること。この2つが揃った環境では、トレースが持つ因果情報がそのまま調査時間の短縮になります。 すでにDatadogでインフラ監視を運用している組織であれば、Agentが配布済みなのでAPMの追加は設定変更の範囲に収まります。Kubernetes上でノード全体を監視している構成なら、その延長として計装できます（構成は[Kubernetes監視・モニタリング](https://www.issoh.co.jp/tech/details/15303/)を参照）。 ### 見送るべき3つの場面と、外形監視だけで足りる規模の線引き基準 逆に、次の場面では見送りが妥当です。 - 単一プロセスのモノリスで、外部依存がDB1台のみ。トレースを見なくても、遅い箇所はスロークエリログで特定できます - アプリケーションコードへ手を入れる予算と権限が無い状態。SSIで計装しても、タグ設計と改修が伴わなければトレースは溜まるだけです - 障害検知そのものが未整備で、監視のアラートが誰にも届いていない状態。先に必要なのは外形監視と通知経路の整備で、APMはその次です 3番目については順序を強調します。トレースの解像度を上げても、気づく仕組みが無ければ意味を持ちません。検知の整備が先、原因追跡の高度化が後。この順序を逆にした現場では、Datadogの請求額だけが増えて障害対応の時間は変わらない結果になりがちです。 計装から運用定着までを内製で回す人員が確保できない場合は、監視設計とAgent構成の初期構築だけを外部に任せ、運用は自社で引き取る形も取れます。当社の[システム保守運用・内製化支援](https://www.issoh.co.jp/service/system/maintenance/)では、こうした監視基盤の設計と内製化までの伴走を扱っています。 ## よくある質問：Datadog APMの計装・サンプリング・課金に関する疑問 導入検討時と実装時に繰り返し出てくる質問を5つ挙げます。 ### Datadog APMとは何ですか？インフラ監視との違いは？ Datadog APMは、アプリケーション内部の処理をスパンという単位に分解し、それらを親子関係でつないだトレースとして記録するプロダクトです。インフラ監視がホストやコンテナの状態（CPU・メモリ・ディスク）を対象にするのに対し、APMはリクエストが通った経路と各区間の所要時間を対象にします。両者は代替関係ではなく、リソース枯渇はメトリクス、サービス間の待ち時間はトレースという分担になります。 ### コードを書き換えずにDatadog APMを導入できますか？ できます。Single Step Instrumentationを有効にしてAgentをインストールまたは更新すると、Agentが対応プロセスへSDKを読み込ませる形で計装されます。対応する配置形態はLinux・Docker・Kubernetes・Windowsです（2026年8月時点）。ただし、カスタム計装が検出されるとSSIは自動的に無効化されるため、既存の計装コードが残っている環境では先にそれを取り除いてください。 ### デフォルトのサンプリング率はどうなっていますか？ Agent側は全体でおよそ毎秒10トレースを目標に、トラフィックに応じて各サービスへ配分します（`DD_APM_TARGET_TPS`の既定値10）。SDK側では`DD_TRACE_RATE_LIMIT`が未指定時にサービスインスタンスあたり毎秒100トレースの上限として働きます。率を明示するときは`DD_TRACE_SAMPLING_RULES`を使い、非推奨となった`DD_TRACE_SAMPLE_RATE`は避けてください。 ### サービスマップに一部のサービスが表示されないのはなぜですか？ サービスマップはルートスパンを含む完全なトレースから描画されるため、期間中にスパンが欠けているとその期間の表示が得られないことがあります。確認する順序は、入口サービスの計装漏れ、プロキシやキューでのトレースIDの伝播断絶、サンプリングの絞りすぎの3つです。特にサービス単位で異なる率を設定している場合、木の一部だけが取り込まれる状態が起きます。 ### OpenTelemetryで計装してもDatadog APMは使えますか？ 利用可能です。OpenTelemetry SDKで計装し、OTLPでDatadogへ送る構成も選択肢です。送信経路は複数あり、経路ごとに利用できる機能や必要な設定が異なるため、ベンダー中立性を優先するか製品固有の機能を優先するかで選び分ける必要があります。方式別の差分は関連記事のOpenTelemetry連携の解説で整理しています。 ## 関連記事 - [Datadog運用のベストプラクティス](https://www.issoh.co.jp/tech/details/16515/)：タグ設計・監視対象の絞り込み・アラート整理という、計装後の運用フェーズで効いてくる型をまとめています。 - [TerraformでDatadogを管理する方法](https://www.issoh.co.jp/tech/details/10105/)：モニターやインテグレーションをコードで管理し、APMの設定を環境間で揃える際の実装手順です。 - [Kubernetes監視・モニタリング](https://www.issoh.co.jp/tech/details/15303/)：Agentをクラスタへ配置する構成と、APM計装の前提になるノード監視の設計を扱っています。 - [オブザーバビリティ（可観測性）とは](https://www.issoh.co.jp/column/details/3077/)：トレースを含む3本柱の考え方と、監視との違いを製品非依存で整理した記事です。 --- 出典: [Datadog APM導入の実装手順｜dd-trace自動計装からサンプリング設計まで]()（株式会社一創）