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"}

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

注3：value 的值是時間戳和當前的值

區間向量

通過使用 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"
    ]
}