Datadog Agent導入の実装手順｜ホスト・Docker・DaemonSetの3方式とdatadog.yaml設定

Datadog Agentは、監視対象のホストやコンテナに常駐してメトリクス・ログ・トレースを集め、Datadogへ送り出す収集プロセスです。インストール自体はワンライナーやHelmで終わります。手が止まるのはその先で、どこにファイルが置かれるのか、コンテナではどう設定を渡すのか、届かないときに何から疑うのか。2026年8月時点の公式ドキュメントとリリース情報をもとに、実装目線で整理します。

まとめ：Datadog Agent導入で先に決める配置方式と初期設定

結論から置きます。導入で最初に決めるのはインストールコマンドではありません。ホストへ直接置くか、Dockerコンテナとして動かすか、KubernetesのDaemonSetとして配るか。この配置方式と、APIキー・サイトパラメータ・タグの3点を先に固定してください。ここが決まっていれば残りは各方式の作法に落ちます。

実装順序はこうです。まず1台だけに入れて疎通を確認し、Datadog側のホスト一覧に出ることを見届ける。次にタグとホスト名の規則を決めて全台へ広げる。インテグレーションを有効化するのはその後です。逆順にすると、データが届かない原因がAPIキーなのか設定ファイルなのか切り分けられなくなります。キーの発行本数の上限や失効時の挙動はDatadog APIの実装手順で整理しています。

採否の線引きも先に述べます。監視対象が複数ホストにまたがり、ミドルウェアやコンテナの内部状態まで取りたいならAgent常駐は投資に見合う。単一のマネージドサービスだけで完結し、クラウド側のメトリクスAPI連携で足りる構成なら、Agentを置かずインテグレーション連携だけで済ませる判断もあります。理由は判断章で条件付きに示します。

Datadog Agentが動かす4つの内部プロセスと収集の守備範囲

Agentは単一のプロセスではありません。役割ごとに分かれた複数のプロセスが同居する構成で、これを知らないと「メトリクスは来るのにトレースが来ない」という状態の切り分けができなくなります。

4プロセスの分担：メトリクス・トレース・プロセス・ネットワークの収集範囲

Agent 7系（2026-08-10時点でGitHubのリリース一覧では7.82系が最新）では、収集の主体がおおむね4つに分かれます。Core Agentがメトリクスとインテグレーションのチェックを回し、Trace AgentがAPMのスパンを受け取り、Process Agentがプロセスやコンテナの一覧を集め、System Probeがカーネル側の情報を扱います。ログ収集はCore Agent側の機能として設定で有効化する形です。

この分担が効いてくるのは障害の切り分けです。ホストのCPUメトリクスは出ているのにトレースが1本も届かないなら、疑う先はAPIキーではなくTrace Agentの受信設定とアプリ側の送信先です。逆にホストがDatadogのホスト一覧に現れないなら、Core Agentが起動していないか送信先が違います。トレース側の計装そのものはDatadog APM導入の実装手順で扱っているため、本記事はAgentが受け口として動いているかどうかまでを範囲とします。

サイトパラメータの取り違えでデータが1件も届かない失敗パターン

見落としで多いのがサイトパラメータです。Datadogはリージョンごとに送信先が分かれており、公式のサイト一覧ではUS1がdatadoghq.com、US3がus3.datadoghq.com、US5がus5.datadoghq.com、EU1がdatadoghq.eu、日本のAP1がap1.datadoghq.com、オーストラリアのAP2がap2.datadoghq.comと定義されています（2026-08-15時点）。

日本国内でAP1のアカウントを作ったのに、インストール手順をUS1向けのまま実行すると、Agentは起動し、ログにも致命的なエラーが出ないまま、Datadogの画面には何も現れません。APIキーは正しく、プロセスも動いているので原因を追いにくい。Agentが動いているのにデータが見えないときは、APIキーの再発行より先にsiteの値を確認してください。製品全体の構成や何ができるかはDatadogとは何かで整理しています。

ホストへ直接入れる方式とdatadog.yamlで最初に埋める設定

仮想マシンや物理サーバへ直接入れる方式は、依存が少なく切り分けもしやすい構成です。コンテナ化されていない既存システムに監視を後付けする場面では、この方式が扱いやすくなります。

インストール後に生成される設定ファイルの場所と必須項目の確認

