[17.0.0.3 以及更新版本]

MicroProfile 度量 REST API

mpMetrics-1.0mpMetrics-1.1 特性提供 REST API 來顯示度量,以供管理者存取。

格式

度量端點提供兩種輸出格式。用於每一個回應的格式,取決於對應要求的 HTTP accept 標頭。
Prometheus 文字格式
相容於 Prometheus 監視工具的度量表示法。如果要求具有 text/plain accept 標頭,則會傳回此格式。
JSON 格式
度量的 JSON 表示法。如果要求具有 application/json accept 標頭,則會傳回此格式。

REST 端點

下表說明可供存取以提供度量的不同端點。
端點 要求類型 支援的格式 說明
/metrics GET JSON、Prometheus 傳回所有已登錄的度量。
/metrics/<scope> GET JSON、Prometheus 針對個別的範圍,傳回已登錄的度量。
/metrics/<scope>/<metric name> GET JSON、Prometheus 針對個別的範圍,傳回符合該度量名稱的度量。
/metrics OPTIONS JSON 傳回所有已登錄的度量 meta 資料。
/metrics/<scope> OPTIONS JSON 針對個別的範圍,傳回已登錄的度量 meta 資料。
/metrics/<scope>/<metric name> OPTIONS JSON 針對個別的範圍,傳回符合該度量名稱的度量 meta 資料。

連接至資料儲存庫和監視工具

管理者可以將其應用程式度量連接至可用來分析及監視度量資訊的其他工具和堆疊。

依預設,/metrics 端點會以 Prometheus 相容格式來傳回資料。如果要將 Liberty 伺服器連接至 Prometheus,請將 Prometheus 配置成使用 https://host:https_port/metrics 端點。

瞭解 JSON 的其他度量收集工具可以使用 JSON 格式。例如,可將 collectd curl_json 外掛程式配置成解譯 MicroProfile 度量中的 JSON 格式。之後 collectd 就可將資料轉遞給 Graphite 等不同的工具。

Prometheus 格式的詳細資料

Prometheus 文字格式是以 Prometheus 說明文件中所述的 0.0.4 闡述格式為基礎。對於每一個度量,都會提供 meta 資料(若有的話)。# Help 字行包含度量的說明。meta 資料中所呈現的任何標籤,都會以 Prometheus 標籤形式提供。若為量規和直方圖,則度量名稱尾端會附加度量的單位。

量規會以單一值表示。下列範例說明如何顯示名為 cost 且單位是 dollars 的量規:
# TYPE application:cost_dollars gauge
# HELP application:cost_dollars The running cost of the server in dollars.
application:cost_dollars 80        
下列範例說明針對計數器產生的文字格式。對於計數器,輸出只會包含一值。
# 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 前一分鐘的平均比率(事件/秒)。
fiveMinRate 前五分鐘的平均比率(事件/秒)。
fifteenMinRate 前十五分鐘的平均比率(事件/秒)。
下列範例說明直方圖的 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 前一分鐘的平均比率(事件/秒)。
fiveMinRate 前五分鐘的平均比率(事件/秒)。
fifteenMinRate 前十五分鐘的平均比率(事件/秒)。
min 所記錄的最小值。
max 所記錄的最大值。
mean 平均值。
stddev 標準差。
p50 第 50 個百分位的值,與中位數相同。
p75 第 75 個百分位的值。
p95 第 95 個百分位的值。
p98 第 98 個百分位的值。
p99 第 99 個百分位的值。
p999 第 999 個百分位的值。

JSON 格式的詳細資料 - OPTIONS

會以相同的樹狀樣式來顯示 meta 資料,而子樹狀結構會顯示子項資源。度量的名稱會對映至其 meta 資料值。例如,如果 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