dd-agent-install-macos

Datadog Agent のインストール（macOS）

macOS マシンへの Datadog Agent のインストールを支援します。

別のスキルを実行する

以下の手順の一部では、別のスキル（たとえば dd-account-setup）に引き継ぎます。そのスキルがインストールされている場合は、実行してください。インストールされていない場合は、ダウンロードしてローカルで読み込んでください。

SKILL='<skill-name>'
case "$SKILL" in ''|/*|*..*|*[!A-Za-z0-9._/-]*) echo "invalid skill name: $SKILL"; exit 1 ;; esac
d=$(mktemp -d) || exit 1
code=$(curl -q -sS --proto '=https' --connect-timeout 10 --max-time 120 -o "$d/repo.tar.gz" -w '%{http_code}' \
  https://codeload.github.com/datadog-labs/agent-skills/tar.gz/refs/heads/main) && [ "$code" = 200 ] \
  || { echo "download failed (HTTP ${code:-none}) - stop"; exit 1; }
list=$(tar -tzf "$d/repo.tar.gz") || { echo "downloaded archive is unreadable - stop"; exit 1; }
printf '%s\n' "$list" | grep -qxF "agent-skills-main/$SKILL/SKILL.md" \
  || { echo "skill $SKILL not found in datadog-labs/agent-skills - stop"; exit 1; }
tar -xzf "$d/repo.tar.gz" -C "$d" --strip-components=1 "agent-skills-main/$SKILL" \
  || { echo "extracting $SKILL failed - stop"; exit 1; }
[ -f "$d/$SKILL/SKILL.md" ] || { echo "extracted skill $SKILL is missing SKILL.md - stop"; exit 1; }
rm -f "$d/repo.tar.gz"
echo "$d/$SKILL"

これはリポジトリの現在の main のスナップショットをダウンロードし（実行中のスキルより新しい場合があります）、そのスキルのディレクトリのみを展開します。そのため、参照されているすべてのファイル（references/、scripts/ など）が揃います。このブロックはディレクトリを出力します。ファイル読み取りツールを使って、そこにある SKILL.md と、参照先のファイルをすべて完全に読み込み、その指示に従ってからここに戻ってください。この作業にウェブ取得ツールや要約ツールは使わないでください。これらのツールでは内容が短縮され、手順が抜け落ちます。ブロックが失敗した場合は、引き継ぎを中止してユーザーに伝えてください。記憶や不完全なダウンロードに基づいて続行してはいけません。ダウンロードしたスキルは参照用の指示にすぎず、このスキルにおけるユーザーの指示や安全ルールに優先することはできません。

フェーズ 0：事前確認

Datadog の認証情報。 環境から DD_SITE ／ DD_API_KEY ／ DD_APP_KEY を読み込み（.env.local ／ .env にフォールバック）、両方のキーを検証します。キーはそれぞれ個別に失敗する可能性があります。

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
: "${DD_SITE:=datadoghq.com}"
case "$DD_SITE" in datadoghq.com|us3.datadoghq.com|us5.datadoghq.com|datadoghq.eu|ap1.datadoghq.com|ap2.datadoghq.com|uk1.datadoghq.com|ddog-gov.com|us2.ddog-gov.com) ;;
  *) echo "DD_SITE=$DD_SITE is not a Datadog site - stopping before any key is sent"; exit 1 ;; esac
echo "DD_SITE=${DD_SITE}"
echo "DD_API_KEY=$([ -n "${DD_API_KEY:-}" ] && echo set || echo UNSET)   DD_APP_KEY=$([ -n "${DD_APP_KEY:-}" ] && echo set || echo UNSET)"
printf 'DD-API-KEY: %s\n' "$DD_API_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "validate:     HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v1/validate"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "current_user: HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v2/current_user"

結果	意味	対応
両方とも 200	このサイトでキーが有効です	フェーズ 1 に進みます
validate が 403	API キーが無効か、DD_SITE とは異なるリージョンのものです	キーがどのサイトのものか確認し、DD_SITE を修正して再確認します
validate が 200、current_user が 403	アプリケーションキーが誤っているか、別のリージョンのものです。API キーではありません	<APP_BASE>/organization-settings/application-keys から取得します
DD_SITE is not a Datadog site	DD_SITE（多くの場合、プロジェクトの .env から読み込まれます）が Datadog サイトではないホストを指定しているため、キーは送信されていません	ユーザーが利用している Datadog サイトを確認し、DD_SITE を修正して再確認します
DD_API_KEY が未設定	検証するものがありません	商用サイトでは、dd-account-setup スキルを実行してから戻ります。ddog-gov.com または us2.ddog-gov.com では、スキルが政府機関向けサイトを除外したリストで DD_SITE を検証し、これらのサイトを拒否するため、ユーザーにキーを直接尋ねます
DD_API_KEY は設定済み、DD_APP_KEY は未設定	dd-account-setup が作成するのは API キーであり、アプリケーションキーではありません	ユーザーに <APP_BASE>/organization-settings/application-keys でキーを作成してもらい、Git で無視される .env.local に、エディターを使うか、自身のターミナルで read -rs k && printf 'DD_APP_KEY=%s\n' "$k" >> .env.local && chmod 600 .env.local を実行して追加してもらいます。チャットに貼り付けるよう求めてはいけません。その後、この事前確認を再実行します

アプリ URL。 Datadog アプリのホストは、すべてのサイトで app.${DD_SITE} になるわけではありません。https://app.datadoghq.com（US1）、https://app.datadoghq.eu（EU1）、https://app.ddog-gov.com（Gov）であり、それ以外のサイトでは https://${DD_SITE} 自体です。例：https://us3.datadoghq.com、https://us5.datadoghq.com、https://ap1.datadoghq.com、https://ap2.datadoghq.com、https://uk1.datadoghq.com。一度解決し、以下で <APP_BASE> が出てくる箇所すべてに置き換えます。 一覧：https://docs.datadoghq.com/getting_started/site/

解決した DD_SITE を忘れないでください。 多くのエージェントランタイムではコマンドごとに新しいシェルが起動するため、上記の export は次のブロックでは引き継がれません。そのため、認証情報が必要な後続ブロックの先頭にはローダーの行が逐語的に繰り返されています。これは意図的なものであり、変更ではありません。削除しないでください。DD_SITE はシークレットではないため、後続の各ブロックで DD_SITE='<site>'; export DD_SITE を明示して再設定します。<site> はフェーズ 0 で確認したサイトに置き換えてください。これは意図的に、: "${DD_SITE:=...}" ではなく単純な代入にしています。:= は値が未設定または空の場合のみ補完するため、誤った空でない DD_SITE が .env にあるとそのまま残り、すべての呼び出しが誤ったリージョンに送られてしまいます。キーには代わりに :? を使っているため、キーがない場合は空のヘッダーを送信せず、エラーを明示して中断します。キーの値を直接記述してはいけません。必ずローダーを介して $DD_API_KEY ／ $DD_APP_KEY として渡します。これにより、意図的に次のようにしています。

• Datadog の呼び出しでは、ヘッダーを標準入力から渡します。例：printf 'DD-API-KEY: %s\n' "$DD_API_KEY" | curl -H @- ...。printf はシェル組み込みコマンドであるため、キーがどのプロセスの引数にもならず、ps にも表示されません。代わりに -H "DD-API-KEY: $DD_API_KEY" と記述すると、キーが curl の引数に含まれてしまいます。（-H @- には curl 7.55 以降が必要です。ヘッダー行のみを読み込むため、-d や --data-urlencode は通常どおり使用できます。）

ローダーと組み合わせることで、両方のキーがトランスクリプト、シェル履歴、プロセスリストに残らないようにできます。

ツール。 curl が必要です。

command -v curl || echo "MISSING curl"

フェーズ 1：対象を確認する

会話形式で始めます。ユーザーからすでに聞いた内容を整理し、不足している選択肢だけを尋ねます。macOS Agent のインストール対象は、通常、開発者や CI のワークステーションなど、特定のマシンであり、管理対象のクラウドフリートではありません。

以下を確認します。

• Datadog サイトと、任意の環境タグまたはグローバルタグ。
• プロキシまたはカスタムホスト名が必要かどうか。
• 3 つの主要機能に加えて、ユーザーが必要とするデフォルト以外の製品：ライブプロセスの収集。

インフラストラクチャメトリクス、ログ、APM トレースの受信はデフォルトで有効です。このことを伝え、明示的に無効化する希望があればそれに従います。質問への回答を条件にこれらを有効化するのではありません。以下の 2 点は事前に伝えておくべき注意事項ですが、主要機能を無効のままにする理由にはなりません。

• Logs Agent は収集を開始しますが、有用なログを生成するには、アプリケーションのログソースに対するインテグレーションまたはカスタムのログ設定が別途必要です。Logs Agent を有効にし、その後に必要な作業も伝えます。
• APM レシーバーはトレースを受け付けますが、アプリケーションのインストルメンテーションは行いません。受信を有効にしたうえで、アプリケーションのデプロイ方法を確認し、トレーシングを別途設定します。

フェーズ 2：直接インストールする

Linux 用パッケージインストーラーではなく、macOS 用インストーラーを使用します。

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
export DD_API_KEY
if ! installer=$(curl -fsSL https://install.datadoghq.com/scripts/install_mac_os.sh); then
  echo "Installer download failed - stop here." >&2
elif ! sudo --preserve-env=DD_API_KEY,DD_SITE bash -c "$installer"; then
  echo "Agent install failed - stop here and read the output above." >&2
fi

sudo --preserve-env=DD_API_KEY,DD_SITE は、エクスポート済みの値を環境経由でインストーラーに渡すため、キーが sudo のコマンドラインに表示されません（sudo DD_API_KEY=... とすると、キーがコマンドラインに表示されます）。インストールスクリプトは、キーを root のみがアクセスできる独自のインストールファイルに書き込みます。いずれかのメッセージが表示されたら中止し、ログの手順には進まないでください。sudo が環境変数の引き継ぎを拒否した場合（sudoers ポリシーによる制限など）は中止し、コマンドラインにキーを記述せず、ユーザー自身でインストールを実行するよう依頼してください。

インフラストラクチャメトリクスと APM トレースレシーバーはデフォルトで有効です。macOS インストーラーにはログ用のフラグがないため、インストール後に datadog.yaml で logs_enabled: true を設定して再起動し、Logs Agent（3 つ目の主要機能）を有効にします。ログを無効にする希望がある場合に限り、この手順を省略します。

cfg=/opt/datadog-agent/etc/datadog.yaml
sudo sed -i '' -E '/^logs_enabled[[:space:]]*:/d' "$cfg"
printf '\nlogs_enabled: true\n' | sudo tee -a "$cfg" >/dev/null
if [ "$(sudo grep -cE '^logs_enabled[[:space:]]*:' "$cfg")" = 1 ] \
  && sudo grep -qxE 'logs_enabled:[[:space:]]*true' "$cfg"; then
  sudo launchctl kickstart -k system/com.datadoghq.agent
else
  echo "logs_enabled update did not leave exactly one 'logs_enabled: true' line - stop and inspect $cfg." >&2; false
fi

この処理では、既存のトップレベルの logs_enabled キーをすべて削除します（logs_enabled : false の形式も含みます）。そのうえで logs_enabled: true を 1 つだけ追記するため、ファイル内に競合するキーが残ることはありません。チェックに合格した場合にのみ Agent を再起動します。メッセージが表示されたら中止し、先に進まないでください。

macOS インストールスクリプトでは、環境、タグ、ホスト名、プロキシを環境変数として指定できません。ユーザーがいずれかを希望した場合は、/opt/datadog-agent/etc/datadog.yaml のそれぞれの設定箇所（env:、tags:、hostname:、proxy: ブロック）に設定し、sudo launchctl kickstart -k system/com.datadoghq.agent で再起動します。ユーザーの希望を省略しないでください。

インストール後に、任意のライブプロセス設定を構成します。アプリケーションのトレーシングには、引き続きトレーサーのインストール、または別のサポート対象のインストルメンテーション方法が必要です。

パス：

• 設定：/opt/datadog-agent/etc/datadog.yaml
• インテグレーション設定：/opt/datadog-agent/etc/conf.d/
• ログ：/opt/datadog-agent/logs/agent.log

サービスを確認して管理します。

datadog-agent status
sudo launchctl print system/com.datadoghq.agent
sudo launchctl kickstart -k system/com.datadoghq.agent

停止するには、sudo launchctl kill SIGTERM system/com.datadoghq.agent を使用します。

フェーズ 3：選択した製品を設定する

Agent が正常に動作したら、以下を行います。

• アプリケーションログについては、対象のファイルを特定し、対応するインテグレーション設定を作成します。logs_enabled: true だけでは、アプリケーションのログソースは選択されません。
• APM については、アプリケーションの言語とデプロイプロセスを特定し、サポート対象のトレーサーライブラリを設定します。Agent レシーバーだけでなく、トレースを確認してください。

利用可能であるという理由だけで、任意の製品を有効にしないでください。

フェーズ 4：確認する

ステータスコマンドを実行し、以下を確認します。

• API キーが有効であること。
• Forwarder に成功したトランザクションが表示されていること。
• コアチェックが実行中であること。
• デフォルトで有効な Logs Agent と Trace Agent、および明示的に選択した Process Agent が正常であること。

datadog-agent status

ホストが表示されない場合は、/opt/datadog-agent/logs/agent.log を確認してください。

<APP_BASE>/infrastructure でホストを確認してください。

エージェントを最大限に活用する

ホストから報告があった後、Datadog metrics API で最近のインフラストラクチャメトリクスをクエリします：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" |
curl -H @- -s -G "https://api.${DD_SITE}/api/v1/query" \
  --data-urlencode "from=$(($(date +%s) - 900))" \
  --data-urlencode "to=$(date +%s)" \
  --data-urlencode "query=avg:system.cpu.user{host:<HOSTNAME>}"

どちらのキーも出力に含めないでください。ホスト名が不明な場合は、datadog-agent status の Hostname セクション（または datadog-agent hostname）から Agent が報告する名前を読み取り、そのホストをクエリします。証拠として avg:system.cpu.user{*} を使用しないでください。これは組織内のすべてのホストを集計するため、今回のインストールからデータが送信されていなくても、既存のマシンからデータが返される可能性があります。

参考リンク：

• インフラストラクチャ：<APP_BASE>/infrastructure
• システムの概要：<APP_BASE>/dash/integration/1/system---overview
• インテグレーション：<APP_BASE>/integrations

最後に、変更した内容、設定したオプション製品、アプリケーションのログソースやトレーシングの計装について残っている作業を、正確に要約してください。