インストールスクリプトを実行すると、OSごとに決まった位置へ設定ファイルが置かれます。公式ドキュメントの記載では、Linuxが/etc/datadog-agent/datadog.yaml、macOSが/opt/datadog-agent/etc/datadog.yaml、WindowsはProgramData配下のDatadogフォルダです（2026-08-15時点）。インストール時に環境変数でAPIキーを渡していれば、このdatadog.yamlに値が書き込まれた状態で起動します。

最初に埋めるべき項目は多くありません。api_key、前章で触れたsite、そしてtagsとhostname。APMやログを使うならapm_configとlogs_enabledを追加します。設定ファイルはインストール直後の状態でほぼ全項目がコメントアウトされており、そのままでも既定のメトリクスは流れ始めます。

タグとホスト名を初期設定で固定して後工程を減らすための命名基準

後回しにすると面倒になるのがタグの規則です。env・service・roleあたりをどう付けるかを決めないまま数十台へ配ると、Datadog側でダッシュボードの絞り込みもモニターの対象指定も書けなくなります。1台目の疎通確認が終わった時点で規則を決め、構成管理ツールのテンプレートに埋め込んでから広げてください。

ホスト名も同様です。Agentは既定でOSのホスト名やクラウドのインスタンスIDから自動判定しますが、判定結果が構成管理台帳の名前と食い違うと、障害時にどのサーバのことか分からなくなります。hostnameを明示するか、命名を揃えるかを先に決めておく話です。タグ設計をモニターやコスト管理まで含めてどう組むかはDatadog運用のベストプラクティスで扱っています。

Dockerで動かす方式と環境変数によるdatadog.yamlの置き換え

datadog dockerの構成、つまりAgent自体をコンテナとして動かす方式は、更新がイメージの差し替えで済み、ホスト側の設定を汚さない利点があります。公式ドキュメントでもコンテナ環境ではこちらが案内されています。

コンテナ版で使うDD_接頭辞の環境変数とホスト情報の必須マウント対象

コンテナ版で押さえるのは、設定ファイルを直接編集しない点です。公式の説明では、コンテナ化されていない環境でdatadog.yamlに書く設定項目は、Docker Agentでは環境変数による指定です。DD_API_KEY、DD_SITE、DD_TAGSのように、設定キーを大文字化してDD_を付けた名前が対応します。この規則を知っていれば、ホスト版のドキュメントを読みながらコンテナ版の指定へ読み替えられます。

もう一点がマウントです。Agentコンテナからホスト側のDockerソケットやprocファイルシステムを読めるようにしないと、他コンテナの情報もホストのメトリクスも取れません。コンテナを起動したのにコンテナ一覧が空という状態は、たいていマウント漏れか権限の問題です。

コンテナのメトリクスとログを拾うために追加する収集対象の指定

既定で流れるのはAgent自身が見えている範囲のメトリクスまでです。同一ホスト上の他コンテナのログまで集めるなら、ログ収集を有効化する環境変数と、収集対象のコンテナを絞る指定を追加します。全コンテナのログを無条件に集める設定にすると、ビルドコンテナやサイドカーの出力まで取り込まれ、送信量が跳ね上がります。

ここは課金に直結する箇所です。ログは取り込んだ量とインデックス保持で費用が決まる課金単位のため、収集対象を絞る指定を入れずに本番へ広げると請求が読めなくなります。どの単位で費用が積み上がるかはDatadogの料金体系と費用が膨らむ課金単位にまとめました。

KubernetesはDaemonSetとCluster Agentの二階建てで配置する

Kubernetes環境では配置の考え方が変わります。ノードごとに1つ、加えてクラスタ全体に1つという二階建てになるためです。

Datadog OperatorとHelmを選び分ける運用条件

公式ドキュメントでは、Kubernetesへの導入方法としてDatadog Operator、Helmチャート、kubectlによるマニフェスト適用の3つが示され、このうちDatadog Operatorが推奨として案内されています（2026-08-15時点）。デプロイ状態を報告し、設定ミスの余地を減らせる点が理由として挙げられています。

実務での選び分けはこうなります。GitOpsで宣言的にクラスタを管理していてカスタムリソースの追加に抵抗がないならOperator。既にHelmでミドルウェアを配っていて運用手順を揃えたいならHelmチャート。マニフェスト直書きは、更新時に自分でYAMLを追随させ続ける負担が残るため、検証目的以外では選びにくい方式です。

バージョンの前後関係にも注意が要ります。公式の互換表では、Kubernetes 1.33.0以降の機能にはAgent 7.67.0以降とCluster Agent 7.67.0以降が必要と記載されています（2026-08-15時点）。クラスタを先に上げてAgentを据え置くと、一部の情報が欠けたまま気付かない状態になり得ます。

