- 一、格式概述
- 二、表示式查詢
- 2.1 Instant queries(即時查詢)
- 2.2 範圍查詢
- 三、查詢後設資料
- 3.1 通過標籤匹配器找到度量指標列表
- 3.2 獲取標籤名
- 3.3 查詢標籤值
- 四、表示式查詢結果格式
- 4.1 範圍向量
- 4.2 瞬時向量
- 4.3 標量
- 4.4 字串
- 五、Targets目標
- 六、Rules規則
- 七、Alerts報警
- 八、查詢目標後設資料
- 九、Altermanagers警報管理器
- 十、Status狀態
- 10.1 Config配置
- 10.2 Flags標誌
- 十一、TSDB Admin APIs，TSDB管理API
- 11.1 快照
- 11.2 刪除序列
- 11.3 CleanTombstones
在Prometheus伺服器上的/api/v1下可以訪問當前穩定的HTTP API。 將在該端點下新增任何非中斷新增項。
一、格式概述
這個API返回是JSON格式。每個請求成功的返回值都是以2xx開頭的編碼。
到達API處理的無效請求，返回一個JSON錯誤物件，並返回下面的錯誤碼：
400 Bad Request。當引數錯誤或者丟失時。422 Unprocessable Entity。當一個表示式不能被執行時。503 Service Unavailable。當查詢超時或者中斷時。
對於在到達API端點之前發生的錯誤，可以返回其他非2xx程式碼。
如果存在不阻止請求執行的錯誤，則可以返回警告陣列。 成功收集的所有資料都將在資料欄位中返回。
JSON響應格式如下：
{
"status": "success" | "error",
"data": <data>,
// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "<string>",
"error": "<string>",
// Only if there were warnings while executing the request.
// There will still be data in the data field.
"warnings": ["<string>"]
}
|
輸入時間戳可以以RFC3339格式提供，也可以以秒為單位提供給Unix時間戳，可選的小數位數用於亞秒級精度。 輸出時間戳始終表示為Unix時間戳，以秒為單位。
可以以[]結尾查詢引數的名稱。
<series_selector>佔位符指的是Prometheus時間序列選擇器，如http_requests_total或http_requests_total{method =〜"(GET|POST)"}，需要進行URL編碼。
<duration>佔位符指的是[0-9]+[smhdwy]形式的Prometheus持續時間字串。 例如，5m指的是5分鐘的持續時間。
<bool>佔位符引用布林值（字串true和false）。
二、表示式查詢
可以對指標或指標聚合表示式在某一時刻或者某一段時間進行查詢操作，詳細解釋見下：
2.1 Instant queries(即時查詢)
以下端點在單個時間點評估即時查詢：
GET /api/v1/query |
URL查詢引數：
query=<string>: Prometheus表示式查詢字串。time=<rfc3339 | uninx_timestamp>: 執行時間戳，可選項。timeout=<duration>: 執行超時時間設定，可選項，預設由-query.timeout標誌設定
如果time預設，則用當前伺服器時間表示執行時刻。
這個查詢結果的data部分有下面格式：
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
|
<value> 是一個查詢結果資料，依賴於這個resultType格式,見表示式查詢結果格式> 。
下面例子執行了在時刻是2015-07-01T20:10:51.781Z的up表示式：
$ curl 'http://localhost:9090/api/v1/query?query=up&time=2020-03-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" ]
}
]
}
}
|
2.2 範圍查詢
以下端點在一段時間內評估表示式查詢：
GET /api/v1/query_range |
URL查詢引數
query=<string>: Prometheus表示式查詢字串。start=<rfc3339 | unix_timestamp>: 開始時間戳。end=<rfc3339 | unix_timestamp>: 結束時間戳。step=<duration>: 以持續時間格式查詢解析度步長或浮點秒數。timeout=<duration>:評估超時。 可選的。 預設為-query.timeout標誌的值並受其限制。
查詢結果的資料部分具有以下格式：
{
"resultType": "matrix",
"result": <value>
}
|
對於<value>佔位符的格式，詳見第四章節部分。
以下示例在30秒範圍內評估表示式，查詢解析度為15秒。
$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2020-03-01T20:10:30.781Z&end=2020-03-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" ]
]
}
]
}
}
|
三、查詢後設資料
3.1 通過標籤匹配器找到度量指標列表
以下端點返回與特定標籤集匹配的時間系列列表。
GET /api/v1/series POST /api/v1/series |
URL查詢引數：
match[]=<series_selector>: 選擇器是series_selector。這個引數個數必須大於等於1.start=<rfc3339 | unix_timestamp>: 開始時間戳。end=<rfc3339 | unix_timestamp>: 結束時間戳。
查詢結果的data部分包含一個物件列表，這些物件包含標識每個系列的標籤名稱/值對。
下面這個例子返回時間序列資料, 選擇器是up或者process_start_time_seconds{job="prometheus"}
$ curl -g 'http://localhost:9090/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode 'match[]=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"
}
]
}
|
3.2 獲取標籤名
以下端點返回標籤名稱列表：
GET /api/v1/labels POST /api/v1/labels
JSON響應的data部分是字串標籤名稱的列表。
如下例子：
[mingming.chen@m162p84 ~]$ curl 'localhost:9095/api/v1/labels' | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 517 100 517 0 0 48782 0 --:--:-- --:--:-- --:--:-- 64625
{
"data": [
"__name__",
"alertname",
"alertstate",
"api_group",
"branch",
"bucket_capacity",
"build_date",
"build_version",
"result",
"revision",
"rulesName",
"schema",
"sd_env",
"sd_service",
"sd_zone",
"segment_type",
"service",
"service_name",
"severity",
"shard",
"source",
"type"
],
"status": "success"
}
|
3.3 查詢標籤值
以下端點返回提供的標籤名稱的標籤值列表：
GET /api/v1/label/<label_name>/values
JSON響應的data部分是字串標籤值的列表。
此示例查詢作業標籤的所有標籤值：
[mingming.chen@m162p84 ~]$ curl http://localhost:9095/api/v1/label/job/values | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 63 100 63 0 0 6990 0 --:--:-- --:--:-- --:--:-- 9000
{
"data": [
"federate",
"m3coordinator",
"m3db"
],
"status": "success"
}
|
四、表示式查詢結果格式
表示式查詢可能會在data部分的result屬性中返回以下響應值。 <sample_value>佔位符是數字樣本值。 JSON不支援特殊的浮點值，例如NaN，Inf和-Inf，因此樣本值將作為帶引號的JSON字串而不是原始數字傳輸。
4.1 範圍向量
範圍向量返回的result型別是一個matrix矩陣。下面返回的結果是result部分的資料格式：
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ]
},
...
]
|
4.2 瞬時向量
瞬時向量的result型別是vector。下面是result部分的資料格式
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ]
},
...
]
|
4.3 標量
標量查詢返回result型別是scalar。下面是result部分的資料格式：
[ <unix_time>, "<scalar_value>" ]
4.4 字串
字串的result型別是string。下面是result部分的資料格式：
[ <unix_time>, "<string_value>" ]
五、Targets目標
以下端點返回Prometheus目標發現的當前狀態概述：
GET /api/v1/targets |
活動目標和刪除目標都是響應的一部分。 labels表示重新標記發生後的標籤集。 discoveredLabels表示在發生重新標記之前在服務發現期間檢索到的未修改標籤。
$ curl http://localhost:9090/api/v1/targets
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9090",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "prometheus"
},
"labels": {
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
"scrapePool": "prometheus",
"scrapeUrl": "http://127.0.0.1:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 0.050688943,
"health": "up"
}
],
"droppedTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9100",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "node"
},
}
]
}
}
|
狀態查詢引數允許呼叫者按活動或已刪除的目標進行過濾（例如，state=active, state=dropped, state=any）。 請注意，對於已濾除的目標，仍然返回空陣列。 其他值將被忽略。
$ curl 'http://localhost:9090/api/v1/targets?state=active'
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9090",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "prometheus"
},
"labels": {
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
"scrapePool": "prometheus",
"scrapeUrl": "http://127.0.0.1:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 50688943,
"health": "up"
}
],
"droppedTargets": []
}
}
|
六、Rules規則
/rules API端點返回當前載入的警報和記錄規則列表。 此外，它還返回由每個警報規則的Prometheus例項觸發的當前活動警報。
由於/rules端點相當新，它沒有與總體API v1相同的穩定性保證。
GET /api/v1/rules
$ curl http://localhost:9090/api/v1/rules
{
"data": {
"groups": [
{
"rules": [
{
"alerts": [
{
"activeAt": "2018-07-04T20:27:12.60602144+02:00",
"annotations": {
"summary": "High request latency"
},
"labels": {
"alertname": "HighRequestLatency",
"severity": "page"
},
"state": "firing",
"value": 1
}
],
"annotations": {
"summary": "High request latency"
},
"duration": 600,
"health": "ok",
"labels": {
"severity": "page"
},
"name": "HighRequestLatency",
"query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
"type": "alerting"
},
{
"health": "ok",
"name": "job:http_inprogress_requests:sum",
"query": "sum(http_inprogress_requests) by (job)",
"type": "recording"
}
],
"file": "/rules.yaml",
"interval": 60,
"name": "example"
}
]
},
"status": "success"
}
|
七、Alerts報警
/alerts端點返回所有活動警報的列表。
由於/alerts端點相當新，它沒有與總體API v1相同的穩定性保證。
GET /api/v1/alerts
$ curl http://localhost:9090/api/v1/alerts
{
"data": {
"alerts": [
{
"activeAt": "2018-07-04T20:27:12.60602144+02:00",
"annotations": {},
"labels": {
"alertname": "my-alert"
},
"state": "firing",
"value": 1
}
]
},
"status": "success"
}
|
八、查詢目標後設資料
以下端點返回有關目標正在刮取的度量標準的後設資料。 這是實驗性的，將來可能會發生變化。
GET /api/v1/targets/metadata
URL查詢引數：
match_target=<label_selectors>：通過標籤集匹配目標的標籤選擇器。 如果留空則選擇所有目標。metric=<string>：用於檢索後設資料的度量標準名稱。 如果留空，則檢索所有度量標準後設資料。limit=<number>：要匹配的最大目標數。
查詢結果的data部分包含一個包含度量後設資料和目標標籤集的物件列表。
以下示例從前兩個目標返回go_goroutines指標的所有後設資料條目，標籤為job ="prometheus"。
curl -G http://localhost:9091/api/v1/targets/metadata \
--data-urlencode 'metric=go_goroutines' \
--data-urlencode 'match_target={job="prometheus"}' \
--data-urlencode 'limit=2'
{
"status": "success",
"data": [
{
"target": {
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
"type": "gauge",
"help": "Number of goroutines that currently exist.",
"unit": ""
},
{
"target": {
"instance": "127.0.0.1:9091",
"job": "prometheus"
},
"type": "gauge",
"help": "Number of goroutines that currently exist.",
"unit": ""
}
]
}
|
以下示例返回標籤instance="127.0.0.1:9090"的所有目標的所有度量標準的後設資料。
curl -G http://localhost:9091/api/v1/targets/metadata \
--data-urlencode 'match_target={instance="127.0.0.1:9090"}'
{
"status": "success",
"data": [
// ...
{
"target": {
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
"metric": "prometheus_treecache_zookeeper_failures_total",
"type": "counter",
"help": "The total number of ZooKeeper failures.",
"unit": ""
},
{
"target": {
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
"metric": "prometheus_tsdb_reloads_total",
"type": "counter",
"help": "Number of times the database reloaded block data from disk.",
"unit": ""
},
// ...
]
}
|
九、Altermanagers警報管理器
以下端點返回Prometheus alertmanager發現的當前狀態概述：
GET /api/v1/alertmanagers
活動和丟棄的Alertmanagers都是響應的一部分。
$ curl http://localhost:9090/api/v1/alertmanagers
{
"status": "success",
"data": {
"activeAlertmanagers": [
{
"url": "http://127.0.0.1:9090/api/v1/alerts"
}
],
"droppedAlertmanagers": [
{
"url": "http://127.0.0.1:9093/api/v1/alerts"
}
]
}
}
|
十、Status狀態
以下狀態端點顯示當前的Prometheus配置。
10.1 Config配置
以下端點返回當前載入的配置檔案：
GET /api/v1/status/config
配置作為轉儲的YAML檔案返回。 由於YAML庫的限制，不包括YAML註釋。
$ curl http://localhost:9090/api/v1/status/config
{
"status": "success",
"data": {
"yaml": "<content of the loaded config file in YAML>",
}
}
|
10.2 Flags標誌
以下端點返回Prometheus配置的標誌值：
GET /api/v1/status/flags
所有值都以“字串”的形式出現。
$ curl http://localhost:9090/api/v1/status/flags
{
"status": "success",
"data": {
"alertmanager.notification-queue-capacity": "10000",
"alertmanager.timeout": "10s",
"log.level": "info",
"query.lookback-delta": "5m",
"query.max-concurrency": "20",
...
}
}
|
v2.2中的新內容。
十一、TSDB Admin APIs，TSDB管理API
這些是為高階使用者公開資料庫功能的API。 除非設定了--web.enable-admin-api，否則不會啟用這些API。
我們還公開了一個gRPC API，其定義可以在這裡找到。 這是實驗性的，將來可能會發生變化。
11.1 快照
快照會將所有當前資料的快照建立到TSDB資料目錄下的snapshots/<datetime>-<rand>中，並將該目錄作為響應返回。 它可以選擇跳過僅存在於頭塊中但尚未壓縮到磁碟的快照資料。
POST /api/v1/admin/tsdb/snapshot?skip_head=
$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
"status": "success",
"data": {
"name": "20171210T211224Z-2be650b6d019eb54"
}
}
|
快照已存在<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54 v2.1新內容。
11.2 刪除序列
DeleteSeries刪除時間範圍內所選系列的資料。 實際資料仍然存在於磁碟上，並在將來的壓縮中清除，或者可以通過Clean Tombstones端點來明確清理。
如果成功，則返回204。
POST /api/v1/admin/tsdb/delete_series
URL查詢引數：
match[]=<series_selector>：選擇要刪除的系列的重複標籤匹配器引數。 必須至少提供一個match[]引數。start= <rfc3339 | unix_timestamp>：開始時間戳。 可選，預設為最短可能時間。end= <rfc3339 | unix_timestamp>：結束時間戳。 可選，預設為最長可能時間。
不提及開始和結束時間將清除資料庫中匹配系列的所有資料。
例：
$ curl -X POST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
|
11.3 CleanTombstones
CleanTombstones從磁碟中刪除已刪除的資料並清理現有的邏輯刪除。 這可以在刪除系列後使用以釋放空間。
如果成功，則返回204。
POST /api/v1/admin/tsdb/clean_tombstones
這不需要引數或正文。
$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones