- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
このページでは、Datadog Agent インテグレーションを作成する方法について、テクノロジーパートナーに説明します。このインテグレーションは、Integrations ページですぐに使えるものとして、または Marketplace ページで価格を付けて出品することができます。
Agent ベースのインテグレーションでは、Datadog Agent を使用して、開発者が書いたチェックを介してデータを送信します。チェックは、メトリクス、イベント、サービスチェックを顧客の Datadog アカウントに送信できます。Agent 自体も同様にログを送信することができますが、これはチェックの外側で構成されます。
これらのインテグレーションの実装コードは、Datadog がホスティングしています。Agent インテグレーションは、ローカルエリアネットワーク (LAN) や仮想プライベートクラウド (VPC) に存在するシステムまたはアプリケーションからデータを収集するのに最適な方法です。Agent インテグレーションの作成では、ソリューションを Python ホイール (.whl
) として公開およびデプロイする必要があります。
Agent ベースのインテグレーションには、モニター、ダッシュボード、ログパイプラインなどのすぐに使えるアセットを含めることができます。ユーザーがインテグレーションタイルの Install をクリックすると、セットアップ手順に従うよう促され、すぐに使えるすべてのダッシュボードがアカウントに表示されます。ログパイプラインなどの他のアセットは、インテグレーションを適切にインストールおよび構成した後に、ユーザーに表示されます。
Agent ベースのインテグレーションを構築するプロセスは、次のようになります。
.whl
) を構築してインストールすることが含まれます。必要な Datadog Agent インテグレーション開発ツールは以下の通りです。
ddev
)。インストール方法については、Datadog Agent Integration Developer Tool のインストールを参照してください。すぐに使えるインテグレーションを構築するには
dd
ディレクトリを作成します。
mkdir $HOME/dd && cd $HOME/dd
Datadog Development Toolkit は、$HOME/dd/
ディレクトリで作業することを想定しています。これは必須ではありませんが、異なるディレクトリで作業する場合は、追加の構成手順が必要です。
integrations-extras
リポジトリをフォークします。
フォークを dd
ディレクトリに複製します。
git clone git@github.com:<YOUR USERNAME>/integrations-extras.git
作業するフィーチャーブランチを作成します。
git switch -c <YOUR INTEGRATION NAME> origin/master
Agent Integration Developer Tool を使用すると、インテグレーションを開発する際に、インテグレーションタイルのアセットとメタデータのスケルトンを生成して、スキャフォールディングを作成することができます。ツールのインストール方法については、Datadog Agent Integration Developer Tool をインストールするを参照してください。
integrations-extras
リポジトリに対応したツールを構成するには
オプションとして、integrations-extras
リポジトリが $HOME/dd/
以外の場所にある場合は、ddev
構成ファイルを調整します。
ddev config set extras "/path/to/integrations-extras"
デフォルトの作業用リポジトリとして integrations-extras
を設定します。
ddev config set repo extras
インテグレーションを構築するには
Marketplace リポジトリへのアクセスリクエストは、Marketplace 製品の構築を参照してください。
dd
ディレクトリを作成します。
mkdir $HOME/dd```
Datadog Development Toolkit コマンドは、`$HOME/dd/` ディレクトリで作業していることを想定しています。これは必須ではありませんが、異なるディレクトリで作業する場合は、追加の構成手順が必要です。
マーケットプレイスのリポジトリへのアクセスが許可されたら、dd
ディレクトリを作成し、marketplace
リポジトリを複製します。
git clone git@github.com:DataDog/marketplace.git```
作業するフィーチャーブランチを作成します。
git switch -c <YOUR INTEGRATION NAME> origin/master```
Agent Integration Developer Tool を使用すると、インテグレーションを開発する際に、インテグレーションタイルのアセットとメタデータのスケルトンを生成して、スキャフォールディングを作成することができます。ツールのインストール方法については、Datadog Agent Integration Developer Tool をインストールするを参照してください。
Agent Integration Developer Tool をインストールしたら、Marketplace のリポジトリ用に構成します。
デフォルトの作業用リポジトリとして marketplace
を設定します。
ddev config set marketplace $HOME/dd/marketplace
ddev config set repo marketplace
marketplace
ディレクトリの複製に $HOME/dd
以外のディレクトリを使用した場合は、以下のコマンドを使用して作業リポジトリを設定します。
ddev config set marketplace <PATH/TO/MARKETPLACE>
ddev config set repo marketplace
Docker をダウンロードし、適切なバージョンの Python をインストールし、開発環境を準備したら、Agent ベースのインテグレーションを作成し始めることができます。
以下の説明では、Awesome
というインテグレーションを例にしています。Awesome のコードを使うか、Awesome を自分のコードに置き換えて、コマンドの中にインテグレーション名を入れてください。例えば、ddev create Awesome
の代わりに ddev create <your-integration-name>
を使用します。
ddev create
コマンドは、Agent ベースのインテグレーションに必要な基本的なファイルとパスの構造 (またはスキャフォールディング) を作成するインタラクティブツールを実行します。
最初のインテグレーションディレクトリを作る前に、ディスクに何も書き込まない -n/--dry-run
フラグを使って、ドライランを試してみてください。
ddev create -n Awesome
このコマンドで、ファイルが書き込まれるパスと、パス構造自体が表示されます。出力の 1 行目のパスがリポジトリの場所と一致していることを確認します。
コマンドを -n
フラグを付けずに実行します。このツールは、メールと名前の入力を求め、インテグレーションを始めるために必要なファイルを作成します。
ddev create Awesome
Agent ベースの各インテグレーションの中核には、定期的に情報を収集し Datadog に送信する Agent Check があります。
チェックは、AgentCheck
ベースクラスからロジックを継承し、以下の要件を備えています。
AgentCheck
から派生している必要があります。check(self, instance)
を提供しなければなりません。datadog_checks
ネームスペースの下にまとめられています。例えば、Awesome のコードは awesome/datadog_checks/awesome/
ディレクトリに格納されています。Awesome の場合、Agent Check は、Web ページ上の文字列を検索する awesome.search
という名前のサービスチェックで構成されています。文字列が存在する場合は OK
、ページにはアクセスできるが文字列が見つからない場合は WARNING
、ページにアクセスできない場合は CRITICAL
という結果が得られます。
Agent Check でメトリクスを送信する方法については、カスタムAgent Check を参照してください。
awesome/datadog_checks/awesome/check.py
のコードは次のようになります。
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 種類あります。
pytest と hatch はテストを実行するために使用されます。インテグレーションを公開するためには、テストが必要です。
Awesome の check
メソッドの前半では、2 つの要素をコンフィギュレーションファイルから取得して検証しています。これは、ユニットテストにかける候補として適切です。
awesome/tests/test_awesome.py
ファイルを開き、内容を次に書き換えます。
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 ファイルを作成します。
docker-compose.yml
version: "3"
services:
nginx:
image: nginx:stable-alpine
ports:
- "8000:80"
次に、awesome/tests/conftest.py
ファイルを開き、内容を次に書き換えます。
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
ファイルにインテグレーションテストを追加します。
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
spec.yaml
ddev
ツールを使用して conf.yaml.example
を生成するために使用されます。詳しくは、構成仕様を参照してください。conf.yaml.example
spec.yaml
のコンテンツから生成されます。詳しくは、コンフィギュレーションファイルのリファレンスドキュメントを参照してください。manifest.json
metadata.csv
service_check.json
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 権限を持っていること)
v6.11
以前& "C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe" integration install -w /path/to/wheel.whl
v6.12
以降& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /path/to/wheel.whl
Agent ベースのインテグレーションを作成したら、インテグレーションタイルに表示される残りの必須アセットを入力し、プルリクエストを開くための情報については、タイルの作成ドキュメントを参照してください。