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 に達したためにメトリックを作成できませんでした。このデフォルト値を上書きするには、
introscope.agent.metricClamp=
プロパティを
IntroscopeEPAgent.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"}] }