インテグレーション用実行ファイルの仕様

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

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

実行可能ファイルとは

実行可能ファイルとは、New Relic に送信するデータを生成するファイルのことです。実行可能ファイルは、シェルスクリプト、スクリプト言語を使ったスクリプト、コンパイル済みのバイナリなど、コマンドラインインターフェイスから実行できるファイルを指します。実行可能ファイルは好きな言語で作成して構いません。唯一の要件は、このドキュメントの仕様を満たす JSON データをエクスポートできることです。(New Relic が推奨している言語は、Go です。Go は、New Relic 内において Infrastructure インテグレーションとインテグレーションのビルドツールの作成に使っています)

以下は、3種類のデータをすべて記録している実行可能ファイルにおける JSON 出力フォーマットの例です。

{
    "name":"com.myorg.nginx",
    "protocol_version":"1",
    "integration_version":"1.0.0",
    "metrics": [ 
        {
            "event_type":"LoadBalancerSample",
            "provider": "MyOrg:NGINX",
            "provider.connectionsActive": 54,  
            "provider.requestsPerSecond": 21,  
            "provider.reading": 23,
        }
    ],
    "inventory": {
        "events/worker_connections": {
            "value": 1024,
                },
        "http/gzip" : {
            "value": "on"
                }
    },
    "events": [
        {
            "summary":"More than 10 request errors logged in the last 5 minutes",
            "category": "notifications"
        }
    ],
}
上記の JSON は読みやすいように整形していますが、JSON ペイロードは1行である必要があります。

この JSON は2つの部分に分かれます。

一般的な仕様

以下は、JSON 出力する実行ファイルの一般的な仕様です。

一般的な出力と JSON フォーマット
データを JSON 形式で stdout(標準出力)に出力します。エージェントは stdout および stderr ファイルディスクリプタを行単位のバッファーとして扱います。
データ出力には、整形されたものではなく、標準の JSON 形式で出力してください。デバッグ目的で JSON を整形して出力するコマンドラインスイッチ(--pretty など)をオプションとしてを含めることを New Relic では推奨しています。
エラーとログ出力
ログ出力の唯一の要件は、エラーとデバッグ情報を stderr (標準エラー)に出力するということです。ログ出力の推奨事項とベストプラクティスについては、インテグレーション用のログ出力をご覧ください。
実行ファイルの終了
終了コードはステータスコード ゼロで終了することです。また、プラットフォーム固有の規則に従う必要もあります。たとえば、Linux の場合は、0 == EX_OK となります。
実行可能ファイルがゼロ以外の状態で終了した場合、エージェントは stdout からのデータをすべて破棄し、インテグレーション名、終了コード、収集可能な診断情報をログファイルに書き込みます。

ヘッダー

以下は、実行ファイルの JSON ヘッダー出力の例です。

"name":"com.myorg.nginx",
"protocol_version":"1",
"integration_version":"1.0.0",

上の JSON で強調表示されている項目の定義は以下の通りです。

ヘッダーの項目 説明
name 必須。構成ファイル名の name 項目と同じ値である必要があります。
protocol_version 必須。インテグレーション用の実行可能ファイルが使っているプロトコルのバージョン番号。
integration_version 任意。各ホスト上で実行されているインテグレーションのバージョンを追跡するためのインテグレーションのバージョン。注: インテグレーションに複数の実行可能ファイルがあることがあります。よって、これは単なる実行可能ファイルのバージョンではありません。

最小のペイロードは、ヘッダー項目のみを持つ JSON オブジェクトです。収集するデータがない場合は、stderr に書き込まれたプログラムのリターンコードとログメッセージを使用することをお勧めします。

データ

ヘッダーの後にデータを置きます。インテグレーションでは、以下の3種類の Infrastructure データを記録できます。

これらのデータタイプの詳細については、インテグレーション SDK の紹介をご覧ください。以下に、これらのデータタイプの仕様を示します。

メトリックデータ

Infrastructure のメトリックデータは、通常、単純な数値データをさします。例として、1秒あたりのキュー内の MySQL リクエスト数や、1分あたりの特定のシステムへのアクティブな接続の数などが挙げられます。関連するメタデータを除くと、メトリクスの構成要素は、メトリクス名と数値だけです。このデータは New Relic Insights で見つけることができます。

Infrastructure のメトリクスイベントは、両方とも、New Relic Insights の観点からは、イベントデータ・タイプとして分類されます。つまり、Infrastructure メトリクスと Infrastructure イベントの両方とも、Insight のイベントデータエクスプローラーから利用できるということです。メトリックデータエクスプローラーでは利用できません。

メトリクスデータの JSON 出力の例を以下に示します。 (これは ヘッダーの JSON の後に置かれます)。

[ 
    {
         "event_type":"LoadBalancerSample",
         "provider": "MyOrg:NGINX",
         "provider.connectionsActive": 54,  # metric data (a key/value pair)
         "provider.requestsPerSecond": 21,  # metric data (a key/value pair)
         "provider.reading": 23,   # metric data (a key/value pair)
    }
]

