EPAgent RESTful インターフェースの設定
EPAgent RESTful インターフェースの設定
apmdevops102jp
アプリケーションまたは環境から収集されるメトリックを送信するように EPAgent HTTP RESTful インターフェースを設定することができます。HTTP RESTful インターフェースは、既存の EPAgent メトリック収集ソリューション(ステートフル/ステートレス プラグイン、ネットワーク ソケット リスナ、GET とクエリ パラメータを使用する HTTP メソッドなど)と組み合わせて使用することができます。
EPAgent に対して REST インターフェースを有効にするには、IntroscopeEPAgent.properties ファイルの introscope.epagent.config.httpServerPort を設定します。REST インターフェースは、HTTP POST 呼び出しを使用して、JSON 構文のメトリック データのペイロードにより、メトリック データを受信します。さらに、EPAgent REST インターフェースは、GZIP 圧縮の JSON メトリック データを処理できます。
2
タイプ
メトリック
{"type" : "<a supported metric type>","name" : "<a unique metric name (including path but excluding host|process|agent)>","value" : "<the metric value>"}}
有効なメトリック データ タイプ
メトリックの type 属性は、以下のいずれかである必要があります。
PerIntervalCounter
値は、間隔ごとのレートです。このメトリックは、値を合計することによって、一定期間で集約されます。値の合計は、カウンタによって保持されます。15 秒の間隔の終了時に、カウンタの値がレポートされます。その後、カウンタはゼロにリセットされます。
何かが発生するレート、たとえば「間隔ごとのエラー数」のようなレートについてレポートする必要がある場合は常に、このデータ タイプを使用します。
IntCounter/LongCounter
メトリックに送信される integer 値または long 値がレポートされます。この値のレポートは、新しい値が指定されるまで、15 秒間隔で維持されます。
このデータ タイプは、キュー深度や使用可能スレッド数など、ゲージのような集計メトリックのレポートのコンテキストで役立つ場合があります。
IntAverage/LongAverage
メトリックに指定するタイミングの平均(integer または long)が計算されてレポートされます。IntAverage/LongAverage が測定値を受け取ると、現在のカウントと、現在の結果の平均が保持されます。各 15 秒間隔の終了時に、測定の回数、すべての測定値の平均、最速の測定値、および最も遅い測定値がレポートされます。
「平均遅延時間(ミリ秒)」のような応答時間を計算するには、このデータ タイプを使用します。
IntRate
1 秒あたりのレート(整数)。IntRate では、指定した値が 15 で除算されます。ライブ データを見る場合、
1 秒あたり
のレートを前提にしています。15 秒間隔の場合、残りの部分(14 以下)は切り捨てられます。複数の期間にわたって集約される場合、加重平均が集約値として使用されます。たとえば、「queries per second」のコンテキストでこのデータ タイプを使用します。
StringEvent
プロセス ID やスタートアップ コマンド ラインなどの文字列値がレポートされます。このメトリック データ タイプでは、メモリおよび帯域幅に関して相当のオーバーヘッドが生じるため、慎重に使用します。文字列イベントとしてログ エントリをレポートすることはお勧めしません。
タイムスタンプ
このデータ タイプでは、連続して増加するタイムスタンプが生成されます。値は、1970 年 1 月 1 日 00時 00分 00 秒(UTC)からの経過ミリ秒数である UNIX 時間です。
パフォーマンス メトリックには、APM での受信時にタイムスタンプがすべて自動的に付けられるため、通常、タイムスタンプのレポートは不要であることに注意してください。
Metric Feed
{"host" : "<agent hostname>", (Optional. If set, it must match that in IntroscopeEPAgent.properties)"process" : "<agent process name>", (Optional. If set, it must match that in IntroscopeEPAgent.properties)"agent" : "<agent name>", (Optional. If set, it must match that in IntroscopeEPAgent.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 に達したためにメトリックを作成できませんでした。このデフォルト値を上書きするには、 プロパティを ファイルに追加し、カスタムのクランプ値を設定します。処理するメトリックが多いほど、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"}] }