Agent インテグレーションの作成

概要

このページでは、Datadog Agent インテグレーションを作成する方法について、テクノロジーパートナーに説明します。このインテグレーションは、Integrations ページですぐに使えるものとして、または Marketplace ページで価格を付けて出品することができます。

Agent ベースのインテグレーション

Agent ベースのインテグレーションでは、Datadog Agent を使用して、開発者が書いたチェックを介してデータを送信します。チェックは、メトリクス、イベント、サービスチェックを顧客の Datadog アカウントに送信できます。Agent 自体も同様にログを送信することができますが、これはチェックの外側で構成されます。

これらのインテグレーションの実装コードは、Datadog がホスティングしています。Agent インテグレーションは、ローカルエリアネットワーク (LAN) や仮想プライベートクラウド (VPC) に存在するシステムまたはアプリケーションからデータを収集するのに最適な方法です。Agent インテグレーションの作成では、ソリューションを Python ホイール (.whl) として公開およびデプロイする必要があります。

Agent ベースのインテグレーションには、モニター、ダッシュボード、ログパイプラインなどのすぐに使えるアセットを含めることができます。ユーザーがインテグレーションタイルの Install をクリックすると、セットアップ手順に従うよう促され、すぐに使えるすべてのダッシュボードがアカウントに表示されます。ログパイプラインなどの他のアセットは、インテグレーションを適切にインストールおよび構成した後に、ユーザーに表示されます。

開発プロセス

Agent ベースのインテグレーションを構築するプロセスは、次のようになります。

1. Datadog パートナーネットワークに合格すると、Datadog テクノロジーパートナーチームと面談し、提供する製品やユースケースについて話し合います。
2. Datadog パートナーネットワークポータルから、開発用の Datadog サンドボックスアカウントをリクエストします。
3. インテグレーションの開発を開始します。これには、あなたの側でインテグレーションコードを書くことと、Python ホイール (.whl) を構築してインストールすることが含まれます。
4. Datadog サンドボックスアカウントでインテグレーションをテストします。
5. 開発作業をテストして完了したら、Integrations または Marketplace ページに表示されるインテグレーションタイルを構成するセットアップ手順、イメージ、サポート情報などの情報を提供し、タイルアセットを作成します。
6. プルリクエストが送信され、承認されると、Datadog テクノロジーパートナーチームは、インテグレーションを最終確認するためのデモをスケジュールします。
7. Datadog のサンドボックスアカウントでタイルとインテグレーションをテストしてから公開するか、すべての顧客向けにインテグレーションをすぐに公開するかのオプションがあります。

前提条件

必要な Datadog Agent インテグレーション開発ツールは以下の通りです。

• Python v3.9、pipx、Agent Integration Developer Tool (ddev)。インストール方法については、Datadog Agent Integration Developer Tool のインストールを参照してください。
• フルテストスイートを実行するための Docker。
• git コマンドラインまたは GitHub デスクトップクライアント。

mkdir $HOME/dd && cd $HOME/dd

インテグレーションを作成する

Docker をダウンロードし、適切なバージョンの Python をインストールし、開発環境を準備したら、Agent ベースのインテグレーションを作成し始めることができます。

以下の説明では、Awesome というインテグレーションを例にしています。Awesome のコードを使うか、Awesome を自分のコードに置き換えて、コマンドの中にインテグレーション名を入れてください。例えば、ddev create Awesome の代わりに ddev create <your-integration-name> を使用します。

インテグレーションのためのスキャフォールディングを作成する

ddev create コマンドは、Agent ベースのインテグレーションに必要な基本的なファイルとパスの構造 (またはスキャフォールディング) を作成するインタラクティブツールを実行します。

1. 最初のインテグレーションディレクトリを作る前に、ディスクに何も書き込まない -n/--dry-run フラグを使って、ドライランを試してみてください。

   ddev create -n Awesome
   

   このコマンドで、ファイルが書き込まれるパスと、パス構造自体が表示されます。出力の 1 行目のパスがリポジトリの場所と一致していることを確認します。

2. コマンドを -n フラグを付けずに実行します。このツールは、メールと名前の入力を求め、インテグレーションを始めるために必要なファイルを作成します。

   Datadog Marketplace 用のインテグレーションを作成する場合、ディレクトリが {パートナー名}_{インテグレーション名} のパターンに従っていることを確認してください。

   ddev create Awesome
   

Agent チェックを書く

Agent ベースの各インテグレーションの中核には、定期的に情報を収集し Datadog に送信する Agent Check があります。

チェックは、AgentCheck ベースクラスからロジックを継承し、以下の要件を備えています。

• Datadog Agent v7 以降で実行するインテグレーションは、Python 3 に対応している必要があります。Datadog Agent v5 と v6 で実行されるインテグレーションは、依然として Python 2.7 を使用しています。
• チェックは AgentCheck から派生している必要があります。
• チェックは、このシグネチャを持つメソッド check(self, instance) を提供しなければなりません。
• チェックは通常の Python パッケージの中で、datadog_checks ネームスペースの下にまとめられています。例えば、Awesome のコードは awesome/datadog_checks/awesome/ ディレクトリに格納されています。
• パッケージ名は、チェック名と同じでなければなりません。
• そのパッケージ内の Python モジュールの名称や、チ ェックを実装するクラスの名称には制限がありません。

チェックロジックの実装

Awesome の場合、Agent Check は、Web ページ上の文字列を検索する awesome.search という名前のサービスチェックで構成されています。文字列が存在する場合は OK、ページにはアクセスできるが文字列が見つからない場合は WARNING、ページにアクセスできない場合は CRITICAL という結果が得られます。

Agent Check でメトリクスを送信する方法については、カスタムAgent Check を参照してください。

awesome/datadog_checks/awesome/check.py のコードは次のようになります。

import requests

from datadog_checks.base import AgentCheck, ConfigurationError


class AwesomeCheck(AgentCheck):
    """AwesomeCheck は AgentCheck を継承し、必要なチェックメソッドを提供します。"""

    def check(self, instance):
        url = instance.get('url')
        search_string = instance.get('search_string')

        # 基本的なサニティチェックを行うことをお勧めします。
        # 例外についてはできるだけ具体的に記述してください。
        if not url or not search_string:
            raise ConfigurationError('Configuration error, please fix awesome.yaml')

        try:
            response = requests.get(url)
            response.raise_for_status()
        # 大きな間違いがある場合
        except Exception as e:
            # もう少し具体的なメッセージを用意してください...
            self.service_check('awesome.search', self.CRITICAL, message=str(e))
        # ページがアクセス可能な場合
        else:
            # search_string が見つかった場合
            if search_string in response.text:
                self.service_check('awesome.search', self.OK)
            # search_string が見つからなかった場合
            else:
                self.service_check('awesome.search', self.WARNING)

基本 Python クラスの詳細は、Python チェックの構造を参照してください。

検証テストを書く

テストには 2 種類あります。

• 特定の機能のユニットテスト
• check メソッドを実行し、適切なメトリクス収集を検証するインテグレーションテスト

pytest と hatch はテストを実行するために使用されます。インテグレーションを公開するためには、テストが必要です。

ユニットテストを書く

Awesome の check メソッドの前半では、2 つの要素をコンフィギュレーションファイルから取得して検証しています。これは、ユニットテストにかける候補として適切です。

awesome/tests/test_awesome.py ファイルを開き、内容を次に書き換えます。

import pytest

    # インテグレーションをインポートするのを忘れないでください

from datadog_checks.awesome import AwesomeCheck
from datadog_checks.base import ConfigurationError


@pytest.mark.unit
def test_config():
    instance = {}
    c = AwesomeCheck('awesome', {}, [instance])

    # 空のインスタンス
    with pytest.raises(ConfigurationError):
        c.check(instance)

    # URL のみ
    with pytest.raises(ConfigurationError):
        c.check({'url': 'http://foobar'})

    # 検索文字列のみ
    with pytest.raises(ConfigurationError):
        c.check({'search_string': 'foo'})

    # これは失敗しません
    c.check({'url': 'http://foobar', 'search_string': 'foo'})

pytest はマーカーをサポートし、これを使用してテストをカテゴリにグループ化できます。test_config が unit テストとしてマークされていることに注目してください。

スキャフォールディングは、awesome/tests にあるすべてのテストを実行するように設定されています。テストを実行するには、以下のコマンドを実行します。

ddev test awesome

インテグレーションテストを書く

上記のユニットテストでは、コレクションロジックはチェックされません。ロジックをテストするには、インテグレーションテストのための環境を作り、インテグレーションテストを書く必要があります。

インテグレーションテスト用の環境を作成する

このツールキットは docker を使って NGINX コンテナをスピンアップし、チェックにウェルカムページを取得させることができます。

インテグレーションテスト用の環境を作成するために、awesome/tests/docker-compose.yml に以下の内容で docker-compose ファイルを作成します。

version: "3"

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - "8000:80"

次に、awesome/tests/conftest.py ファイルを開き、内容を次に書き換えます。

import os

import pytest

from datadog_checks.dev import docker_run, get_docker_hostname, get_here

URL = 'http://{}:8000'.format(get_docker_hostname())
SEARCH_STRING = 'Thank you for using nginx.'
INSTANCE = {'url': URL, 'search_string': SEARCH_STRING}


