HttpAPI訪問 · Prometheus中文文檔

## HTTP API --- 在Prometheus服務上`/api/v1`版本api是穩定版。 ### 格式概述這個API返回是JSON格式。每個請求成功的返回值都是以`2xx`開頭的編碼。到達API處理的無效請求，返回一個JSON錯誤對象，并返回下面的錯誤碼： - `400 Bad Request`。當參數錯誤或者丟失時。 - `422 Unprocessable Entity`。當一個表達式不能被執行時。 - `503 Service Unavailable`。當查詢超時或者中斷時。在請求到達API之前，其他非`2xx`的錯誤碼可能會被返回。 JSON返回格式如下所示： ```JSON { "status": "success" | "error", "data": <data>, // 如果status是"error", 這個數據字段還會包括下面的數據 "errorType": "<string>", "error": "<string>" } ``` 輸入時間戳可以被[RFC3339](https://www.ietf.org/rfc/rfc3339.txt)格式或者Unix時間戳提供。輸出時間戳以Unix時間戳的方式呈現。查詢參數名稱可以用`[]`中括號重復次數。 `<series_selector>`占位符提供像`http_requests_total`或者`http_requests_total{method=~"^GET|POST$"}`的Prometheus時間序列選擇器，并需要在URL中編碼傳輸。 `<duration>`占位符涉及到`[0-9]-[smhdwy]`。例如：`5m`表示5分鐘的持續時間。 ### 表達式查詢查詢語言表達式可以在瞬時向量或者范圍向量中執行。 #### Instant queries(即時查詢) 瞬時向量的http restful api查詢： > GET /api/v1/query URL查詢參數： - `query=<string>`: Prometheus表達式查詢字符串。 - `time=<rfc3339 | uninx_timestamp>`: 執行時間戳，可選項。 - `timeout=<duration>`: 執行超時時間設置，默認由`-query.timeout`標志設置如果`time`缺省，則用當前服務器時間表示執行時刻。這個查詢結果的`data`部分有下面格式： ```JSON { "resultType": "matrix" | "vector" | "scalar" | "string", "result": <value> } ``` <value>是一個查詢結果數據，依賴于這個`resultType`格式, 不同的結果類型，則會有不同的結果數據格式。見[表達式查詢結果格式](https://prometheus.io/docs/querying/api/#expression-query-result-formats)。下面例子執行了在時刻是`2015-07-01T20:10:51.781Z`的`up`表達式： ```JSON $ 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" ] } ] } } ``` #### 范圍查詢下面評估了一個范圍時間的查詢表達式： > GET /api/v1/query_range URL查詢參數 - `query=<string>`: Prometheus表達式查詢字符串。 - `start=<rfc3339 | unix_timestamp>`: 開始時間戳。 - `end=<rfc3339 | unix_timestamp>`: 結束時間戳。 - `step=<duration>`: 查詢時間步長，范圍時間內每step秒執行一次。下面查詢結果格式的`data`部分： ```json { "resultType": "matrix", "result": <value> } ``` 對于`<value>`占位符的格式，詳見[范圍向量結果格式](https://prometheus.io/docs/querying/api/#range-vectors)。下面例子評估的查詢條件`up`，且30s范圍的查詢，步長是15s。 ```JSON $ 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" ] ] } ] } } ``` ### 查詢元數據 #### 通過標簽匹配器找到度量指標列表下面例子返回了度量指標列表且不返回時間序列數據值。 > GET /api/v1/series URL查詢參數： - `match[]=<series_selector>`: 選擇器是series_selector。這個參數個數必須大于等于1. - `start=<rfc3339 | unix_timestamp>`: 開始時間戳。 - `end=<rfc3339 | unix_timestamp>`: 結束時間戳。返回結果的`data`部分，是由key-value鍵值對的對象列表組成的。下面這個例子返回時間序列數據, 選擇器是`up`或者`process_start_time_seconds{job="prometheus"}` ```JSON $ 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 這個返回JSON結果的`data`部分是帶有label_name=job的值列表： ```JSON $ curl http://localhost:9090/api/v1/label/job/values { "status" : "success", "data" : [ "node", "prometheus" ] } ``` ### 刪除時間序列下面的例子，是從Prometheus服務中刪除匹配的度量指標和標簽列表： > DELETE /api/v1/series URL查詢參數 - `match[]=<series_selector>`: 刪除符合series_selector匹配器的時間序列數據。參數個數必須大于等于1. 返回JSON數據中的`data`部分有以下的格式 ``` { "numDeleted": <number of deleted series> } ``` 下面的例子刪除符合度量指標名稱是`up`或者時間序列為`process_start_time_seconds{job="prometheus"}`： ```JSON $ curl -XDELETE -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}' { "status" : "success", "data" : { "numDeleted" : 3 } } ``` ### 表達式查詢結果格式表達式查詢結果，在`data`部分的`result`部分中，返回下面的數據。`\<sample_value\>`占位符有數值樣本值。JSON不支持特殊浮點值，例如：`NaN`, `Inf`和`-Inf`。因此樣本值返回結果是字符串，不是原生的數值。 #### 范圍向量范圍向量返回的result類型是一個`matrix`矩陣。下面返回的結果是`result`部分的數據格式： ```JSON [ { "metric": { "<label_name>": "<label_value>", ... }, "values": [ [ <unix_time>, "<sample_value>" ], ... ] }, ... ] ``` #### 瞬時向量瞬時向量的`result`類型是`vector`。下面是`result`部分的數據格式 ```JSON [ { "metric": { "<label_name>": "<label_value>", ... }, "value": [ <unix_time>, "<sample_value>" ] }, ... ] ``` #### Scalars標量標量查詢返回`result`類型是`scalar`。下面是`result`部分的數據格式： > [ <unix_time>, "<scalar_value>" ] #### 字符串字符串的`result`類型是`string`。下面是`result`部分的數據格式： > [ <unix_time>, "<string_value>" ] ### Targets目標這個API是實驗性的，暫不翻譯。 ### Alertmanagers 這個API也是實驗性的，暫不翻譯