Agent v6 の変更点

Agent のメインコンフィギュレーションファイルは INI 形式から YAML 形式に移行し、複雑なコンフィギュレーションをサポートし、Agent とチェック全体で一貫したエクスペリエンスを提供します。

Agent v5 datadog.conf –> Agent v6 datadog.yaml

Agent コンフィギュレーションのパスと形式を切り替えるには、以下の Agent コマンドを使用します。

sudo -u dd-agent -- datadog-agent import

このコマンドは、既存の datadog.conf を解析し、サポートされているパラメーターを datadog.yaml の新しい形式に変換します。このコマンドは、現在有効になっているチェックのコンフィギュレーションファイルもコピーします。詳細については、Datadog Agent v6 へのアップグレードを参照してください。

オプション

次の Agent コンフィギュレーションオプションは、Agent v6 で変更または削除されました。削除されたコンフィギュレーションオプションは、他のオプションに置き換えられたか、以前のバージョンとは異なる動作をする機能に関連しています。

変更

削除

Agent v6 は、有効な YAML ファイルを <AGENT_DIRECTORY>/conf.d/<CHECK_NAME>.d/ にロードします。これにより、複雑なコンフィギュレーションを複数のファイルに分割できます。

たとえば、http_check のコンフィギュレーションファイルは以下のようになります。

/etc/datadog-agent/conf.d/http_check.d/
├── backend.yaml
└── frontend.yaml

Agent は、<CHECK_NAME>.d フォルダー内のサブディレクトリからコンフィギュレーションファイルをロードしません。たとえば、次のコンフィギュレーションはロードされません。

/etc/datadog-agent/conf.d/http_check.d/prod.d/
├── backend.yaml

オートディスカバリーテンプレートファイル (auto_conf.yaml) もコンフィギュレーションフォルダーに保存されます。以下は redisdb チェックコンフィギュレーションフォルダーの例です。

/etc/datadog-agent/conf.d/redisdb.d/
├── auto_conf.yaml
└── conf.yaml.example

<CHECK_NAME>.d フォルダー内の YAML ファイルには、.yaml または .yml 拡張子が付いている限り、どんな名前でも付けることができます。標準名は conf.yaml です。

下位互換性を維持するため、Agent は <AGENT_DIRECTORY>/conf.d/<CHECK_NAME>.yaml の形式でコンフィギュレーションファイルを処理しますが、更新されたレイアウトへの移行を強くおすすめします。

コンフィギュレーションオプション

Agent v6 は、チェックの instance セクションで次のオプションをサポートしています。

Agent v6 で使用される環境変数のほとんどは、以前のバージョンとは異なります。Agent v6 の環境変数のリストを参照してください。

注: DD_TAGS は同じタグですが、Agent v6 では形式がスペースで区切られています。以前のバージョンはカンマで区切られていました。v6 の例: DD_TAGS="simple-tag-0 tag-key-1:tag-value-1"

プロキシ

v6.4.0 以降の場合、Agent プロキシ設定は次の環境変数でオーバーライドできます。

標準環境変数 (HTTP_PROXY、HTTPS_PROXY、NO_PROXY) は Agent v6 でサポートされていますが、DD_PROXY_* 変数を使用することをお勧めします。DD_PROXY_* 変数は他のプロキシ変数よりも優先されます。

Agent v6 のプロキシオプションの優先順位は、以前のバージョンとは異なります。

• Agent v6 は、最初に環境変数を使用し、次にコンフィギュレーションファイルを使用します。
• Agent v6 は、コンフィギュレーションファイルの値を環境内の値でオーバーライドします。たとえば、コンフィギュレーションファイルで proxy.http と proxy.https の両方が設定されていて、環境で DD_PROXY_HTTPS のみが設定されている場合、Agent は環境の https 値とコンフィギュレーションファイルの http 値を使用します。

Agent v5 と Agent v6 ではホスト名解決に違いがあります。詳細については、専用ドキュメントをご覧ください。

Linux 上の Agent v6 の主な変更点は次のとおりです。

• Agent の_ライフサイクルコマンド_ (start/stop/restart/status) だけは sudo service/sudo initctl/sudo systemctl で実行する必要があります。
• 他のすべてのコマンドは、デフォルトで datadog-agent として PATH (/usr/bin) にある Agent バイナリで呼び出す必要があります。dd-agent コマンドは使用できなくなりました。
• info サブコマンドは status に名前が変更されました。
• Agent v6 には SysV-init スクリプトが付属していません (以前は /etc/init.d/datadog-agent にありました)。