@pytest.fixture(scope='session')
def dd_environment():
    compose_file = os.path.join(get_here(), 'docker-compose.yml')

    # これには 3 つの意味があります。
    #
    # 1. Compose ファイルで定義されたサービスをスピンアップします
    # 2. テストを実行する前に、URL が利用可能になるまで待ちます
    # 3. テスト終了後、サービスを撤収します
    with docker_run(compose_file, endpoints=[URL]):
        yield INSTANCE


@pytest.fixture
def instance():
    return INSTANCE.copy()

インテグレーションテストを追加する

インテグレーションテストのための環境を整えたら、awesome/tests/test_awesome.py ファイルにインテグレーションテストを追加します。

@pytest.mark.integration
@pytest.mark.usefixtures('dd_environment')
def test_service_check(aggregator, instance):
    c = AwesomeCheck('awesome', {}, [instance])

    # このチェックは OK を送信するはずです
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.OK)

    # このチェックは WARNING を送信するはずです
    instance['search_string'] = 'Apache'
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.WARNING)

開発をスピードアップするために、-m/--marker オプションを使って、インテグレーションテストのみを実行することができます。

ddev test -m integration awesome

インテグレーションはほぼ完了です。次に、必要なチェックアセットを追加します。

インテグレーションアセットを入力する

ddev スキャフォールディングによって作成された以下のアセットセットには、インテグレーションに関連する情報を入力する必要があります。

README.md

これには、Agent チェックのドキュメント、その設定方法、収集するデータ、サポート情報が含まれます。

spec.yaml

これは ddev ツールを使用して conf.yaml.example を生成するために使用されます。詳しくは、構成仕様を参照してください。

conf.yaml.example

これには、Agent チェックのデフォルト（または一例として）のコンフィギュレーションオプションが含まれます。このファイルを手動で編集しないでください。これは spec.yaml のコンテンツから生成されます。詳しくは、コンフィギュレーションファイルのリファレンスドキュメントを参照してください。

manifest.json

タイトルやカテゴリーなど、Agent チェックのメタデータが格納されています。詳しくは、マニフェストファイルリファレンスドキュメントを参照してください。

metadata.csv

これには、Agent チェックによって収集されたすべてのメトリクスのリストが含まれます。詳細については、メトリクスメタデータファイルのリファレンスドキュメントを参照してください。

service_check.json

Agent チェックによって収集されたすべてのサービスチェックのリストが含まれています。詳しくは、サービスチェックファイルリファレンスドキュメントを参照してください。

README.md と manifest.json ファイルの詳細については、タイルの作成とインテグレーションアセットリファレンスをご覧ください。

ホイールのビルド

pyproject.toml ファイルは、ホイールのパッケージ化とビルドに使用されるメタデータを提供します。ホイールはインテグレーションを機能させるために必要なファイルを含んでおり、これには Agent Check、構成例ファイル、ホイールビルド中に生成される成果物が含まれます。

メタデータファイルを含むすべての追加要素は、ホイールに含まれることを意図しておらず、Datadog プラットフォームとエコシステムによって他の場所で使用されます。

Python のパッケージングについてより詳しく知りたい場合は、Python プロジェクトのパッケージングを参照してください。

pyproject.toml の準備ができたら、以下のオプションのいずれかを使用してホイールを作成します。

• (推奨) ddev ツールを使用する: ddev release build <INTEGRATION_NAME>
• ddev ツールを使用しない: cd <INTEGRATION_DIR> && pip wheel . --no-deps --wheel-dir dist

ホイールのインストール

Wheel は、Agent v6.10.0 以降で提供されている Agent の integration コマンドを使ってインストールされます。このコマンドは、環境に応じて、特定のユーザーとして、または特定の権限で実行する必要があります。

Linux (dd-agent として)

sudo -u dd-agent datadog-agent integration install -w /path/to/wheel.whl

OSX (管理者として)

sudo datadog-agent integration install -w /path/to/wheel.whl

Windows PowerShell (シェルセッションが administrator 権限を持っていること)

& "C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe" integration install -w /path/to/wheel.whl

& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /path/to/wheel.whl

タイルを入力し、インテグレーションを公開する

Agent ベースのインテグレーションを作成したら、インテグレーションタイルに表示される残りの必須アセットを入力し、プルリクエストを開くための情報については、タイルの作成ドキュメントを参照してください。

その他の参考資料

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

タイルの作成DOCUMENTATION Agent ベースのインテグレーション開発のための PythonDOCUMENTATION Datadog プラットフォームで開発する方法についてDOCUMENTATION