[17.0.0.3 and later]

MicroProfile Metrics REST API

mpMetrics-1.0 フィーチャーおよび mpMetrics-1.1 フィーチャーは、管理者がアクセスするための、メトリックを表示する REST API を提供します。

フォーマット

メトリック・エンドポイントは、2 つの出力フォーマットを提供します。各応答に使用されるフォーマットは、対応する要求の HTTP accept ヘッダーに依存します。
Prometheus テキスト・フォーマット
Prometheus モニタリング・ツールと互換性のあるメトリック表記。このフォーマットは、accept ヘッダーが text/plain の要求に対して返されます。
JSON フォーマット
メトリックの JSON 表記。このフォーマットは、accept ヘッダーが application/json の要求に対して返されます。

REST エンドポイント

次の表は、メトリックを提供するためにアクセスできるさまざまなエンドポイントを示しています。
エンドポイント 要求タイプ サポートされるフォーマット 説明
/metrics GET JSON、Prometheus すべての登録済みメトリックを返します。
/metrics/<scope> GET JSON、Prometheus それぞれのスコープの登録済みメトリックを返します。
/metrics/<scope>/<metric name> GET JSON、Prometheus それぞれのスコープのメトリック名と一致するメトリックを返します。
/metrics OPTIONS JSON すべての登録済みメトリック・メタデータを返します。
/metrics/<scope> OPTIONS JSON それぞれのスコープの登録済みメトリック・メタデータを返します。
/metrics/<scope>/<metric name> OPTIONS JSON それぞれのスコープのメトリック名と一致するメトリック・メタデータを返します。

データ・ストアおよびモニタリング・ツールへの接続

管理者は、アプリケーション・メトリックを、メトリック情報を分析およびモニターできる他のツールやスタックに接続できます。

デフォルトでは、/metrics エンドポイントは、Prometheus と互換のフォーマットでデータを返します。Liberty サーバーを Prometheus に接続するには、https://host:https_port/metrics エンドポイントを使用するように Prometheus を構成します。

JSON を理解する他のメトリック収集ツールは JSON フォーマットを使用できます。例えば、collectd curl_json プラグインを、MicroProfile メトリックからの JSON フォーマットを解釈するように構成できます。そうすると、collectd は、さまざまなツール (Graphite など) に情報を転送できます。

Prometheus フォーマットの詳細

Prometheus テキスト・フォーマットは、Prometheus 資料で説明されている 0.0.4 公開フォーマットに基づいています。使用可能な場合、メタデータが各メトリックに対して提供されます。# Help 行に、メトリックの説明が含まれます。メタデータ内にあるタグは、Prometheus ラベルとして提供されます。ゲージおよびヒストグラムのメトリック名の末尾にはメトリックの単位が付加されます。

ゲージは単一値で表されます。次の例は、cost という名前で単位が dollars のゲージがどのように表示されるのかを示しています。
# TYPE application:cost_dollars gauge
# HELP application:cost_dollars The running cost of the server in dollars.
application:cost_dollars 80        
次の例は、カウンターの場合に生成されるテキスト・フォーマットを示しています。出力には、カウンターの 1 つの値のみが含まれます。
# TYPE application:visitors counter
# HELP application:visitors The number of unique visitors
application:visitors 80
メーターは、複数の値で構成されます。次の例は、requests という名前のメーターがどのように表示されるのかを示しています。
# TYPE application:requests_count counter 
# HELP application:requests_count Tracks the number of requests to the server 
application:requests_count 29382
# TYPE application:requests_rate_per_second gauge 
application:requests_rate_per_second 12.223
# TYPE application:requests_one_min_rate_per_second gauge 
application:requests_one_min_rate_per_second 12.563
# TYPE application:requests_five_min_rate_per_second gauge 
application:requests_five_min_rate_per_second 12.364
# TYPE application:requests_fifteen_min_rate_per_second gauge 
application:requests_fifteen_min_rate_per_second 12.126
ヒストグラムは、複数の値で構成されます。次の例は、file_sizes という名前で単位が bytes に設定されたヒストグラムがどのように表示されるのかを示しています。
# TYPE application:file_sizes_mean_bytes gauge
application:file_sizes_mean_bytes 4738.231
# TYPE application:file_sizes_max_bytes gauge
application:file_sizes_max_bytes 31716
# TYPE application:file_sizes_min_bytes gauge
application:file_sizes_min_bytes 180
# TYPE application:file_sizes_stddev_bytes gauge
application:file_sizes_stddev_bytes 1054.7343037063602
# TYPE application:file_sizes_bytes summary
# HELP application:file_sizes_bytes Users file size
application:file_sizes_bytes_count 2037
application:file_sizes_bytes{quantile="0.5"} 4201
application:file_sizes_bytes{quantile="0.75"} 6175
application:file_sizes_bytes{quantile="0.95"} 13560
application:file_sizes_bytes{quantile="0.98"} 29643
application:file_sizes_bytes{quantile="0.99"} 31716
application:file_sizes_bytes{quantile="0.999"} 31716
タイマー・メトリックは、複数の値で構成されます。次の例は、response_time という名前のタイマーがどのように表示されるのかを示しています。
# TYPE application:response_time_rate_per_second gauge 
application:response_time_rate_per_second  0.004292520715985437
# TYPE application:response_time_one_min_rate_per_second gauge 
application:response_time_one_min_rate_per_second  2.794076465421066E-14
# TYPE application:response_time_five_min_rate_per_second  gauge 
application:response_time_five_min_rate_per_second  4.800392614619373E-4
# TYPE application:response_time_fifteen_min_rate_per_second  gauge 
application:response_time_fifteen_min_rate_per_second  0.01063191047532505
# TYPE application:response_time_mean_seconds gauge 
application:response_time_mean_seconds 0.000415041
# TYPE application:response_time_max_seconds gauge 
application:response_time_max_seconds 0.0005608694
# TYPE application:response_time_min_seconds gauge 
application:response_time_min_seconds 0.000169916
# TYPE application:response_time_stddev_seconds gauge 
application:response_time_stddev_seconds 0.000652907
# TYPE application:response_time_seconds summary 
# HELP application:response_time_seconds Server response time for /index.html
application:response_time_seconds_count 80
application:response_time_seconds{quantile="0.5"} 0.0002933240
application:response_time_seconds{quantile="0.75"} 0.000344914
application:response_time_seconds{quantile="0.95"} 0.000543647
application:response_time_seconds{quantile="0.98"} 0.002706543
application:response_time_seconds{quantile="0.99"} 0.005608694
application:response_time_seconds{quantile="0.999"} 0.005608694

