Prometheus監控學習筆記之在 HTTP API 中使用 PromQL

 

0x00 概述

Prometheus 當前穩定的 HTTP API 可以通過 /api/v1 訪問。

 

0x01 API 響應格式

Prometheus API 使用了 JSON 格式的響應內容。 當 API 調用成功后將會返回 2xx 的 HTTP 狀態碼。

反之，當 API 調用失敗時可能返回以下幾種不同的 HTTP 狀態碼：

• 404 Bad Request ：當參數錯誤或者缺失時。

• 422 Unprocessable Entity : 當表達式無法執行時。

• 503 Service Unavailable : 當請求超時或者被中斷時。

所有的 API 請求返回的格式均使用以下的 JSON 格式：

{
"status": "success" | "error",
"data": <data>,
 
// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "<string>",
"error": "<string>"
}

輸入時間戳可以由 RFC3339 格式或者 Unix 時間戳提供，后面可選的小數位可以精確到亞秒級別。輸出時間戳以 Unix 時間戳的方式呈現。

查詢參數名稱可以用中括號 [] 重復次數。<series_selector> 占位符提供像 http_requests_total 或者 http_requests_total{method=~"(GET|POST)"} 的 Prometheus 時間序列選擇器，並需要在 URL 中編碼傳輸。

<duration> 占位符指的是 [0-9]+[smhdwy] 形式的 Prometheus 持續時間字符串。例如：5m 表示 5 分鍾的持續時間。

<bool> 提供布爾值（字符串 true 和 false）。

 

0x02 表達式查詢

通過 HTTP API 我們可以分別通過 /api/v1/query 和 /api/v1/query_range 查詢 PromQL 表達式當前或者一定時間范圍內的計算結果。

瞬時數據查詢

通過使用 QUERY API 我們可以查詢 PromQL 在特定時間點下的計算結果。

 

GET /api/v1/query

URL 請求參數：

• query=<string> : PromQL 表達式。

• time=<rfc3339 | unix_timestamp> : 用於指定用於計算 PromQL 的時間戳。可選參數，默認情況下使用當前系統時間。

• timeout=<duration> : 超時設置。可選參數，默認情況下使用全局設置的參數 -query.timeout。

如果 time 參數缺省，則使用當前服務器時間。

當 API 調用成功后，Prometheus 會返回 JSON 格式的響應內容，格式如上小節所示。並且在 data 部分返回查詢結果。data 部分格式如下：

{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}

<value> 指的是查詢結果數據，具體的格式取決於 resultType，不同的結果類型，會有不同的結果數據格式。參考 響應數據格式。

例如使用以下表達式查詢表達式 up 在時間點 2015-07-01T20:10:51.781Z 的計算結果：

$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
"status" : "success",
"data" : {
"resultType" : "vector",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"value": [ 1435781451.781, "1" ]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9100"
},
"value" : [ 1435781451.781, "0" ]
}
]
}
}

 

區間數據查詢

使用 QUERY_RANGE API 我們則可以直接查詢 PromQL 表達式在一段時間返回內的計算結果。

 

GET /api/v1/query_range

URL 請求參數：

• query=<string> : PromQL 表達式。

• start=<rfc3339 | unix_timestamp> : 起始時間戳。

• end=<rfc3339 | unix_timestamp> : 結束時間戳。

• step=<duration | float> : 查詢時間步長，時間區間內每 step 秒執行一次。

• timeout=<duration> : 超時設置。可選參數，默認情況下使用全局設置的參數 -query.timeout。

當使用 QUERY_RANGE API 查詢 PromQL 表達式時，返回結果一定是一個區間向量：

{
"resultType": "matrix",
"result": <value>
}

[info] 注意

在 QUERY_RANGE API 中 PromQL 只能使用瞬時向量選擇器類型的表達式。

對於 <value> 占位符的格式，詳見 區間向量查詢結果格式。

例如使用以下表達式查詢表達式 up 在 30 秒范圍內以 15 秒為間隔計算 PromQL 表達式的結果。

$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
"status" : "success",
"data" : {
"resultType" : "matrix",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"values" : [
[ 1435781430.781, "1" ],
[ 1435781445.781, "1" ],
[ 1435781460.781, "1" ]
]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
"values" : [
[ 1435781430.781, "0" ],
[ 1435781445.781, "0" ],
[ 1435781460.781, "1" ]
]
}
]
}
}

 

0x03 查詢元數據

通過標簽選擇器查找時間序列

以下表達式返回與特定標簽集匹配的時間序列列表：

 

GET /api/v1/series

URL 請求參數：

• match[]=<series_selector> : 表示標簽選擇器是 series_selector。必須至少提供一個 match[] 參數。

• start=<rfc3339 | unix_timestamp> : 起始時間戳。

• end=<rfc3339 | unix_timestamp> : 結束時間戳。

返回結果的 data 部分，是由 key-value 鍵值對的對象列表組成的。

例如使用以下表達式查詢表達式 up 或 process_start_time_seconds{job="prometheus"} 的計算結果：

$ curl -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
{
"status" : "success",
"data" : [
{
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
{
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
{
"__name__" : "process_start_time_seconds",
"job" : "prometheus",
"instance" : "localhost:9090"
}
]
}

 

查詢標簽值

下面這個例子返回了帶有指定標簽的的時間序列列表：

 

GET /api/v1/label/<label_name>/values

返回結果的 data 部分是一個標簽值列表。例如，以下表達式返回結果的 data 部分是標簽名稱為 job 的所有標簽值：

$ curl http://localhost:9090/api/v1/label/job/values
{
"status" : "success",
"data" : [
"node",
"prometheus"
]
}

 

0x04 響應數據格式

表達式查詢結果可能會在 data 部分的 result 字段中返回以下的響應值。其中 <sample_value> 占位符是數值樣本值。由於 json 不支持特殊浮點值，例如：NaN, Inf, 和 -Inf，所以樣本值將會作為字符串（而不是原始數值）來進行傳輸。

區間向量

當返回數據類型 resultType 為 matrix 時，result 響應格式如下：

[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ]
},
...
]

其中 metrics 表示當前時間序列的特征維度，values 包含當前事件序列的一組樣本。

 

瞬時向量

當返回數據類型 resultType 為 vector 時，result 響應格式如下：

[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ]
},
...
]

其中 metrics 表示當前時間序列的特征維度，values 包含當前事件序列的一組樣本。

 

標量

當返回數據類型 resultType 為 scalar 時，result 響應格式如下：

[ <unix_time>, "<scalar_value>" ]

由於標量不存在時間序列一說，因此 result 表示為當前系統時間一個標量的值。

 

字符串

當返回數據類型 resultType 為 string 時，result 響應格式如下：

[ <unix_time>, "<string_value>" ]

字符串類型的響應內容格式和標量相同。