grafana +Prometheus API 使用
Prometheus API 使用了 JSON 格式的響應內容。 輸入時間戳可以由 RFC3339 格式或者 Unix 時間戳提供,後面可選的小數位可以精確到亞秒級別。輸出時間戳以 Unix 時間戳的方式呈現。所有的 API請求返回的格式均使用以下的 JSON 格式:
{ "status": "success" | "error", "data": <data>, // Only set if status is "error". // additional data. "errorType": "<string>", "error": "<string>" }
表示式查詢
我們可以分別通過/api/v1/query
和/api/v1/query_range
查詢 PromQL 表示式瞬時或者一定時間範圍內的查詢結果。當 API 呼叫成功後,Prometheus 會返回 JSON 格式的響應內容。
表示式查詢結果會在 data 部分的 result 欄位中返回以下的響應值。響應資料格式一共分為四種:
瞬時向量
通過使用QUERY API
我們可以查詢 PromQL 在特定時間點下的計算結果。
URL 請求引數:
query=<string> : PromQL 表示式。
time=<rfc3339 | unix_timestamp> : 用於指定用於計算 PromQL的時間戳。可選引數,預設情況下使用當前系統時間。
當 API 呼叫成功後,Prometheus 會返回 JSON 格式的響應內容,並且在 data 部分返回查詢結果。data 部分格式如下:
{ "resultType":"vector", "result": <value> }
data
返回查詢結果。value
指的是查詢結果資料,具體的格式取決於resultType,不同的結果型別,會有不同的結果資料格式。瞬時資料的resultType為vector。區間資料的resultType為matrix。當返回資料型別 resultType 為 vector 時,是一組時間序列,每個時間序列包含單個樣本。result 響應格式如下:
[ { "metric": { "<label_name>": "<label_value>", ... }, "value": [ <unix_time>, "<sample_value>" ] }, ... ]
這個 url 的查詢結果為當前時間node_disk_io_now指標的查詢結果。
Url="http://10.4.**.**:32075/api/v1/query?query=node_disk_io_now";
{ "status":"success", "data":{ "resultType":"vector", "result":[ { "metric":{ "__name__":"node_disk_io_now", "app":"prometheus", "component":"node-exporter", "device":"dm-0", "instance":"10.4.**.**:9100", "job":"kubernetes-endpoints", "kubernetes_name":"prometheus-node-exporter", "kubernetes_namespace":"monitoring" }, "value":[ 1542939382.369, "0" ] }, { "metric":{ "__name__":"node_disk_io_now", "app":"prometheus", "component":"node-exporter", "device":"dm-1", "instance":"10.4.**.**:9100", "job":"kubernetes-endpoints", "kubernetes_name":"prometheus-node-exporter", "kubernetes_namespace":"monitoring" }, "value":[ 1542939382.369, "0" ] } ] } }
注1:如果只是簡單輸入http://ip:port/api/v1/query會返回:
{"status":"error","errorType":"bad_data","error":"parse error at char 1: no expression found in input"}
- 1
注2:如果 time 引數預設,則使用當前伺服器時間。
區間向量
通過使用QUERY_RANGE API
我們則可以直接查詢 PromQL表示式在一段時間內返回的計算結果。
URL 請求引數:
query=<string> : PromQL 表示式。 start=<rfc3339 | unix_timestamp> : 起始時間戳。 end=<rfc3339 | unix_timestamp> : 結束時間戳。 step=<duration | float> : 查詢時間步長,時間區間內每 step 秒執行一次。
當使用 QUERY_RANGE API 查詢 PromQL 表示式時,返回結果一定是一個區間向量:
{ "resultType": "matrix", "result": <value> }
當返回資料型別 resultType 為 matrix 時,是一組時間序列,每個時間序列包含一段時間範圍內的樣本資料。result 響應格式如下:
[ { "metric": { "<label_name>": "<label_value>", ... }, "values": [ [ <unix_time>, "<sample_value>" ], ... ] }, ... ]
這個 url 的查詢結果為2018-11-22 17:20:23到2018-11-22 17:20:33這十秒內 ,指標http_requests_total的查詢結果:
Url="http://10.4.54.31:32075/api/v1/query_range?query=http_requests_total&start=1542878423.447&end=1542878433.447&step=10s";
{ "status":"success", "data":{ "resultType":"matrix", "result":[ { "metric":{ "__name__":"http_requests_total", "code":"200", "handler":"prometheus", "instance":"node1", "job":"kubernetes-nodes", "method":"get" }, "values":[ [ 1542878423.447, "86031" ], [ 1542878433.447, "86032" ] ] } ] } }
標量
當返回資料型別 resultType 為 scalar 時,是一個浮點型的資料值。result 響應格式如下:
[ <unix_time>, "<scalar_value>" ]
字串
當返回資料型別 resultType 為 string 時,是一個簡單的字串值。result 響應格式如下:
[ <unix_time>, "<string_value>" ]
字串型別的響應內容格式和標量相同。
元資料查詢
標籤選擇器查詢
我們可以通過 /api/v1/series 返回與特定標籤集匹配的時間序列列表。
URL 請求引數:
match[]=<series_selector> : 表示標籤選擇器是 series_selector。必須至少提供一個 match[] 引數。 start=<rfc3339 | unix_timestamp> : 起始時間戳。 end=<rfc3339 | unix_timestamp> : 結束時間戳。
如我們查出所有job名為kubernetes-cadvisor的up指標和所有kubernetes_name名為kube-state-metrics的process_start_time_seconds指標:
Url="http://10.4.**.**:32075/api/v1/series?match[]=up{job=\"kubernetes-cadvisor\"}&match[]=process_start_time_seconds{kubernetes_name=\"kube-state-metrics\"}";
{ "status":"success", "data":[ { "__name__":"process_start_time_seconds", "app":"prometheus", "component":"node-exporter", "instance":"10.4.**.**:9100", "job":"kubernetes-endpoints", "kubernetes_name":"prometheus-node-exporter", "kubernetes_namespace":"monitoring" }, { "__name__":"up", "app":"kube-state-metrics", "instance":"10.233.102.139:8080", "job":"kubernetes-endpoints", "kubernetes_name":"kube-state-metrics", "kubernetes_namespace":"monitoring" } ] }
標籤值查詢
我們可以通過 /api/v1/label/‘label_name’/values 返回帶有指定標籤的標籤值列表。
如我們查出所有標籤名為 job 的標籤值:
Url="http://10.4.**.**:32075/api/v1/label/job/values";
{ "status":"success", "data":[ "kubernetes-cadvisor", "kubernetes-endpoints", "kubernetes-nodes", "kubernetes-pods" ] }