ノード用DaemonSetとクラスタ用Cluster Agentを分離する理由

ノードAgentはDaemonSetとして全ノードに配られ、そのノード上のコンテナとホストのメトリクスを集めます。一方のCluster Agentは、クラスタ全体で1回だけ取ればよい情報を担当します。ノード数が増えるほど、全ノードがAPIサーバへ問い合わせる構成は負荷が集中するためです。

この分離を理解していないと、「ノードのメトリクスは取れているのにDeploymentやServiceの状態が見えない」という状況で原因を探しあぐねます。クラスタ側のオブジェクト情報が欠けているなら、見る先はDaemonSetではなくCluster Agentの導入有無です。何をメトリクスとして取りアラートをどこに置くかという監視設計そのものはKubernetes監視・モニタリングの設計で扱っています。

インテグレーション有効化はconf.d配下の命名規約で決まる

Agentを入れただけで得られるのはホストの基礎的な指標までです。MySQLやNGINXといったミドルウェアの内部指標を取るには、インテグレーションを1つずつ有効にします。

設定ファイルの命名規約から読み解く有効化と再起動までの作業手順

公式ドキュメントの記載では、Agentは/etc/datadog-agent/conf.d/配下の、チェック名に.dを付けたディレクトリ内のYAMLを読み込みます。テンプレートはconf.yaml.exampleという名前で置かれており、これをconf.yamlへ複製して中身を編集すると有効になります。CPUやメモリなど既定で動くチェックは.defaultの接尾辞、Autodiscovery用のテンプレートはauto_conf.yamlという名前です（2026-08-15時点）。

規約が分かっていれば作業は単純です。有効化したいインテグレーションのディレクトリを開き、exampleを複製し、接続先とcredentialを埋め、Agentを再起動する。1つのディレクトリに複数のYAMLを置いて設定を分割することもできるため、監視対象のインスタンスが増えてもファイルを分けて管理できます。

コンテナ環境でAutodiscoveryから設定を差し込む実装手順

コンテナではファイルを置く先が固定できません。ポッドは入れ替わり、IPも変わるためです。そこでKubernetesではポッドのアノテーション、Dockerではコンテナのラベルとして設定を書き、Agentが対象を見つけた時点でテンプレートを適用します。これがAutodiscoveryの考え方です。

実装上の勘所は、設定を書く場所がアプリ側のマニフェストに移る点にあります。Agentのconf.dを触るのではなく、監視されたいコンテナ自身が「自分はPostgreSQLとして監視してほしい」と宣言する方式です。運用の分担がインフラ担当からアプリ担当側へ寄るため、誰がその記述を管理するかを先に決めておくと後の押し付け合いを避けられます。

疎通確認でstatusコマンドの出力を上から読む3段階の確認手順

入れ終わったら疎通確認です。ここを画面の目視だけで済ませると、データが欠けていることに数日後に気付く事態になります。

statusコマンドで最初に確認する送信状態と収集結果の3箇所

Agentには状態を出力するサブコマンドが用意されており、ホスト版ならdatadog-agent status、コンテナ版ならAgentコンテナの中で同じコマンドを実行します。長い出力が返りますが、最初に見る箇所は3つです。

Forwarderの送信が失敗しているならAgentの外側、つまりAPIキー・サイト・ネットワーク経路の問題です。Forwarderは成功しているのにCollectorで特定のチェックだけ失敗しているなら、原因はそのインテグレーションの接続情報に絞れます。この2段で見ると、切り分けの範囲がすぐ狭まります。

データが届かない場合に影響範囲の広さから疑う5段階の確認順序

順序を固定しておくと迷いません。まずAgentのプロセスが起動しているか。次にサイトパラメータが自社のリージョンと一致しているか。次にAPIキーが有効か。次に送信先への通信がプロキシやセキュリティグループで遮られていないか。最後にインテグレーション個別の権限、たとえば監視用DBユーザに必要な参照権限が付いているか。

この順番にしている理由は、上から順に「影響範囲が広く、確認コストが低い」からです。個別のインテグレーション設定を疑うのは最後で構いません。全データが届いていないなら原因は共通部分にあり、特定のチェックだけ落ちているなら原因はその設定にあります。

Datadog Agentの配置方式を選ぶ条件と、入れ方を変えるべき場面

ここまでの3方式は優劣ではなく、対象の性質で決まります。判断の条件を言い切ります。

採用条件：常駐プロセスの価値が出る監視対象と内部指標の構成基準