サービスライフサイクルコマンド

システムで service ラッパーコマンドが使用できる場合、ライフサイクルコマンドに変更はありません。 たとえば Ubuntu の場合、_ライフサイクルコマンド_は次のとおりです。

ご使用のシステムで service ラッパーコマンドを使用できない場合は、以下を使用してください。

• upstart ベースのシステムの場合: sudo start/stop/restart/status datadog-agent
• systemd ベースのシステムの場合: sudo systemctl start/stop/restart/status datadog-agent

ディストリビューションがデフォルトで使用する init システムが不明な場合は、以下の表を参照してください。

Agent のコマンド

Agent v6 以降では、他の機能は Agent バイナリ自体によってサブコマンドとして提供されるため、service/systemctl/initctl で呼び出すことはできません。以下にいくつかの例を示します。

Windows 上の Agent v6 の主な変更点は次のとおりです。

• Agent v5 Windows Agent Manager GUI は、ブラウザベースのクロスプラットフォームマネージャーに置き換えられました。詳細については、Windows 用 Datadog Agent Manager を参照してください。
• メインの実行可能ファイルは agent.exe (以前は ddagent.exe) です。
• Administrator コマンドプロンプトからコマンドライン "%PROGRAMFILES%\datadog\datadog agent\embedded\agent.exe" <COMMAND> を使用してコマンドを実行する必要があります。
• Windows サービスが「自動遅延」として開始されます。起動時に自動的に開始されますが、他のすべてのサービスの後に開始されます。これにより、再起動後のメトリクスのレポートにわずかな遅延が生じます。
• Windows GUI と Windows システムトレイアイコンが個別に実装されるようになりました。詳細については、Windows 用 Datadog Agent Manager を参照してください。

MacOS 上の Agent v6 の主な変更点は次のとおりです。

• ライフサイクルコマンド (以前は datadog-agent start/stop/restart/status) は、com.datadoghq.agent サービスの launchctl コマンドに置き換えられ、ログインユーザーで実行される必要があります。これらのコマンドでは、Datadog Agent systray アプリを使用することもできます。
• 他のすべてのコマンドは、デフォルトで PATH (/usr/local/bin/) にある datadog-agent バイナリで実行できます。
• info コマンドは status に名前が変更されました。
• コンフィギュレーション GUI は Web ベースのアプリケーションになり、コマンド datadog-agent launch-gui を実行するか、systray アプリを使用してアクセスできます。

変更例:

APM Agent は、Linux、MacOS、Windows 用の Agent v6 パッケージにデフォルトで付属しています。

Linux では、APM Agent はデフォルトで有効になっています。他のプラットフォームで有効または Linux で無効にするには、datadog.yaml の apm_config キーを更新します。

apm_config:
  enabled: true

Docker イメージの場合、APM Agent はデフォルトで無効になっています。DD_APM_ENABLED を true に設定して有効にします。デフォルトではすべてのインターフェイスをリッスンします。他のプラットフォームでローカル以外のトラフィックをリッスンする場合は、DD_APM_NON_LOCAL_TRAFFIC を true に設定します。詳細については、Docker アプリケーションのトレースを参照してください。

Process Agent は、Linux 用の Agent v6 パッケージにのみデフォルトで付属しています。

Process Agent はデフォルトでは有効になっていません。有効にするには、datadog.yaml ファイルを次のように更新します。

process_config:
  enabled: "true"

enabled の値は文字列で、以下のオプションがあります。

• "true": プロセス Agent を有効にして、プロセスとコンテナを収集します。
• "false": コンテナがあれば、コンテナのみを収集します (デフォルト)。
• "disabled": Process Agent を実行しません。

Agent v6 では、Docker バージョン 1.12.1 以降がサポートされています。

Docker チェックは、Agent の内部アーキテクチャを利用するために Go で書き直されました。したがって、Python バージョン (docker_daemon) は非推奨になりました。

新しいチェックの名前は docker です。Agent インポートコマンドは、レガシーの docker_daemon.yaml コンフィギュレーションから設定をインポートします。以下を除くすべての機能が移植されています。

