インテグレーションアセットリファレンス

インテグレーションアセットリファレンス

構成ファイル

新しいインテグレーションを用意する際は、必要なオプションと適正なデフォルトを設定したコンフィギュレーションサンプルを追加する必要があります。この例のサンプルコンフィギュレーションファイルは <チェック名>/datadog_checks/<チェック名>/data/conf.yaml.example にあり、init_configinstances という 2 つのトップレベル要素を持っています。init_config 下のコンフィギュレーションはインテグレーションにグローバルに適用され、インテグレーションのすべてのインスタンスで使用されます。一方、instances 内のコンフィギュレーションは特定のインスタンスに適用されます。

どちらのセクションの構成ブロックも次の形式になります。

## @<COMMAND> [- <ARGS>]
## <DESCRIPTION LINE 1>
## <DESCRIPTION LINE 2>
#
<KEY>: <VALUE>

構成ブロックは以下のガイドラインに従います。

  • 説明を空にすることはできません。
  • ドキュメント寄稿ガイドラインに準拠して、プレースホルダーは常に <これはプレースホルダーです> の形式に従う必要があります。
  • すべての必須パラメーターはデフォルトでコメントにされません
  • すべてのオプションパラメーターはデフォルトでコメントにされます。
  • プレースホルダーにインテグレーションのデフォルト値がある場合 (たとえば、インテグレーションのステータスエンドポイント)、それを汎用プレースホルダーの代わりに使用できます。

@param の指定

事実上 @param が唯一のコマンドです。@param は、主に文書化の目的で構成ブロックについて説明するために使用され、以下のいずれかの形式を使用して実装されます。

@param <name> - <type> - 必須
@param <name> - <type> - オプション
@param <name> - <type> - オプション - デフォルト: <defval>

引数

  • name: パラメーターの名前。例: search_string (必須)。
  • type: パラメーター値のデータタイプ (必須)。使用可能な値:
    • boolean
    • string
    • integer
    • double
    • float
    • dictionary
    • list*
    • object
  • defval: パラメーターのデフォルト値。空でもかまいません (オプション)。

list および object 変数は複数行にまたがり、特別な規則があります。

  • list の個々の要素は、@param 指定を使用して文書化されません。
  • object の場合は、@param 指定を使用して要素を個別に文書化することも、オブジェクト自体の指定に続けてトップレベルに共通の説明を付けることもできます。

オプションパラメーター

オプションパラメーターはデフォルトでコメントにする必要があります。パラメーターの記述に使用される各行の前に、@param 指定と同じインデントで # を追加します。

ブロックコメント

次の規則に従って、構成ファイルの任意の場所にブロックコメントを追加できます。

  • コメントは ## で開始されます。
  • コメントは変数と同様にインデントされます (ハイフンはカウントされません)。

YAML 構文の詳細については、Wikipedia を参照してください。Online YAML Parser も活用してください。

マニフェストファイル

各インテグレーションには manifest.json ファイルが含まれています。これには、オペレーティングパラメーター、さらに大きな Datadog インテグレーションエコシステム内の配置などが記述されます。

以下に、manifest.json ファイルの必須属性とオプション属性をすべてリストします。

