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

概要

このページでは、基本的な「Hello world!」カスタム Agent チェックを構築する手順を説明します。また、チェックの最小収集間隔を変更する方法も示します。

セットアップ

インストール

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

最新バージョンの Agent と互換性を保つには、カスタム Agent チェックが Python 3 互換である必要があります。

構成

  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_ でチェックにプレフィックスを付けて、既存の Datadog Agent インテグレーションの名前との競合を避けることをお勧めします。例えば、カスタム Postfix チェックの場合、チェックファイルの名前は custom_postfix.py と custom_postfix.yaml ではなく postfix.py と postfix.yamlにします。
    • 構成ファイルとチェックファイルの名前は一致している必要があります。チェックの名前が 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 を再起動し、新たに hello.world という名前のメトリクスがメトリクスの概要に表示されるまで待ちます。

カスタムチェックの動作に問題がある場合は、ファイルの権限を確認してください。チェックファイルは Agent ユーザーが読み取り、実行できる必要があります。その他のトラブルシューティング手順については、Agent チェックのトラブルシューティングを参照してください。

収集間隔の更新

チェックの収集間隔を変更するには、custom_checkvalue.yamlファイル内で min_collection_interval 設定を使用し、秒単位で指定します。デフォルト値は 15 秒です。min_collection_interval はインスタンスレベルで追加する必要があります。カスタムチェックが複数のインスタンスをモニターするように設定されている場合、インスタンスごとに間隔を個別に構成する必要があります。

min_collection_interval を 30 に設定しても、必ずしもメトリクスが 30 秒ごとに収集されることは保証されません。Agent のコレクターは 30 秒ごとにチェックを実行しようとしますが、同一の Agent 上で有効なインテグレーションおよびチェックの数によっては、チェックが他のインテグレーションやチェックの後ろでキューに入る可能性があります。もし check メソッドが完了するのに 30 秒以上かかる場合、Agent はまだチェックが実行中であることを検知し、次の間隔までその実行をスキップします。

収集間隔を設定

単一のインスタンスの場合、収集間隔を 30 秒に設定するには以下の構成を使用します。

conf.d/custom_checkvalue.yaml

init_config:

instances:
  - min_collection_interval: 30

以下の例は、my_service という名前のサービスを 2 つの異なるサーバーでモニターする想定のカスタムチェックで、間隔を変更する方法を示しています。

init_config:

instances:
  - host: "http://localhost/"
    service: my_service
    min_collection_interval: 30

  - host: "http://my_server/"
    service: my_service
    min_collection_interval: 30

チェックの検証

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

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

チェックが動作していることを確認した後、Agent を再起動してチェックを含め、データの報告を開始してください。

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

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

Python インタプリタはマルチスレッドの Go ランタイムに埋め込まれているため、Python 標準ライブラリの subprocess や multithreading モジュールの使用はサポートされていません。サブプロセス内でコマンドを実行する場合は、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)

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

もしサブプロセスの出力に対して文字列処理を行わなかったり、整数または浮動小数点数に変換しなかったりした場合、チェックはエラーを出さずに実行されますが、メトリクスやイベントを報告しません。また、Agent ユーザーがコマンドが参照するファイルやディレクトリへの正しい権限を持っていない場合、または 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() returns an int by default
        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:
    # first, try to import the base class from new versions of the Agent
    from datadog_checks.base import AgentCheck
except ImportError:
    # if the above failed, the check is running in Agent version < 6.6.0
    from checks import AgentCheck

# content of the special variable __version__ will be shown in the Agent status page
__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