EPAgent プラグイン RESTful インターフェースの有効化

アプリケーションまたは環境から収集されるメトリックを送信するように EPAgent プラグイン HTTP RESTful インターフェースを設定することができます。HTTP RESTful インターフェースは、既存の EPAgent プラグイン メトリック収集ソリューションとともに使用することができます。ソリューションには、ステートフルとステートレス プラグイン、およびネットワーク ソケット リスナが含まれます。ソリューションには、GET とクエリ パラメータを使用する HTTP メソッドも含まれます。
apmsaas
スタンドアロン EPAgent はダウンロードできなくなりました。また、この機能は、DX APM SaaS および DX APM オンプレミス(20.x 以降)で APM インフラストラクチャ エージェントの EPAgent 拡張機能を使用してサポートされるようになりました。実装の詳細は、こちらを参照してください。ただし、既存のユーザは、ここで説明する手順を使用して、レガシー スタンドアロン EPAgent を DX APM SaaS または DX APM オンプレミス(20.x 以降)に接続できます。詳細については、「スタンドアロン EPAgent のインストールおよび設定」と「クラウド プロキシ」を参照してください。
アプリケーションまたは環境から収集されるメトリックを送信するように EPAgent プラグイン HTTP RESTful インターフェースを設定することができます。HTTP RESTful インターフェースは、既存の EPAgent プラグイン メトリック収集ソリューションとともに使用することができます。ソリューションには、ステートフルとステートレス プラグイン、およびネットワーク ソケット リスナが含まれます。ソリューションには、GET とクエリ パラメータを使用する HTTP メソッドも含まれます。
REST インターフェースは、HTTP POST 呼び出しを使用して、JSON 構文のメトリック データのペイロードにより、メトリック データを受信します。さらに、EPAgent プラグイン REST インターフェースは、GZIP 圧縮の JSON メトリック データを処理できます。
2
HTTP RESTful インターフェースの有効化
REST インターフェースをインフラストラクチャ エージェントに対して有効にします。
  1. <Agent_Home>/core/config ディレクトリに移動し、テキスト エディタで IntroscopeAgent.profile ファイルを開きます。
  2. introscope.epagent.config.httpServerPort
    プロパティを設定します。
  3. ファイルを保存します。
  4. インフラストラクチャ エージェントを再起動します。