上の JSON で強調表示されているフィールドの定義は以下の通りです。

項目 説明
event_type

必須。event_type は、一般的なソフトウェアやインフラの抽象型を表します。この値は、以下で紹介する New Relic Infrastructure が現在サポートしているタイプから選択します。これらの値から、接続とユーザビリティーを的確に表しているものを選択します。

  • LoadBalancerSample (NGINX、Apache、HAProxy など)
  • BlockDeviceSample (NFS など)
  • DatastoreSample (MySQL、CouchDB、MongoDB、Cassandra など)
  • QueueSample (Kafka、RabbitMQ など)
  • ComputeSample (CPU、ディスク・スペースなどの VM やホストの情報)
  • PrivateNetworkSample
  • ServerlessSample
利用したいメトリクスデータが上記のカテゴリに該当しない場合は、support.newrelic.com まで連絡ください。

provider 必須。データを送信する組織とサービス名の両方を示す名前。例: MyOrg:NGINX。これらの要素は、New Relic UI で分析やフィルタリングを行う際に、データを簡単に識別するのに役立ちます。
Metric data

(少なくとも1つは) 必須。各メトリクスの測定値は、キーと値のペアで構成されています。Infrastructure 機能との最大限の互換性を保つため、エンティティタイプの仕様に準拠する必要があります。以下がその仕様です。

  • 属性名と値の前に provider. を使用することが推奨されています。そうすることにより、インテグレーション SDK によって生成されたデータを UI ですばやく確認できるようになります。
  • 値は文字列もしくは数値(整数または浮動小数点数)でなければなりません。文字列は関連メタデータとして使用できます。New Relic UI でデータをフィルタリングできます。真偽値は、文字列(”true”、 “false”)または整数(1、0)のいずれかで表現できます。値に配列やハッシュなどの複雑な型は指定できません
  • 命名フォーマットにはローワーキャメルケースを使います。例: queriesPerSecond
  • 以下の例のように、測定単位は、単位を接尾辞に指定することが推奨されています。
    • パーセント: Percent を使います。例: cpuUtilPercent
    • 率: PerSecond のような形式を利用します。秒は標準レートの測定値ですが、次のように他の単位を使用することもできます。PerMinutePerDay
    • バイト: Bytes や次のようなその他の絶対測定単位を利用します。Megabytes
  • 集約を表したい場合は、ドット表記を使用します。例:
    myMetricBytes.sum

イベントデータ

Infrastructure のイベントデータは、システム上の主要な活動に対する1回限りのメッセージを表します。サービスの起動や新規テーブルの作成が、イベントデータを作成する場合の活動の例として挙げられます。イベントデータは、Infrastructure にある Events ページやイベントフィード、そして、InfrastructureEvent イベントタイプを照会することで、Insights 上から見つけることができます。

以下は、インテグレーション用のイベントデータの JSON ペイロードの例です。(これは ヘッダーの JSON の後に置かれます)。

[
   {
      "summary":"More than 10 request errors logged in the last 5 minutes",
      "category": "notifications"
   }
]

上の JSON で強調表示されているフィールドの定義は以下の通りです。

項目 説明
summary 必須。送信するメッセージ。メッセージは単純な文字列でなければなりません。
category

任意。Infrastructure 製品で使用されている既存のカテゴリの1つ、もしくは新しいカテゴリ。文字列で指定します。デフォルト値は notifications です。以下はカテゴリの例です。

  • os
  • system
  • services
  • users
  • configuration
  • automation
  • notifications
  • metadata
  • applications
  • sessions
  • packages

インベントリデータ

Infrastructure 用のインベントリデータは、構成データ、インストールされたシステムのバージョン、その他のシステムのメタデータなどのライブ状態のシステム情報を収集します。インベントリデータは、Infrastructure の Inventory ページとイベントフィードに表示されます。Insights ではインベントリの変更に関連するデータも検索できます。

インベントリデータ型は、以下の条件を満たす1つ以上の JSON サブオブジェクトのハッシュです。

  • 固有のインベントリ ID キー(必須):インベントリ項目の識別子。このキーは、インテグレーションの接頭辞と組み合わせて、インベントリ項目のデータを示すパスを作成するのに利用されます。エンティティをまたいで結びつけて、差分があればそれを示すようなパスとなります。この ID はハッシュを指します。
  • キー/値のペアのハッシュ。インベントリ属性ごとに1つ。少なくとも1つは必須。
  • キーは文字列でなければなりません。
  • 値は、スカラー型(文字列または数値)もしくは、キー/値のハッシュオブジェクト。階層はサポートされていますが、最終の値ノードは上記のようにスカラーでなければなりません。

以下は、インベントデータの JSON ペイロードの例です。(これは ヘッダーの JSON の後に置かれます)。

{
    "events/worker_connections": {
        "value": 1024,
                },
    "http/gzip" : {
        "value": "on"
                }
}

実行可能ファイルを含むカスタムインテグレーションの例については、インテグレーションの例をご覧ください。

ファイルの配置と有効化

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