New Relic インフラストラクチャ エージェントのオンホスト統合は、 実行可能ファイルと少なくとも 1 つの構成ファイルの少なくとも 2 つのファイルで構成されます。実行可能ファイルは、インフラストラクチャ監視エージェントによって消費され、New Relic に送信される JSON データを生成します。JSON オブジェクトを SDK 統合プロトコルと呼びます。
実行ファイルの要件
実行ファイルは、コマンドライン・インターフェースから実行できるファイルであれば何でも構いません。
- シェルスクリプト
- スクリプティング言語のスクリプト
- コンパイル済みバイナリ
実行ファイルの唯一の要件は、このドキュメントの の仕様 を満たす JSON データを一行形式でエクスポートすることです。
推奨： 統合機能の作成にはGoを使用してください。Goは、オンホスト統合機能や 統合機能構築ツール の作成に使用する言語です。しかし、どの言語でもインテグレーションを作成することができます。
ファイルの配置
実行ファイルはこのディレクトリに入ります。
Linux：
/var/db/newrelic-infra/custom-integrationsウィンドウズ：
C:\Program Files\New Relic\newrelic-infra\newrelic-integrations
Integration protocol v4: JSON出力例
ここでは、新しいJSONスキーマ（統合プロトコルv4）について説明します。SDK v4は、この新しいバージョンのプロトコルのみをサポートしています。これらは最も重要な変更点です。
- 最上位の新しい
integrationオブジェクト。 entityおよびmetricsオブジェクトが変更されました。
詳しくは、 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 出力のdataリスト内には、1 つ以上のエンティティがあります。エンティティ入力フィールドには次のものがあります。
エンティティのJSONフィールド | 説明 |
|---|---|
| 必須。エンティティのデータまたはプロパティ。 |
| オプションです。エンティティ関連メトリックのリスト。 |
| オプションです。エンティティ関連のインベントリ項目。 |
| オプションです。エンティティ関連イベントのリスト。 |
| オプション。ブール。 |
JSON 出力のdataリスト内には、1 つ以上のエンティティとそのデータが含まれています。entityエントリには次の 2 つのフィールドがあります。
エンティティデータのJSONフィールド | 説明 |
|---|---|
| 必須項目です。エンティティの識別子/名称です。 推奨： リバースドメイン名を使用して、ユニークな統合名を生成します。 |
| 必要。エンティティの種類。これは、インフラストラクチャ エージェントによって、 |
| オプション。エンティティに一意性を提供するキー値属性のリスト。これらは、読みやすくし、追加情報を提供し、エンティティ名の一意性を向上させるために、 Identifier属性は、エンティティ名が一意の識別子として機能するのに十分でない場合や、意味のある情報を十分に提供できない場合に有効です。例えば |
エンティティ名のループバックアドレス置換
インフラストラクチャ エージェント バージョン 1.2.25 以降では、プロトコル v3 はエージェント レベルでエンティティ名にローカル アドレス置換を追加することにより、リモート エンティティの一意性を向上させます。
複数のリモート エンティティがエンドポイント ( ipまたはhostnameのいずれか) に基づく名前を持ち、この名前にループバック アドレスが含まれている場合、2 つの問題があります。
- このlocalhostの値は、より詳しい情報がないと価値のある情報を提供しません。
nameは、ローカル アドレスで名前が付けられている他のサービスと衝突する可能性があります。
これは次のような場合に起こります。
- エンドポイント名は
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 ダッシュボードの観点からは、インフラストラクチャのメトリクスとイベントは、どちらも イベントデータ に分類されます。