obsdog

Datadog Fundamentals 認定 / 05 / 06

Datadog のトラブルシューティング

このドメインで学ぶこと

このドメインでは、Agent を導入したのにデータが届かない、インテグレーションが動かない、Agent が起動しないといった場面で、原因を自分で切り分ける手順を学びます。柱は 3 つです。第 1 に status コマンドの出力を読んで状況を把握すること (Running Checks、Collector、Clocks の各節)。第 2 に flare でサポートに必要な情報を安全に渡すこと。第 3 に Agent のログ (場所、ログレベル、ランタイム変更) と設定ファイル (conf.d の読み込み規則、.default、一時無効化) の挙動を理解することです。試験では「この症状のとき最初にどこを見るか」「このサブコマンドは何を診断するか」「この置き方で Agent はどう動くか」という形で問われます。数値や既定値は 2026 年 9 月時点の公式ドキュメントに基づきます。

公式ガイドの内容範囲

  • Agent コマンド (status / flare)
  • Agent のログ
  • Agent の設定ファイル

重要ポイント

  • 公式のチェックリストは、インターネットまたはプロキシへの到達、API キーとサイトの一致、Agent が 1 つだけ動いていること、YAML 編集後の再起動を確認する。
  • status 出力の Running Checks 節に警告もエラーも無く表示されていれば、そのインテグレーションは正しく設定されている。
  • グラフの欠損、メトリクスの遅延、誤ったアラート発火は NTP のずれが原因になり得る。status 出力の Clocks 節で NTP offset を確認する。
  • flare は設定ファイルとログをまとめてサポートに送る仕組みで、パスワードや API キーなどの機微情報は除去され、アップロード前に確認を求められる。
  • diagnose は送信先への接続性を診断し、configcheck は読み込まれて解決された設定を表示する。症状がネットワークか設定かで使い分ける。
  • Linux の Agent ログは /var/log/datadog/ にあり、既定のログレベルは INFO。DEBUG は一定期間だけ有効にし、終わったら INFO に戻す。
  • Agent 6.19 / 7.19 以降は config set log_level debug で再起動なしにログレベルを変えられるが、変更は再起動で失われる。
  • conf.d の <CHECK_NAME>.d/ 内の有効な YAML はすべて読み込まれ、長さ 0 のファイルは無視される。.default は既定の中核チェックを定義する。
  • チェックを一時的に止めるには conf.yaml を .yaml でも .yml でもない拡張子 (conf.yaml.disable など) に改名する。
  • Agent 7.40 以降のコンテナはホスト名を解決できないと起動直後に終了する。Kubelet API やクラウドのメタデータエンドポイントへの到達を確認する。

用語と概念

トラブルシューティングのチェックリスト

公式ドキュメントは、Agent の問題を疑ったときに最初に確認する 7 項目を挙げています。Agent コンテナが起動直後に止まっていないか、インターネットかプロキシに到達できるか、プロキシを使うなら Agent にその設定があるか、API キーが自分のプラットフォームのものか、site が組織のサイトと一致するか、Agent が 1 つだけ動いているか、YAML 編集後に再起動したか。すべて問題が無ければ status コマンド、Agent のログ、DEBUG モードへ進み、それでも分からなければ flare を付けてサポートに連絡します。

status コマンドの出力の読み方

datadog-agent status は Agent とインテグレーションの状態をまとめて表示します。正しく設定されたインテグレーションは Running Checks 節に警告もエラーも無く現れ、Total Runs や Metric Samples などが並びます。Collector 節では動作中のチェックインスタンスの要約と収集メトリクス数が分かり、Agent の CPU やメモリが高いときに原因を絞り込めます。Clocks 節の NTP offset では、グラフの欠損や誤アラートの原因になる時刻のずれを確認できます。

flare

flare は Agent の設定ファイルとログを 1 つのアーカイブに集めてサポートに送る仕組みです。パスワード、API キー、プロキシの資格情報などの機微情報は除去され、アップロード前に確認を求められます。コマンドは sudo datadog-agent flare <ケース番号> で、続けてケースに紐づくメールアドレスを入力します。ケース番号が無ければログイン用のメールアドレスで新しいケースが作られます。Datadog に接続できないときは /tmp に作られたアーカイブを手動で提出します。

診断系サブコマンドの使い分け

Agent の CLI はサブコマンド方式です。トラブルシューティングで使うのは、指定したチェックを実行する check、実行中の Agent が読み込んで解決した全設定を表示する configcheck、接続性を診断する diagnose、Agent の健全性を表示する health、Agent が使うホスト名を表示する hostname、処理中のログを流し見る stream-logs です。チェックが動いているのにデータが届かないなら diagnose、チェックが Running Checks に現れないなら configcheck で確かめるのが基本の切り分けです。

Agent のログファイルとログレベル

Linux の Agent ログは /var/log/datadog/ の agent.log です。macOS は 7.28 以降で /opt/datadog-agent/logs、Windows は C:\ProgramData\Datadog\logs です。ログは既定で 10 MB ごとにロールオーバーし、バックアップは 1 世代です。既定のログレベルは INFO で、OFF から TRACE までの 7 段階から選び、指定したレベル以上が出力されます。DEBUG はログ量が増えるため一定期間だけ有効にし、終わったら INFO に戻します。OFF は引用符が必須です。

ランタイム設定管理

Agent 6.19 / 7.19 以降では、config サブコマンドで一部の設定を再起動なしに変更できます。config list-runtime で変更可能な項目を一覧し、config set log_level debug で値を変え、config get log_level で現在値を確認します。コンテナを作り直さずにログレベルを DEBUG に切り替えられるのが利点ですが、動的な変更は永続せず、Agent が再起動すると元に戻ります。別コンテナで動く trace-agent はランタイム変更に対応せず、DD_LOG_LEVEL を設定して再デプロイします。

conf.d の読み込み規則

インテグレーションの設定は conf.d/<CHECK_NAME>.d/ に置き、Agent はそのフォルダー内の有効な YAML をすべて読み込むため、複数ファイルへ分割できます。長さ 0 のファイルは無視されます。.default 接尾辞のファイルは CPU やメモリなど既定で常に有効な中核チェックを定義し、同じチェックに他の設定があれば無視され、止めたいときは削除します。一時的に止めるには conf.yaml を別の拡張子へ改名します。ログ収集では同じソースを指す複数の YAML は受け付けず、アルファベット順で最初のファイルだけが使われます。

権限と所有者 (dd-agent ユーザー)

Linux の Agent は dd-agent ユーザーで動作し、/var/log/datadog/ とその中のファイルは dd-agent が所有している必要があります。所有者が違うと Permission denied でログが書けないため、ls -l で確認し、sudo chown -R dd-agent:dd-agent /var/log/datadog/ で直して再起動します。起動時に EACCES のソケットエラーが出て、ポート競合も残留プロセスも無い場合は /opt/datadog-agent/run の所有者を疑います。root で動かすのは回避策にすぎません。

コンテナでのホスト名解決の失敗

Agent 7.40 以降は、コンテナ環境でホスト名を確実に決められないと起動直後にエラーを出して終了し、ログに Error while getting hostname, exiting と記録されます。Kubernetes では Kubelet API、クラウドのメタデータエンドポイント、コンテナランタイム API のどれかに到達できないことが原因で、最も多いのは Kubelet の TLS 証明書検証の失敗です。この場合は DD_KUBELET_TLS_VERIFY を false にします。CI やサイドカーでは DD_HOSTNAME を明示します。

理解度チェック

学んだ内容を 5 問で確認します