カスタム Agent チェックの書き方

概要

このページでは、min_collection_interval を使用してサンプルのカスタム Agent チェックを作成し、サンプルのカスタムチェックを拡張するためのユースケースの例を示します。カスタムチェックは、Agent ベースのインテグレーションと同じ固定間隔で実行されます。デフォルトでは 15 秒ごとです。

セットアップ

インストール

カスタム Agent チェックを作成するには、まず Datadog Agent をインストールします。

注: Agent v7+ を実行している場合、Agent チェックは Python 3 と互換性がある必要があります。それ以外の場合は Python 2.7+ との互換性が必要です。

構成

  1. システムの conf.d ディレクトリに移動します。conf.d ディレクトリの場所の詳細については、Agent コンフィギュレーションファイルを参照してください。
  2. conf.d ディレクトリに、新しい Agent チェック用の新しいコンフィギュレーションファイルを作成します。ファイルに custom_checkvalue.yaml という名前を付けます。
  3. ファイルを編集して、以下を含めます。

    conf.d/custom_checkvalue.yaml

    init_config:
instances:
  [{}]
  4. checks.d ディレクトリにチェックファイルを作成します。ファイルに custom_checkvalue.py という名前を付けます。
    コンフィギュレーションファイルとチェックファイルの名前は一致している必要があります。チェックの名前が `custom_checkvalue.py` の場合、コンフィギュレーションファイルの名前は `custom_checkvalue.yaml` である必要があります。
  5. ファイルを編集して、以下を含めます。

    checks.d/custom_checkvalue.py

    from checks import AgentCheck
class HelloCheck(AgentCheck):
  def check(self, instance):
    self.gauge('hello.world', 1)
  6. Agent を再起動します。1 分以内に、メトリクスサマリーに hello.world という新しいメトリクスが表示されます。

Python チェックファイルは、Agent ユーザーが読み取り可能で、実行可能でなければなりません。

結果

1 分以内に、メトリクスサマリーに hello.world という新しいメトリクスが表示されます。これは 1 の値を送信します。

注: カスタムチェックの名前を選択する際は、既存の Datadog Agent インテグレーションの名前との競合を避けるため、名前の前に custom_ を付けてください。たとえば、カスタム Postfix チェックの場合、チェックファイルの名前は、postfix.py と postfix.yaml ではなく、custom_postfix.py と custom_postfix.yaml にします。

収集間隔の更新

チェックの収集間隔を変更するには、custom_checkvalue.yaml ファイルで min_collection_interval を使用します。デフォルト値は 15 です。Agent v6 の場合、min_collection_interval をインスタンスレベルで追加し、インスタンスごとに個別に構成する必要があります。例:

conf.d/custom_checkvalue.yaml

init_config:

instances:
  - min_collection_interval: 30

注: min_collection_interval を 30 に設定しても、メトリクスが 30 秒ごとに収集されるというわけではなく、最短 30 秒ごとに収集されるという意味になります。コレクターはチェックを 30 秒ごとに実行しようとしますが、同じ Agent で有効にされているインテグレーションとチェックの数によっては、待機しなけらばならない場合があります。さらに、check メソッドが終了までに 30 秒以上かかった場合も、Agent はチェックがまだ実行中であると認識し、次の間隔まで実行をスキップします。

チェックの検証

チェックが実行されていることを確認するには、次のコマンドを使用します。

sudo -u dd-agent -- datadog-agent check <CHECK_NAME>

チェックが実行されていることを確認したら、Agent を再起動してチェックを含め、Datadog へのデータのレポートを開始します。

コマンドラインプログラムを実行するチェックの書き方

コマンドラインプログラムを実行し、その出力をカスタムメトリクスとしてキャプチャするカスタムチェックを作成することができます。たとえば、チェックで vgs コマンドを実行して、ボリュームグループに関する情報を報告できます。

チェック内でサブプロセスを実行するには、モジュール datadog_checks.base.utils.subprocess_output にある get_subprocess_output() 関数を使用します。get_subprocess_output() には、コマンドと引数を文字列としてリスト形式で渡します。

例

たとえば、次のようにコマンドプロンプトで入力されるコマンド:

vgs -o vg_free

次のように get_subprocess_output() に渡します。

out, err, retcode = get_subprocess_output(["vgs", "-o", "vg_free"], self.log, raise_on_empty_output=True)

注: チェックを実行する Python インタープリターは、マルチスレッド Go ランタイムに埋め込まれるため、Python 標準ライブラリにある subprocess または multithreading モジュールの使用は、Agent バージョン 6 以降ではサポートされていません。

結果

コマンドラインプログラムを実行すると、チェックはターミナルのコマンドラインで実行されているのと同じ出力をキャプチャします。出力で文字列処理を実行し、結果で int() または float() を呼び出して、数値型を返します。

If you do not do string processing on the output of the subprocess, or if it does not return an integer or a float, the check appears to run without errors but doesn’t report any metrics or events. The check also fails to return metrics or events if the Agent user does not have the correct permissions on any files or directories referenced in the command, or the correct permissions to run the command passed as an argument to get_subprocess_output().

以下に、コマンドラインプログラムの結果を返すチェックの例を示します。

# ...
from datadog_checks.base.utils.subprocess_output import get_subprocess_output

class LSCheck(AgentCheck):
    def check(self, instance):
        files, err, retcode = get_subprocess_output(["ls", "."], self.log, raise_on_empty_output=True)
        file_count = len(files.split('\n')) - 1  #len() はデフォルトで int 値を返します
        self.gauge("file.count", file_count,tags=['TAG_KEY:TAG_VALUE'] + self.instance.get('tags', []))

ロードバランサーからのデータ送信

カスタム Agent チェックを書く一般的なユースケースは、ロードバランサーから Datadog メトリクスを送信することです。始める前に、構成のステップに従います。

ロードバランサーからデータを送信するためのファイルを展開するには

  1. custom_checkvalue.py のコードを次のように置き換えます (lburl の値をロードバランサーのアドレスに置き換えます)。

    checks.d/custom_checkvalue.py

    import urllib2
import simplejson
from checks import AgentCheck

class CheckValue(AgentCheck):
  def check(self, instance):
    lburl = instance['ipaddress']
    response = urllib2.urlopen("http://" + lburl + "/rest")
    data = simplejson.load(response)

    self.gauge('coreapp.update.value', data["value"])

  2. custom_checkvalue.yaml ファイルを更新します (ipaddress をロードバランサーの IP アドレスに置き換えます)。

    conf.d/custom_checkvalue.yaml

    init_config:

instances:
  - ipaddress: 1.2.3.4

  3. Agent を再起動します。1 分以内に、ロードバランサーからメトリクスを送信する coreapp.update.value という新しいメトリクスがメトリクスサマリーに表示されます。

  4. このメトリクスのダッシュボードを作成します。

Agent のバージョン管理

次の try/except ブロックを使うと、カスタムチェックがどの Agent バージョンとも互換性を持つようになります。

try:
    # 最初に、古いバージョンの Agent から基本クラスのインポートを試みます
    from datadog_checks.base import AgentCheck
except ImportError:
    # 失敗した場合は、Agent バージョン 6 以降で実行します
    from checks import AgentCheck

# 特別な変数 __version__ の内容は Agent のステータスページに表示されます
__version__ = "1.0.0"

class HelloCheck(AgentCheck):
    def check(self, instance):
        self.gauge('hello.world', 1, tags=['TAG_KEY:TAG_VALUE'] + self.instance.get('tags', []))

その他の参考資料

お役に立つドキュメント、リンクや記事:

Datadog での開発ドキュメント more more