属性 タイプ 必須/オプション 説明
integration_id 文字列 必須 このインテグレーションを一意に識別する名前。通常は表示名のケバブケース。
categories 文字列の配列 必須 公開ドキュメントのインテグレーションページで使用されるインテグレーションカテゴリ。
creates_events Boolean 必須 インテグレーションがイベントを作成できるかどうか。これが false に設定された場合は、インテグレーションからイベントを作成しようとするとエラーになります。
display_name 文字列 必須 公開ドキュメントのインテグレーションページと Datadog アプリケーションの対応するインテグレーションタイルに表示されるタイトル。
guid 文字列 必須 インテグレーションの一意の ID。UUID を生成します
is_public Boolean 必須 false に設定されると、インテグレーションの README.md コンテンツは Datadog 公開ドキュメントのインデックスにボットによって掲載されません。
maintainer 文字列 必須 インテグレーションの所有者の電子メール。
manifest_version 文字列 必須 現在のマニフェストのバージョン。
name 文字列 必須 インテグレーションの一意の名前。このパラメーターにはフォルダー名を使用します。
public_title 文字列 必須 ドキュメントに表示されるインテグレーションのタイトル。<INTEGRATION_NAME> の形式に従う必要があります。
short_description 文字列 必須 このテキストは、インテグレーションページで、インテグレーションタイルの先頭およびインテグレーションのロールオーバーテキストに表示されます。最大 80 文字。
support 文字列 必須 インテグレーションの所有者。
supported_os 文字列の配列 必須 サポートされている OS のリスト。linuxmac_oswindows から選択します。
type 文字列 必須 インテグレーションの種類。check に設定する必要があります。
aliases 文字列の配列 オプション Datadog ドキュメントの URL エイリアスのリスト。
description 文字列 オプション このテキストは、インテグレーションドキュメントのリンクを共有したときに表示されます。
is_beta Boolean オプション デフォルトは false です。true に設定されると、インテグレーションの README.md コンテンツは Datadog 公開ドキュメントに表示されません。
metric_to_check 文字列 オプション このメトリクスが存在するかどうかで、このインテグレーションが正しく動作しているかどうかが判定されます。インテグレーションがインストールされているのに、このメトリクスが報告されていない場合、このインテグレーションは Datadog アプリケーションで破損しているとマークされます。
metric_prefix 文字列 オプション このインテグレーションのメトリクスのネームスペース。このインテグレーションによって報告されるすべてのメトリクスの先頭にこの値が付加されます。
process_signatures 文字列の配列 オプション このインテグレーションのコマンドラインに一致するシグニチャのリスト。
assets 辞書 必須 アセットファイルが存在する相対的場所とそれぞれの名前。
assets-> dashboards 辞書 必須 (すべてのインテグレーションでグローバルに一意の) ダッシュボードの名前をキーとし、ダッシュボード定義がある場所の相対ファイルパスを値とする辞書。
assets-> monitors 辞書 必須 (すべてのインテグレーションでグローバルに一意の) モニターの名前をキーとし、ダッシュボード定義がある場所の相対ファイルパスを値とする辞書。
assets-> service_checks 文字列 必須 service_checks.json ファイルが存在する相対的な場所。

メトリクスメタデータファイル

metadata.csv ファイルには、インテグレーションが収集できるすべてのメトリクスが記述されます。

metadata.csv ファイルの各列について以下に説明します。

列名 必須/オプション 説明
metric_name 必須 メトリクスの名前。
metric_type 必須 メトリクスのタイプ
interval オプション メトリクスの収集間隔 (秒単位)。
unit_name オプション メトリクスの単位。サポートされているすべての単位のリスト
per_unit_name オプション 単位の下位区分がある場合。request per second (1 秒あたりのリクエスト) など。
description オプション メトリクスの説明。
orientation 必須 myapp.turnover のように、大きい方がよいメトリクスの場合は 1 に設定します。メトリクスの変動が特に重要でない場合は 0 に設定します。myapp.latency のように、小さい方がよいメトリクスの場合は -1 に設定します。
integration 必須 メトリクスを送信するインテグレーションの名前。これは、manifest.json ファイルにある display_name を正規化した文字列です。文字、アンダースコア、ダッシュ、数字以外の文字はアンダースコアに変換されます。例: Openstack Controller -> openstack_controllerASP.NET -> asp_netCRI-o -> cri-o
short_name 必須 メトリクスの明示的な一意の ID。

サービスチェックファイル

service_check.json ファイルは、インテグレーションによって作成されたサービスチェックを記述します。

service_checks.json ファイルには、次の必須属性が含まれています。

属性 説明
agent_version サポートされている Agent の最小バージョン。
integration このサービスチェックを送信するインテグレーションの名前。これは、manifest.json にある正規化されていない display_name です。
check サービスチェックの名前。一意である必要があります。
statuses チェックのさまざまなステータスのリスト。okwarningcritical から選択します。unknown も可能です。
groups サービスチェックと共に送信されるタグ
name サービスチェックの表示名。表示名はわかりやすく、すべてのインテグレーションで一意である必要があります。
description サービスチェックの説明。