• url、api_version、tags* は非推奨になりました。標準の Docker 環境変数を使用することをお勧めします。
• ecs_tags、performance_tags、container_tags は非推奨になりました。すべての関連タグはデフォルトで収集されます。
• docker.container.count メトリクスを有効にする collect_container_count の使用はサポートされません。docker.containers.running と .stopped を使用してください。

一部のオプションは docker_daemon.yaml からメインの datadog.yaml に移動しました。

• collect_labels_as_tags は docker_labels_as_tags に名前が変更され、カーディナリティの高いタグをサポートします。詳細については、タグの割り当てと抽出を参照してください。
• exclude と include は ac_include と ac_exclude に名前が変更されました。Agent のすべてのコンポーネントで絞り込みを一貫させるために、任意のタグでの絞り込みはなくなりました。タグの絞り込みは、image (イメージ名) および name (コンテナ名) でのみサポートされています。正規表現の絞り込みは引き続き使用できます。詳細については、コンテナディスカバリー管理を参照してください。
• docker_root オプションは、container_cgroup_root と container_proc_root の 2 つのオプションに分割されました。
• Kubernetes と Openshift で一時停止中のコンテナを除外するために exclude_pause_container が追加されました (デフォルトは true です)。

Agent v6 では、Kubernetes バージョン 1.3 以降がサポートされています。

Kubernetes インテグレーションは、以下を組み合わせることによって情報を提供します。

• kubelet からの kubelet チェックメトリクス。
• API サーバーからの kubernetes_apiserver チェックイベントとサービスチェック。

Agent インポートコマンド (v6.2 以降) は、レガシーの kubernetes.yaml コンフィギュレーションから設定をインポートします。次のオプションは非推奨になりました。

• API サーバーの認証情報 (api_server_url、apiserver_client_crt、apiserver_client_key、apiserver_ca_cert): 代わりに、kubenetes_kubeconfig_path を使用して Agent に kubeconfig ファイルを提供します。
• use_histogram: Datadog のサポートチームに問い合わせて、最適な代替案を決めてください。
• namespaces と namespace_name_regexp: Agent v6 は、使用可能なすべてのネームスペースからメトリクスを収集します。

アップグレードされたロジックでは、Kubernetes バージョン 1.7.6 以降と互換性のある Prometheus メトリクス収集が有効になります。古いバージョンを実行しているか、cadvisor 収集ロジックに戻したい場合は、cadvisor_port を 4194 (kubelet が cadvisor を公開するポート) に設定します。

kubernetes_state チェックは、Agent v5 または Agent v6 で機能します。

タグ付け

Agent v5 はすべてのポッドラベルをタグとして自動的に収集しましたが、Agent v6 にはホワイトリストが必要です。これは、datadog.yaml の kubernetes_pod_labels_as_tags オプションで行われます。詳細については、タグの割り当てと抽出を参照してください。

次のオプションとタグは非推奨になりました。

• label_to_tag_prefix は kubernetes_pod_labels_as_tags に置き換えられました。
• container_alias タグは収集されません。
• kube_replicate_controller は、ポッドがレプリケーションコントローラーによって作成された場合にのみ追加されます。代わりに、関連するクリエイタータグ (kube_deployment や kube_daemon_set など) を使用してください。

Agent v6 には JMXFetch が付属していますが、次の変更が加えられています。

JMXTerm JAR

Agent v6 には jmxterm JAR が付属していません。jmxterm をダウンロードして使用するには、アップストリームプロジェクトを参照してください。

トラブルシューティングコマンド

トラブルシューティングのコマンド構文が変更されました。これらのコマンドは v6.2.0 以降で使用できます。以前のバージョンについては、JMX Agent のトラブルシューティングを参照してください。

注: デフォルトでは、これらのコマンドは構成済みのすべての JMX チェックで実行されます。チェックを指定するには、--checks フラグを使用します。例: sudo datadog-agent jmx list collected --checks tomcat

Windows Agent のみに影響します

Windows Agent v5 の場合、system.mem.pagefile.* メトリクスは一貫性のない単位を表示します (10^6 でオフ)。

この問題は、Windows Agent v6 で修正されています。ただし、下位互換性のために Agent v5 の不一致は残っています。したがって、Agent v5 から Agent v6 にアップグレードする場合、報告される値 (および関連するモニター) は異なります。