RESTful Metric Feed インターフェース
タイプ
メトリック
{"type" : "<a supported metric type>",
"name" : "<a unique metric name (including path but excluding host|process|agent)>",
"value" : "<the metric value>"}
}
有効なメトリック データ タイプ
メトリックのメトリック タイプの属性が以下の属性のいずれかであることを確認します。
PerIntervalCounter
値は、間隔ごとのレートです。このメトリックは、値を合計することによって、一定期間で集約されます。値の合計は、カウンタによって保持されます。15 秒の間隔の終了時に、カウンタの値がレポートされます。その後、カウンタはゼロにリセットされます。
何かが発生しているレートについてレポートする場合は常に、このデータ タイプを使用します。たとえば、間隔ごとのエラーのレートなどです。
IntCounter/LongCounter
メトリックに送信される integer 値または long 値がレポートされます。この属性では、新しい値が指定されるまで、15 秒間隔で同じ値をレポートし続けます。
このデータ タイプは、キュー深度や使用可能スレッド数など、ゲージのような集計メトリックのレポートのコンテキストで役立つ場合があります。
IntAverage/LongAverage
この属性では、メトリックに指定するタイミングの平均(integer または long)が計算されてレポートされます。IntAverage/LongAverage が測定値を受け取ると、現在のカウントと、現在の結果の平均が保持されます。各 15 秒間隔の終了時に、この属性は測定値に関する情報をレポートします。IntAverage/LongAverage では、測定の回数、すべての測定値の平均、最速の測定値、および最も遅い測定値がレポートされます。
「平均遅延時間(ミリ秒)」のような応答時間を計算するには、このデータ タイプを使用します。
IntRate
1 秒あたりのレート(整数)。IntRate では、指定した 1 つ以上の値が 15 で除算されます。この属性は、ライブ データを見る場合、
1 秒あたり
のレートを前提にしています。15 秒間隔の場合、残りの部分(14 以下)は切り捨てられます。複数の期間にわたって集約される場合、加重平均が集約値として使用されます。
たとえば、
queries per second
のコンテキストでこのデータ タイプを使用します。
StringEvent
プロセス ID やスタートアップ コマンド ラインなどの文字列値がレポートされます。このメトリック データ タイプでは、メモリおよび帯域幅に関して相当のオーバーヘッドが生じるため、慎重に使用します。文字列イベントとしてログ エントリをレポートすることはお勧めしません。
タイムスタンプ
このデータ タイプでは、連続して増加するタイムスタンプが生成されます。値は、1970 年 1 月 1 日 00 時 00 分 00 秒(UTC)からの経過ミリ秒数である UNIX 時間です。
パフォーマンス メトリックは、Enterprise Manager が受信するときにタイムスタンプがすべて自動的に付けられるため、タイムスタンプのレポートは不要です。
Metric Feed
{"host" : "<agent hostname>", (Optional. If set, it must match that in IntroscopeAgent.properties)
"process" : "<agent process name>", (Optional. If set, it must match that in IntroscopeAgent.properties)
"agent" : "<agent name>", (Optional. If set, it must match that in IntroscopeAgent.properties)
"metrics" : [{"type" : "<type>", "name" : "<name>", "value" : "<value>"},
{"type" : "<type>", "name" : "<name>", "value" : "<value>"},
{"type" : "<type>", "name" : "<name>", "value" : "<value>"}
MetricFeedResponse
{"errorCode" : (Only included when errors processing metric feed bundle occur)
"errorMessage" : "One or more metric specifications were invalid", (Only included when errors processing metric feed bundle occur)
"invalidCount" : 2, (Only included when count > 0)
"validCount" : 1
"metricErrors" : [
{"metricName" : "<metric name>", "metricErrorCode" : "<error code>", "metricErrorMsg" : "<error message>", "metricErrorIndex" : <the index of the erroneous metric in the submitted metric list>},
{"metricName" : "<metric name>", "metricErrorCode" : "<error code>", "metricErrorMsg" : "<error message>", "metricErrorIndex" : <the index of the erroneous metric in the submitted metric list>}
] (metricErrors only included when there are errors processing one or more metrics)
}
URI
メトリック フィード URI
URL:
http://<EPA Host>:<EPA HTTP Port>/apm/metricFeed
メソッド:
POST
ヘッダ:
"Content-Type:application/json"
HTTP 成功応答コード:
200 (OK)
{"validMetricCount" : <正常に送信されたメトリックの数>}
GZIP 圧縮
GZIP 圧縮を有効にするには、HTTP ペイロード全体に対して gzip を実行し、以下の HTTP ヘッダを含めます。
ヘッダ:
"Content-Encoding:gzip"
エラー コード
ペイロード エラー
コード
メッセージ
1,000
Invalid Request. A valid request must have a Content-Type header. The only supported value is application/json.
A valid request must have a valid json payload containing a MetricFeed object.
A valid request may have a Content-Encoding header. Supported encodings are gzip, x-gzip, and identity.
A valid request may specify a charset in the Content-Type header. The specified charset must be supported by the
installed java implementation.
1001
Invalid JSON
入力が、JSON として解析可能ではありません。
1010
One or more metric specifications were invalid
応答には、無効な各メトリックについて、メトリックごとのエラーが含まれます。
最初の 100 件に制限されます。
メトリックごとのエラー
コード
メッセージ
1011
Invalid metric name
Name = (MetricName) | (ResourceSegments “:” MetricName)
各項目の説明:
ResourceSegments = (ResourceName) | (ResourceSegments “|” ResourceName)
MetricName = 「|」または「:」以外の任意の Unicode 文字列(後続スペースなし)
ResourceName = 「|」または「:」以外の任意の Unicode 文字列
1012
Invalid metric type
有効なタイプは、LongAverage、IntAverage、LongCounter、IntCounter、IntRate、StringEvent、TimeStamp、PerIntervalCounter です。
1013
Invalid metric value
通常、値が指定されたタイプと一致しない場合に表示されます( IntCounter の値が「hello world」の場合など)。
1014
Metric clamp exceeded
デフォルトのメトリック クランプが 5000 に達したためにメトリックを作成できませんでした。このデフォルト値を上書きするには、
introscope.agent.metricClamp=
プロパティを
IntroscopeAgent.properties
ファイルに追加し、カスタムのクランプ値を設定します。処理するメトリックが多いほど、EPAgent プラグイン プロセスによるリソース使用率が高くなります。
HTTP 応答コード
コード
メッセージ
200
Success
出力に、送信された有効なメトリックの数が含まれています。
400
Invalid request
上記のエラー コード 1000 と 1001 およびそれ以上にマップされます。
409
Partial success
上記のエラー コード 1010 およびそれ以上にマップされ、送信されたエラーのあるメトリックごとに個別のメトリック エラーが示されます。
415
Invalid encoding
gzip または Identity 以外の Content-Encoding ヘッダがメトリック バンドルとともに送信されました。
cURL を使用したサンプルの HTTP POST コール
curl -i -H "Content-type: application/json" -X POST http://my-host-name:8080/apm/metricFeed -d '{ metrics : [{type : "PerIntervalCounter", name : "MyTest|RESTFul|PerIntervalCounter|Test1:Count", value : "123"}] }'
curl -i -H "Content-type: application/json" -X POST http://my-host-name:8080/apm/metricFeed -d '{ metrics : [{type : "LongCounter", name : "MyTest|RESTFul|LongCounter|Test2:Count", value : "456"}] }