インテグレーションの定義ファイルの仕様

New Relic Infrastructure インテグレーション は、実行可能ファイル、定義ファイル、構成ファイルの3つのファイルで構成されています。ここでは、そのうちの定義ファイルを作成する方法について説明しています。

この機能を利用できるかは契約しているサブスクリプションレベルによります。

定義ファイルとは?

インテグレーション用の定義ファイルとは、サポートするプロトコルのバージョン、実行可能なコマンドのリスト、受け入れ可能な引数など、インテグレーションに関する情報を指定する YAML 形式のファイルです。

定義ファイルの構成は以下の通りです。

ヘッダー

定義ファイルのヘッダーの例です。

name: com.myorg.nginx​
protocol_version: 1
description: Collect metric and configuration data from NGINX
os: linux

上記で強調表示されている項目については、以下の表で説明します。

項目 説明
name 必須。name は、ログ出力、内部のメトリクスなどのインテグレーションを識別するために使われます。インテグレーション名は一意である必要があります。エージェントが構成ファイルを読み込むと、ここで指定した名前がエージェントのレジストリ内でインテグレーションを検索するために使われます。
protocol_version 必須。プロトコルのバージョン。インテグレーションとエージェント間の互換性を保証するために使われます。エージェントがインテグレーションのバージョンを理解できな場合は、そのインテグレーションを除外してログメッセージを作成します。
description 任意。インテグレーションが何をするのか分かりやすく説明する文書。
os 任意。インテグレーションを実行する OS。あなたが想定した OS のみでインテグレーションが実行されるようにするためのフィルタとして使われます。デフォルトは、OS に関係なくインテグレーションを実行します。当分の間、linux が唯一のサポートしている OS となります。

コマンド

ヘッダーの後には、コマンドをリストしたセクションを用意します。コマンドセクションは、実行可能ファイルとそれが実行されるのに必要な実行時のデータ用に1つ以上の独立した動作モードを定義します。コマンドセクションは、コマンドを定義した YAML マップです。各キーは、実行ファイルを指定するインテグレーション用の構成ファイル内にあるコマンドの固有のエイリアス名です。

以下はコマンドセクションの例です。

commands:
    metrics:
        command: 
         - myorg-nginx 
         - --metrics
        interval: 30
        prefix: integration/custom/nginx

上記で強調表示されている項目については、以下の表で説明します。

項目 説明
command 必須。コマンド部分を YAML 配列として表現した実行される実際のコマンドラインを指定します。組み立てられて、実際のコマンドとして実行されます。単純なコマンドの場合、配列は1つの要素しか持たないでしょう。その他のルールは以下のとおりです。

コマンドの規則
  • インテグレーションの構成対象の全インスタンスで共有されるコマンドとコマンドライン引数は、全てここに指定します
  • コマンドはコマンドラインとして扱われます。コマンドのベースネーム内でプラットフォーム固有のパス区切りが検出されない場合、プログラムは設定ファイルが見つかったディレクトリ(または、シンボリックリンクの場合、実際のディレクトリ)を実行のパスとして使用します。Infrastructure エージェントは、環境 PATH の定義を仮定していません。例:myorg-nginx は、ユーザーが ./myorg-nginx を指定したように Linux システムによって実行されます。
  • インテグレーションの初期作業ディレクトリは、設定ファイルと同じディレクトリに設定されます。
interval 任意。コマンドの実行間隔。単位は秒数。
メトリクスのポーリングのデフォルト間隔は30秒​​です。最小間隔は15秒です。
メトリクスをアラートでも使いたい場合は、30秒以下の間隔としてください。
prefix 任意。インベントリのカテゴリ(一般的な形式: category/integration_name)。デフォルトのカテゴリは、”integration”

定義ファイルの例

以下は、Linux システム用の2つのコマンドセクションを持つ定義ファイルの例です。

name: com.myorg.nginx
protocol_version: 1
description: Collect metric and configuration data from NGINX
os: linux
commands:
  metrics:
    command: 
      - myorg-nginx 
      - --metrics
    interval: 15
    prefix: integration/custom/nginx
  inventory:
    command: 
      - myorg-nginx 
      - --inventory
    interval: 120
    prefix: integration/custom/nginx

カスタムインテグレーションの完全な例については、インテグレーションの例をご覧ください。

ファイルの配置と有効化

インテグレーションファイルを配置して、有効にする方法については、インテグレーションを有効にするをご覧ください。