インフラストラクチャモニタリング用の Integrations SDK を使用して、カスタム オンホスト統合 を構築する場合、統合は、実行ファイルと少なくとも 1 つの設定ファイルの少なくとも 3 つのファイルで構成されます。実行ファイルは、インフラストラクチャ監視エージェントが消費し、New Relic に送信する JSON データを生成します。この JSON オブジェクトを SDK 統合プロトコルと呼びます。
実行ファイルの要件
実行ファイルは、コマンドライン・インターフェースから実行できるファイルであれば何でも構いません。
- シェルスクリプト
- スクリプティング言語のスクリプト
- コンパイル済みバイナリ
実行ファイルの唯一の要件は、このドキュメントの の仕様 を満たす JSON データを一行形式でエクスポートすることです。
推奨: 統合機能の作成にはGoを使用してください。Goは、オンホスト統合機能や 統合機能構築ツール の作成に使用する言語です。しかし、どの言語でもインテグレーションを作成することができます。
ファイルの配置
実行ファイルはこのディレクトリに入ります。
Linuxです。
/var/db/newrelic-infra/custom-integrationsWindows:
C:\Program Files\New Relic\newrelic-infra\newrelic-integrations
Integration protocol v4: JSON出力例
ここでは、新しいJSONスキーマ(統合プロトコルv4)について説明します。SDK v4は、この新しいバージョンのプロトコルのみをサポートしています。これらは最も重要な変更点です。
- 新しい
統合
オブジェクトをトップレベルで提供します。 エンティティ
とメトリクス
のオブジェクトが変更されました。
詳しくは、 v3からv4への移行ガイド をご覧ください。
{ "protocol_version":"4", # protocol version number "integration":{ # this data will be added to all metrics and events as attributes, # and also sent as inventory "name":"integration name", "version":"integration version" }, "data":[ # List of objects containing entities, metrics, events and inventory { "entity":{ # this object is optional. If it's not provided, then the Entity will get # the same entity ID as the agent that executes the integration. "name":"redis:192.168.100.200:1234", # unique entity name per customer account "type":"RedisInstance", # entity's category "displayName":"my redis instance", # human readable name "metadata":{} # can hold general metadata or tags. Both are key-value pairs that will # be also added as attributes to all metrics and events }, "metrics":[ # list of metrics using the dimensional metric format { "name":"redis.metric1", "type":"count", # gauge, count, summary, cumulative-count, rate or cumulative-rate "value":93, "attributes":{} # set of key-value pairs that define the dimensions of the metric } ], "inventory":{...}, # Inventory remains the same "events":[...] # Events remain the same } ]}
Integration protocol v3: JSON出力例
このJSONには
- 基本的な統合データ(名前、バージョン)を含むヘッダー
- データリスト(1つまたは複数の エンティティを含む) データ(メトリック、インベントリ、および/またはイベントデータ)を報告する。
この図はその構造を表しています。
以下は、JSON出力の例です(読みやすさのために改行を入れて整形しています)。定義と仕様はこの例に従います。
{ "name": "my.company.integration", "protocol_version": "3", "integration_version": "x.y.z", "data": [ { "entity": { "name": "my_garage", "type": "building", "id_attributes": [ { "key": "environment", "value": "production" }, { "key": "node", "value": "master" } ] }, "metrics": [ { "temperature": 25.3, "humidity": 0.45, "displayName": "my_garage", "entityName": "building:my_garage", "event_type": "BuildingStatus" } ], "inventory": { "out_door": { "status": "open" } }, "events": [] }, { "entity": { "name": "my_family_car", "type": "car", "id_attributes": [ { "key": "environment", "value": "production" }, { "key": "node", "value": "master" } ] }, "metrics": [ { "speed": 95, "fuel": 768, "displayName": "my_family_car", "entityName": "car:my_family_car", "event_type": "VehicleStatus" } ], "inventory": { "motor": { "brand": "renault", "cc": 1800 } }, "events": [ { "category": "gear", "summary": "gear has been changed" } ], "add_hostname": true } ]}
JSON: 一般仕様
ここでは、JSON出力の一般的な仕様について説明します。
JSON: ヘッダ
以下は、オン・ホスト・インテグレーションの JSON 出力の最初の部分の例です:
"name":"com.myorg.nginx",
"protocol_version":"3",
"integration_version":"1.0.0",
"data": [ {entities}...]
最小のペイロードは、ヘッダーフィールドのみのJSONオブジェクトとなります。 推奨: 収集するデータがない場合は、プログラムのリターンコードと、 stderrに書き込まれたログメッセージを使用します。
.
JSONヘッダーフィールド | 説明 |
---|---|
| 必要です。設定ファイルの「 推奨: リバースドメイン名を使用して、ユニークな統合名を生成します。 |
| 必須項目です。統合実行ファイルが使用している、統合とエージェントの間の交換プロトコルのバージョン番号です。
|
| オプションです。統合バージョン。各ホストで実行されている統合バージョンを追跡するために使用します。 統合体は複数の実行ファイルを持つことができます。そのため、これは単に実行ファイルのバージョンを示すものではありません。 |
| データの報告に必要。1つまたは複数のエンティティから報告された データを含むリスト 。 |
JSON: エンティティ
データ
リスト JSON 出力 の内部には、1つまたは複数のエンティティがあります。エンティティの入力フィールドには
エンティティのJSONフィールド | 説明 |
---|---|
| 必須。エンティティのデータまたはプロパティ。 |
| オプションです。エンティティ関連メトリックのリスト。 |
| オプションです。エンティティ関連のインベントリ項目。 |
| オプションです。エンティティ関連イベントのリスト。 |
| オプションです。ブール値です。 |
データ
リスト JSON 出力 の内部には、1つまたは複数のエンティティとそのデータがあります。 エンティティ
エントリーには2つのフィールドがあります。
エンティティデータのJSONフィールド | 説明 |
---|---|
| 必須項目です。エンティティの識別子/名称です。 推奨: リバースドメイン名を使用して、ユニークな統合名を生成します。 |
| 必須。エンティティの種類です。これは、インフラストラクチャエージェントによって、 一意の識別子 を |
| 任意です。エンティティに一意性を与えるkey-value属性のリストです。これらは、 Identifier属性は、エンティティ名が一意の識別子として機能するのに十分でない場合や、意味のある情報を十分に提供できない場合に有効です。例えば
|
エンティティ名のループバックアドレス置換
インフラストラクチャーエージェント バージョン1.2.25以上 プロトコルv3では、エージェントレベルのエンティティ名にローカルアドレスの置き換えを追加することで、リモートエンティティの一意性を向上させています。
複数のリモートエンティティがエンドポイントに基づいた名前を持っており( ip
または hostname
)、この名前に ループバックアドレス が含まれている場合、2つの問題があります。
- このlocalhostの値は、より詳しい情報がないと価値のある情報を提供しません。
の名前
は、ローカルアドレスで命名されている他のサービスと衝突する可能性があります。
これは次のような場合に起こります。
- エンドポイントの名前は
localhost:port
のようになります。 - ポートは特定のサービスでは同じになる傾向があります。例えば、Mysqlでは3306です。
プロトコルv3の受信データでは、インフラストラクチャーエージェントは、エンティティ名(およびキー)のループバックアドレスを、以下のリストの最初の利用可能な項目に置き換えます。
- クラウドプロバイダーのインスタンスID(該当する場合はエージェントが取得
- 表示名。 display_name エージェント設定オプションで設定します。
- エージェントが取得したホスト名
例えば、プロトコル v3 を使用する統合が localhost:3306
という名前のエンティティを返し、エージェントがベアメタルで実行されていて(クラウドプロバイダーのインスタンス ID を持っていない)、display_name が設定されておらず、ホスト名が prod-mysql-01
であった場合、エージェントは localhost
を置き換えて、 prod-mysql-01:3306
というエンティティ名を生成します。
インフラストラクチャエージェントは、v3統合プロトコルに対してループバックアドレスの置き換えを自動的に有効にします。また、 エージェント設定フラグ replace_v2_loopback_entity_names
を通じて、v2に対しても有効にすることができます。この場合、v2 を使用するエージェントによって実行されるすべての統合は、ローカルアドレスを運ぶたびにその名前が置き換えられます。
JSON: メトリクス、インベントリ、およびイベントデータ
データの値は、実行ファイルのヘッダーに従います。記録できるデータタイプは3種類 。
重要
New Relic ダッシュボードの観点からは、インフラストラクチャのメトリクスとイベントは、どちらも イベントデータ に分類されます。