Agentを置く価値が明確なのは、ミドルウェアの内部指標やプロセス単位の負荷、コンテナの状態まで取りたい場合です。クラウド事業者のメトリクスAPI経由の連携では、CPU使用率のような外形的な指標までは取れても、スロークエリの発生状況やコネクションプールの枯渇までは届きません。ここを見たいならAgent常駐が要ります。

方式の選び方はこうです。コンテナ化されていない既存サーバはホスト直接インストール。単発のDockerホストはコンテナ版。Kubernetesクラスタは、ノード数が数台でもDaemonSetとCluster Agentの二階建てを最初から組む。クラスタで最初にDaemonSetだけ入れて後からCluster Agentを足すやり方は、設定を二度書くことになりがちです。

複数方式が同一環境に混在すること自体は問題になりません。VMとKubernetesが並存する移行期には、ホスト版とDaemonSet版が同時に動く構成になります。このとき効いてくるのがタグ規則の統一で、方式が違ってもタグが揃っていればダッシュボード側では同じ粒度での扱いが可能です。導入後の運用まで含めて手が足りない場合は、保守運用・内製化支援のように監視基盤の設計と運用体制づくりを外部と組む選択肢もあります。

入れ方の変更または導入を見送るべき構成上の3つの具体的な判断場面

1つ目は、監視対象がマネージドサービスだけで完結している場合です。データベースもキューもすべてマネージドで、自前のサーバプロセスがないなら、Agentを置く先がありません。クラウド側のインテグレーション連携で足ります。

2つ目は、常駐プロセスを増やせない制約がある場合です。リソースが厳しい組み込み寄りの機器や、導入ソフトウェアが審査対象になる環境では、Agent常駐そのものが通りません。この場合は外形監視やログ転送だけに絞る構成を検討します。

3つ目は、短命なコンテナだけで構成される処理です。数秒で終わるジョブに常駐Agentの収集周期は噛み合わず、メトリクスが取れる前に消えます。ここはAgent経由ではなく、アプリ側からメトリクスやトレースを直接送る設計へ寄せる判断になります。

よくある質問：Datadog Agentのインストールと設定に関する疑問

Datadog Agentとは何をするものですか？

監視対象のホストやコンテナに常駐し、メトリクス・ログ・トレースを集めてDatadogへ送る収集プロセスです。Core Agent・Trace Agent・Process Agent・System Probeという役割の異なるプロセスで構成され、何を集めるかは設定ファイルと有効化したインテグレーションで決まります。

設定ファイルはどこに置かれますか？

公式ドキュメントの記載では、Linuxが/etc/datadog-agent/datadog.yaml、macOSが/opt/datadog-agent/etc/datadog.yaml、WindowsはProgramData配下のDatadogフォルダです（2026-08-15時点）。インテグレーション個別の設定は同階層のconf.dディレクトリ配下に置かれます。

Dockerで動かす場合も設定ファイルを編集しますか？

編集しません。公式の説明では、コンテナ化されていない環境でdatadog.yamlに書く項目を、Docker Agentでは環境変数で指定します。設定キーを大文字化してDD_を付けた名前が対応するため、ホスト版のドキュメントから読み替えられます。

Kubernetesではどの方法で入れるのがよいですか？

公式ドキュメントではDatadog Operatorが推奨として案内され、Helmチャートとkubectlによるマニフェスト適用も選べます（2026-08-15時点）。既にHelmで他のミドルウェアを配っているならHelmで揃える判断も現実的で、マニフェスト直書きは更新追随の負担が残ります。

Agentは動いているのにデータが表示されないときは何を見ますか？

サイトパラメータから確認してください。Datadogはdatadoghq.comやap1.datadoghq.comのようにリージョンごとに送信先が分かれており、値が違うとエラーらしいエラーが出ないまま画面に何も出ません。次にstatusコマンドのForwarder部分で送信の成否を見ると、原因が共通部分か個別チェックかを切り分けられます。

関連記事

• Datadog運用のベストプラクティス：Agentを配り終えた後のタグ設計・監視対象の絞り込み・コスト抑制をまとめています。
• Datadog OpenTelemetry連携の4方式：Agent経由で送るか、OTLPで直接送るかという送信経路の選び分けを扱っています。
• Datadog RUM導入の実装手順：ブラウザ側の計測をAgent側のトレースへ紐付ける実装手順です。
• TerraformでDatadogを管理する方法：Agent配布後のモニターやインテグレーションをコードで管理する方法をまとめています。