Kubernetes を使用する場合、オートディスカバリーは Docker デーモンではなく kubelet から情報を取得します。これにより、Docker ソケットにアクセスしなくてもオートディスカバリーが機能します。また、デフォルトの動作では、ポッドアノテーションからオートディスカバリーテンプレートを取得します。docker コンフィギュレーションプロバイダーを有効にしてコンテナラベルを使用し、ポッドが不足しているコンテナでオートディスカバリーが必要な場合は、kubelet リスナーを Docker リスナーに置き換えることができます。

ポッドアノテーションでオートディスカバリーテンプレートを指定する場合、アノテーション名のプレフィックスは ad.datadoghq.com/ です。以前のアノテーションプレフィックス (service-discovery.datadoghq.com/) は Agent v6 でも引き続きサポートされていますが、サポートは将来のバージョンで削除される予定です。

Docker ラベルのオートディスカバリーテンプレートは、同じ名前のプレフィックス com.datadoghq.ad.* で機能します。

一貫性を保つため、識別子オーバーライドラベルの名前が com.datadoghq.sd.check.id から com.datadoghq.ad.check.id に変更されました。以前の名前は Agent v6 でも引き続きサポートされていますが、サポートは将来のバージョンで削除される予定です。

Agent v6 は Python チェックを完全にサポートしていますが、公式の Agent v5 インテグレーションの一部は削除または置き換えられています。

• agent_metrics - 削除
• docker_daemon - Docker チェックに置き換えられました
• kubernetes - Kubernetes チェックに置き換えられました

Python チェックの基本クラス (AgentCheck) が datadog_checks.base.checks からインポートされました。クラス API で削除または変更されたものは多数あります。さらに、各チェックインスタンスは、クラスの独自のインスタンスになりました。したがって、それらの間で状態を共有することはできません。

AgentCheck クラスの以下のメソッドは実装されていません。

• service_metadata
• get_service_metadata
• generate_historate_func
• generate_histogram_func
• stop

メトリクス送信者の関数シグニチャが変更されました。

# 以前のバージョン
gauge(self, metric, value, tags=None, hostname=None, device_name=None, timestamp=None)

# Agent v6
gauge(self, name, value, tags=None, hostname=None, device_name=None)

次のメソッドは、AgentCheck から完全に削除されました。

• _roll_up_instance_metadata
• instance_count
• is_check_enabled
• read_config
• set_check_version
• set_manifest_path
• _get_statistic_name_from_method
• _collect_internal_stats
• _get_internal_profiling_stats
• _set_internal_profiling_stats
• get_library_versions
• get_library_info
• from_yaml
• get_service_checks
• has_warnings
• get_metrics
• has_events
• get_events

注: すべての公式インテグレーションは廃止されたメソッドを削除するように更新されたため、これらの変更はカスタムチェックにのみ影響します。

優先度

Agent v6 では、公式チェックはカスタムチェックよりも優先されます (<AGENT_DIRECTORY>/checks.d のチェック)。公式チェックと同じ名前のカスタムチェックは無視されます。

Agent v6 でカスタムチェックのセットアップを修正するには、影響を受けるカスタムチェックの名前を新しい未使用の名前に変更し、それに応じて関連する .yaml コンフィギュレーションファイルの名前を変更します。

依存関係

カスタムチェックを使用する場合、コードが Agent v6 にバンドルされなくなった Python コードに依存する可能性があります。次のパッケージは、Agent にバンドルされなくなりました。

• backports.ssl-match-hostname
• datadog
• decorator
• future
• futures
• google-apputils
• pycurl
• pyOpenSSL
• python-consul
• python-dateutil
• python-etcd
• python-gflags
• pytz
• PyYAML
• rancher-metadata
• tornado
• uptime
• websocket-client

コードがこれらのパッケージのいずれかに依存している場合は、次のコマンドを実行して、不足しているパッケージをインストールします。

sudo -u dd-agent -- /opt/datadog-agent/embedded/bin/pip install <PACKAGE_NAME>

同様に、Agent v5 でカスタムチェックの要件を満たすために PIP パッケージを追加した可能性があります。追加された PIP パッケージに、すでに Agent v5 にバンドルされているパッケージとの内部依存関係がある場合 (上記のリストを参照)、Agent v6 にアップグレードした後、それらの依存関係は失われます。上記の説明に従って、不足している依存関係をインストールします。