JSON フォーマットの詳細 - GET

JSON フォーマットは、ツリー形式でフォーマットされたデータを返します。各メトリックは、名前と、値 (ゲージおよびカウンターの場合) またはマップ (メーター、ヒストグラム、およびタイマーの場合) のいずれかによって参照されます。

/metrics が要求された場合、スコープのデータがスコープ名にラップされます。
{
  "application": {
    "hitCount": 45
  },
  "base": {
     "thread.count" : 33,
     "thread.max.count" : 47
  },
  "vendor": {...}
}
ゲージおよびカウンターの場合、値はメトリックの値です。次の例は、/metrics/application の呼び出しで返されるものを示しています。
{
  "hitCount": 45
}
次の例は、メーターの JSON オブジェクトを示しています。
{
  "requests": {
    "count": 29382,
    "meanRate": 12.223,
    "oneMinRate": 12.563,
    "fiveMinRate": 12.364,
    "fifteenMinRate": 12.126,
  }
}
この例では、以下のキーがあります。
count イベント数のカウント。
meanRate メトリック登録以降の平均レート (イベント/秒)。
oneMinRate 最後の 1 分間の平均レート (イベント/秒)。
fiveMinRate 最後の 5 分間の平均レート (イベント/秒)。
fifteenMinRate 最後の 15 分間の平均レート (イベント/秒)。
次の例は、ヒストグラムの JSON オブジェクトを示しています。
{ 
"file_sizes": {
    "count":2,
    "min":-1624,
    "max":26,
    "mean":-799.0,
    "stddev":825.0,
    "p50":26.0,
    "p75":26.0,
    "p95":26.0,
    "p98":26.0,
    "p99":26.0,
    "p999":26.0
  }
}
この例では、以下のキーがあります。
count イベント数のカウント。
min 記録された最小値。
max 記録された最大値。
mean 平均値。
stddev 標準偏差。
p50 第 50 百分位数の値 (中央値と同じ)。
p75 第 75 百分位数の値。
p95 第 95 百分位数の値。
p98 第 98 百分位数の値。
p99 第 99 百分位数の値。
p999 第 999 百分位数の値。
次の例は、タイマーの JSON オブジェクトを示しています。
{
  "responseTime": {
    "count": 29382,
    "meanRate":12.185627192860734,
    "oneMinRate": 12.563,
    "fiveMinRate": 12.364,
    "fifteenMinRate": 12.126,
    "min":169916,
    "max":5608694,
    "mean":415041.00024926325,
    "stddev":652907.9633011606,
    "p50":293324.0,
    "p75":344914.0,
    "p95":543647.0,
    "p98":2706543.0,
    "p99":5608694.0,
    "p999":5608694.0
  }
}
count イベント数のカウント。
meanRate メトリック登録以降の平均レート (イベント/秒)。
oneMinRate 最後の 1 分間の平均レート (イベント/秒)。
fiveMinRate 最後の 5 分間の平均レート (イベント/秒)。
fifteenMinRate 最後の 15 分間の平均レート (イベント/秒)。
min 記録された最小値。
max 記録された最大値。
mean 平均値。
stddev 標準偏差。
p50 第 50 百分位数の値 (中央値と同じ)。
p75 第 75 百分位数の値。
p95 第 95 百分位数の値。
p98 第 98 百分位数の値。
p99 第 99 百分位数の値。
p999 第 999 百分位数の値。

JSON フォーマットの詳細 - OPTIONS

メタデータは、同じツリー・スタイルを使用して、サブリソースのサブツリーと共に表示されます。メトリックの名前は、メトリックのメタデータ値にマップされます。例えば、 GET /metrics/applications が次のような複数の値を表示するとします。
{
  "fooVal": 12345,
  "barVal": 42
}
この場合、OPTIONS /metrics/application は以下を表示します。
{
  "fooVal": {
    "unit": "milliseconds",
    "type": "gauge",
    "description": "The average duration of foo requests during last 5 minutes",
    "displayName": "Duration of foo",
    "tags": "app=webshop"
  },
  "barVal": {
    "unit": "megabytes",
    "type": "gauge",
    "tags": "component=backend,app=webshop"
  }
}

トピックのタイプを示すアイコン 参照トピック

ファイル名: rwlp_mp_metrics_rest_api.html