目前穩定的 HTTP API 可在 Prometheus 伺服器上的 /api/v1 下存取。任何非破壞性的新增內容都會新增至該端點下。
API 回應格式為 JSON。每個成功的 API 請求都會傳回 2xx 狀態碼。
到達 API 處理常式的無效請求會傳回 JSON 錯誤物件，以及下列 HTTP 回應碼之一
400 Bad Request，當參數遺失或不正確時。422 Unprocessable Entity，當無法執行表達式時 (RFC4918)。503 Service Unavailable，當查詢逾時或中止時。其他非 2xx 程式碼可能會針對到達 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>",
// Only set if there were warnings while executing the request.
// There will still be data in the data field.
"warnings": ["<string>"],
// Only set if there were info-level annnotations while executing the request.
"infos": ["<string>"]
}
通用預留位置定義如下
<rfc3339 | unix_timestamp>：輸入時間戳記可以 RFC3339 格式或以秒為單位的 Unix 時間戳記提供，並可選擇使用小數位數來表示次秒精確度。輸出時間戳記一律以秒為單位的 Unix 時間戳記表示。<series_selector>：Prometheus 時間序列選取器，例如 http_requests_total 或 http_requests_total{method=~"(GET|POST)"}，且需要進行 URL 編碼。<duration>：使用時間單位的 Prometheus 浮點常值子集。例如，5m 表示持續時間為 5 分鐘。<bool>：布林值 (字串 true 和 false)。注意：可能會重複的查詢參數名稱會以 [] 結尾。
查詢語言表達式可以在單一瞬間或一段時間範圍內評估。以下章節說明每個表達式查詢類型的 API 端點。
下列端點會在單一時間點評估即時查詢
GET /api/v1/query
POST /api/v1/query
URL 查詢參數
query=<string>：Prometheus 表達式查詢字串。time=<rfc3339 | unix_timestamp>：評估時間戳記。選填。timeout=<duration>：評估逾時。選填。預設為 -query.timeout 旗標的值，並受其上限約束。如果省略 time 參數，則會使用目前的伺服器時間。
您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 標頭，直接在請求本文中對這些參數進行 URL 編碼。當指定可能違反伺服器端 URL 字元限制的大型查詢時，這會很有用。
查詢結果的 data 區段具有下列格式
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
<value> 是指查詢結果資料，其格式會因 resultType 而異。請參閱表達式查詢結果格式。
以下範例會在時間 2015-07-01T20:10:51.781Z 評估表達式 up
$ curl 'https://127.0.0.1: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
POST /api/v1/query_range
URL 查詢參數
query=<string>：Prometheus 表達式查詢字串。start=<rfc3339 | unix_timestamp>：起始時間戳記，包含。end=<rfc3339 | unix_timestamp>：結束時間戳記，包含。step=<duration | float>：查詢解析度步幅，格式為 duration 或秒數的浮點數。timeout=<duration>：評估逾時。選填。預設為 -query.timeout 旗標的值，並受其上限約束。您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 標頭，直接在請求本文中對這些參數進行 URL 編碼。當指定可能違反伺服器端 URL 字元限制的大型查詢時，這會很有用。
查詢結果的 data 區段具有下列格式
{
"resultType": "matrix",
"result": <value>
}
如需 <value> 預留位置的格式，請參閱範圍向量結果格式。
下列範例會在 30 秒的範圍內評估表達式 up，查詢解析度為 15 秒。
$ curl 'https://127.0.0.1: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" ]
]
}
]
}
}
下列端點會以美化方式格式化 PromQL 表達式
GET /api/v1/format_query
POST /api/v1/format_query
URL 查詢參數
query=<string>：Prometheus 表達式查詢字串。您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 標頭，直接在請求本文中對這些參數進行 URL 編碼。當指定可能違反伺服器端 URL 字元限制的大型查詢時，這會很有用。
查詢結果的 data 區段是包含格式化查詢表達式的字串。請注意，格式化字串中會移除所有註解。
以下範例會格式化表達式 foo/bar
$ curl 'https://127.0.0.1:9090/api/v1/format_query?query=foo/bar'
{
"status" : "success",
"data" : "foo / bar"
}
此端點為實驗性，未來可能會變更。目前僅適用於 Prometheus 自己的 Web UI，且傳回的端點名稱和確切格式可能會因 Prometheus 版本而異。如果 UI 不再需要它，也可能會再次移除。
下列端點會剖析 PromQL 表達式，並將其以 JSON 格式的 AST (抽象語法樹) 表示法傳回
GET /api/v1/parse_query
POST /api/v1/parse_query
URL 查詢參數
query=<string>：Prometheus 表達式查詢字串。您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 標頭，直接在請求本文中對這些參數進行 URL 編碼。當指定可能違反伺服器端 URL 字元限制的大型查詢時，這會很有用。
查詢結果的 data 區段是包含剖析查詢表達式的 AST 的字串。
以下範例會剖析表達式 foo/bar
$ curl 'https://127.0.0.1:9090/api/v1/parse_query?query=foo/bar'
{
"data" : {
"bool" : false,
"lhs" : {
"matchers" : [
{
"name" : "__name__",
"type" : "=",
"value" : "foo"
}
],
"name" : "foo",
"offset" : 0,
"startOrEnd" : null,
"timestamp" : null,
"type" : "vectorSelector"
},
"matching" : {
"card" : "one-to-one",
"include" : [],
"labels" : [],
"on" : false
},
"op" : "/",
"rhs" : {
"matchers" : [
{
"name" : "__name__",
"type" : "=",
"value" : "bar"
}
],
"name" : "bar",
"offset" : 0,
"startOrEnd" : null,
"timestamp" : null,
"type" : "vectorSelector"
},
"type" : "binaryExpr"
},
"status" : "success"
}
Prometheus 提供一組 API 端點來查詢有關序列及其標籤的中繼資料。
下列端點會傳回符合特定標籤集的時間序列清單。
GET /api/v1/series
POST /api/v1/series
URL 查詢參數
match[]=<series_selector>：重複的序列選取器引數，會選取要傳回的序列。必須至少提供一個 match[] 引數。start=<rfc3339 | unix_timestamp>：起始時間戳記。end=<rfc3339 | unix_timestamp>：結束時間戳記。limit=<number>：傳回的最大序列數。選填。0 表示已停用。您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 標頭，直接在請求本文中對這些參數進行 URL 編碼。當指定可能違反伺服器端 URL 字元限制的大型或動態序列選取器數目時，這會很有用。
查詢結果的 data 區段包含物件清單，其中包含可識別每個序列的標籤名稱/值組。
以下範例會傳回所有符合選擇器 up 或 process_start_time_seconds{job="prometheus"} 的序列。
$ curl -g 'https://127.0.0.1:9090/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode '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/labels
POST /api/v1/labels
URL 查詢參數
start=<rfc3339 | unix_timestamp>：開始時間戳記。選用。end=<rfc3339 | unix_timestamp>：結束時間戳記。選用。match[]=<series_selector>：重複的序列選擇器引數，用於選取要從中讀取標籤名稱的序列。選用。limit=<number>：傳回的最大序列數。選填。0 表示已停用。JSON 回應的 data 區段是一個字串標籤名稱的清單。
以下是一個範例。
$ curl 'localhost:9090/api/v1/labels'
{
"status": "success",
"data": [
"__name__",
"call",
"code",
"config",
"dialer_name",
"endpoint",
"event",
"goversion",
"handler",
"instance",
"interval",
"job",
"le",
"listener_name",
"name",
"quantile",
"reason",
"role",
"scrape_job",
"slice",
"version"
]
}
以下端點會傳回所提供標籤名稱的標籤值清單
GET /api/v1/label/<label_name>/values
URL 查詢參數
start=<rfc3339 | unix_timestamp>：開始時間戳記。選用。end=<rfc3339 | unix_timestamp>：結束時間戳記。選用。match[]=<series_selector>：重複的序列選擇器引數，用於選取要從中讀取標籤值的序列。選用。limit=<number>：傳回的最大序列數。選填。0 表示已停用。JSON 回應的 data 區段是一個字串標籤值的清單。
此範例會查詢 http_status_code 標籤的所有標籤值
$ curl https://127.0.0.1:9090/api/v1/label/http_status_code/values
{
"status" : "success",
"data" : [
"200",
"504"
]
}
標籤名稱可以選擇使用值逸出方法進行編碼，如果名稱包含 / 字元，則必須進行編碼。若要以這種方式編碼名稱
U__。_20_，而 . 會變成 _2e_。有關文字逸出的詳細資訊，請參閱原始的 UTF-8 提案文件。
此範例會查詢 http.status_code 標籤的所有標籤值
$ curl https://127.0.0.1:9090/api/v1/label/U__http_2e_status_code/values
{
"status" : "success",
"data" : [
"200",
"404"
]
}
這是一個實驗性功能，未來可能會變更。以下端點會傳回特定時間範圍內有效 PromQL 查詢的範例清單
GET /api/v1/query_exemplars
POST /api/v1/query_exemplars
URL 查詢參數
query=<string>：Prometheus 表達式查詢字串。start=<rfc3339 | unix_timestamp>：起始時間戳記。end=<rfc3339 | unix_timestamp>：結束時間戳記。$ curl -g 'https://127.0.0.1:9090/api/v1/query_exemplars?query=test_exemplar_metric_total&start=2020-09-14T15:22:25.479Z&end=2020-09-14T15:23:25.479Z'
{
"status": "success",
"data": [
{
"seriesLabels": {
"__name__": "test_exemplar_metric_total",
"instance": "localhost:8090",
"job": "prometheus",
"service": "bar"
},
"exemplars": [
{
"labels": {
"trace_id": "EpTxMJ40fUus7aGY"
},
"value": "6",
"timestamp": 1600096945.479
}
]
},
{
"seriesLabels": {
"__name__": "test_exemplar_metric_total",
"instance": "localhost:8090",
"job": "prometheus",
"service": "foo"
},
"exemplars": [
{
"labels": {
"trace_id": "Olp9XHlq763ccsfa"
},
"value": "19",
"timestamp": 1600096955.479
},
{
"labels": {
"trace_id": "hCtjygkIHwAN9vs4"
},
"value": "20",
"timestamp": 1600096965.489
}
]
}
]
}
表達式查詢可能會在 data 區段的 result 屬性中傳回以下回應值。<sample_value> 佔位符是數值樣本值。JSON 不支援特殊的浮點值，例如 NaN、Inf 和 -Inf，因此樣本值會以引號括住的 JSON 字串而非原始數字傳輸。
只有當回應中存在實驗性的原生直方圖時，才會顯示索引鍵 "histogram" 和 "histograms"。其佔位符 <histogram> 在下面的單獨章節中詳細說明。
範圍向量會以結果類型 matrix 傳回。對應的 result 屬性具有以下格式
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ],
"histograms": [ [ <unix_time>, <histogram> ], ... ]
},
...
]
每個序列都可能會有 "values" 索引鍵，或 "histograms" 索引鍵，或兩者都有。對於給定的時間戳記，只會有一個浮點數或直方圖類型的樣本。
序列會按 metric 排序後傳回。諸如 sort 和 sort_by_label 等函數對範圍向量沒有任何作用。
即時向量會以結果類型 vector 傳回。對應的 result 屬性具有以下格式
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ],
"histogram": [ <unix_time>, <histogram> ]
},
...
]
每個序列都可能會有 "value" 索引鍵，或 "histogram" 索引鍵，但不會同時有兩者。
除非使用 sort 或 sort_by_label 等函數，否則無法保證序列會以任何特定順序傳回。
純量結果會以結果類型 scalar 傳回。對應的 result 屬性具有以下格式
[ <unix_time>, "<scalar_value>" ]
字串結果會以結果類型 string 傳回。對應的 result 屬性具有以下格式
[ <unix_time>, "<string_value>" ]
上面使用的 <histogram> 佔位符格式如下。
請注意，原生直方圖是一項實驗性功能，下方的格式可能仍會變更。
{
"count": "<count_of_observations>",
"sum": "<sum_of_observations>",
"buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
}
<boundary_rule> 佔位符是一個介於 0 和 3 之間的整數，含義如下
請注意，對於目前實作的儲存桶結構描述，正儲存桶是「左開」，負儲存桶是「右開」，而零儲存桶 (具有負左邊界和正右邊界) 是「兩邊閉」。
以下端點會傳回 Prometheus 目標探索目前狀態的概觀
GET /api/v1/targets
預設情況下，回應中會包含作用中和已捨棄的目標。已捨棄的目標受限於 keep_dropped_targets 限制 (如果已設定)。labels 代表重新標籤後出現的標籤集。discoveredLabels 代表在重新標籤之前，於服務探索期間擷取的未修改標籤。
$ curl https://127.0.0.1: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",
"globalUrl": "http://example-prometheus:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 0.050688943,
"health": "up",
"scrapeInterval": "1m",
"scrapeTimeout": "10s"
}
],
"droppedTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9100",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"__scrape_interval__": "1m",
"__scrape_timeout__": "10s",
"job": "node"
},
}
]
}
}
呼叫者可以使用 state 查詢參數，依作用中或已捨棄的目標進行篩選 (例如，state=active、state=dropped、state=any)。請注意，對於已篩選掉的目標，仍會傳回一個空陣列。系統會忽略其他值。
$ curl 'https://127.0.0.1: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",
"globalUrl": "http://example-prometheus:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 50688943,
"health": "up"
}
],
"droppedTargets": []
}
}
呼叫者可以使用 scrapePool 查詢參數，依抓取集區名稱進行篩選。
$ curl 'https://127.0.0.1:9090/api/v1/targets?scrapePool=node_exporter'
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9091",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "node_exporter"
},
"labels": {
"instance": "127.0.0.1:9091",
"job": "node_exporter"
},
"scrapePool": "node_exporter",
"scrapeUrl": "http://127.0.0.1:9091/metrics",
"globalUrl": "http://example-prometheus:9091/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 50688943,
"health": "up"
}
],
"droppedTargets": []
}
}
/rules API 端點會傳回目前已載入的警示和記錄規則清單。此外，它還會傳回每個警示規則的 Prometheus 執行個體目前觸發的作用中警示。
由於 /rules 端點相當新，因此它不具有與整個 API v1 相同的穩定性保證。
GET /api/v1/rules
URL 查詢參數
type=alert|record：僅傳回警示規則 (例如 type=alert) 或記錄規則 (例如 type=record)。當參數不存在或為空時，不會進行篩選。rule_name[]=<string>：僅傳回具有指定規則名稱的規則。如果重複參數，則會傳回具有任何指定名稱的規則。如果我們篩選掉群組的所有規則，則不會傳回該群組。當參數不存在或為空時，不會進行篩選。rule_group[]=<string>：僅傳回具有指定規則群組名稱的規則。如果重複參數，則會傳回具有任何指定規則群組名稱的規則。當參數不存在或為空時，不會進行篩選。file[]=<string>：僅傳回具有指定檔案路徑的規則。如果重複參數，則會傳回具有任何指定檔案路徑的規則。當參數不存在或為空時，不會進行篩選。exclude_alerts=<bool>：僅傳回規則，不傳回作用中警示。match[]=<label_selector>：僅傳回已設定滿足標籤選擇器的標籤的規則。如果重複參數，則會傳回符合任何標籤選擇器集的規則。請注意，比對的是每個規則定義中的標籤，而不是樣板展開後的值 (對於警示規則)。選用。group_limit=<number>：group_limit 參數可讓您指定單一回應中傳回的規則群組數目上限。如果規則群組總數超過指定的 group_limit 值，則回應將包含 groupNextToken 屬性。您可以在後續請求中使用此 groupNextToken 屬性的值在 group_next_token 參數中，以對其餘的規則群組進行分頁。groupNextToken 屬性不會出現在最終回應中，表示您已擷取所有可用的規則群組。請注意，如果規則群組在分頁處理期間遭到修改，則無法保證回應的一致性。group_next_token：當設定 group_limit 屬性時，在先前請求中傳回的分頁符記。分頁符記用於反覆對大量規則群組進行分頁。若要使用 group_next_token 參數，也需要存在 group_limit 參數。如果您在對規則群組進行分頁時移除與下一個符記一致的規則群組，則會傳回狀態碼 400 的回應。$ curl https://127.0.0.1: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": "1e+00"
}
],
"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 by (job) (http_inprogress_requests)",
"type": "recording"
}
],
"file": "/rules.yaml",
"interval": 60,
"limit": 0,
"name": "example"
}
]
},
"status": "success"
}
/alerts 端點會傳回所有作用中警示的清單。
由於 /alerts 端點相當新，因此它不具有與整個 API v1 相同的穩定性保證。
GET /api/v1/alerts
$ curl https://127.0.0.1:9090/api/v1/alerts
{
"data": {
"alerts": [
{
"activeAt": "2018-07-04T20:27:12.60602144+02:00",
"annotations": {},
"labels": {
"alertname": "my-alert"
},
"state": "firing",
"value": "1e+00"
}
]
},
"status": "success"
}
以下端點會傳回目前從目標抓取的度量中繼資料。這是一個實驗性功能，未來可能會變更。
GET /api/v1/targets/metadata
URL 查詢參數
match_target=<label_selectors>：依其標籤集比對目標的標籤選擇器。如果留空，則會選取所有目標。metric=<string>：要擷取中繼資料的度量名稱。如果留空，則會擷取所有度量中繼資料。limit=<number>：要比對的最大目標數目。查詢結果的 data 區段包含物件的清單，其中包含度量中繼資料和目標標籤集。
以下範例會傳回具有標籤 job="prometheus" 的前兩個目標中 go_goroutines 度量的所有中繼資料項目。
curl -G https://127.0.0.1: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 https://127.0.0.1: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": ""
},
// ...
]
}
它會傳回目前從目標抓取的度量中繼資料。但是，它不會提供任何目標資訊。這被視為實驗性功能，未來可能會變更。
GET /api/v1/metadata
URL 查詢參數
limit=<number>：要傳回的最大度量數目。limit_per_metric=<number>：每個度量要傳回的最大中繼資料數目。metric=<string>：用來篩選中繼資料的度量名稱。如果留空，則會擷取所有度量中繼資料。查詢結果的 data 區段包含一個物件，其中每個索引鍵都是一個度量名稱，而每個值都是唯一中繼資料物件的清單，如所有目標的該度量名稱所公開。
以下範例會傳回兩個度量。請注意，度量 http_requests_total 在清單中有一個以上的物件。至少有一個目標的 HELP 值與其餘的值不符。
curl -G https://127.0.0.1:9090/api/v1/metadata?limit=2
{
"status": "success",
"data": {
"cortex_ring_tokens": [
{
"type": "gauge",
"help": "Number of tokens in the ring",
"unit": ""
}
],
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
},
{
"type": "counter",
"help": "Amount of HTTP requests",
"unit": ""
}
]
}
}
以下範例只會傳回每個度量的一個中繼資料項目。
curl -G https://127.0.0.1:9090/api/v1/metadata?limit_per_metric=1
{
"status": "success",
"data": {
"cortex_ring_tokens": [
{
"type": "gauge",
"help": "Number of tokens in the ring",
"unit": ""
}
],
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
}
]
}
}
以下範例僅針對指標 http_requests_total 回傳中繼資料。
curl -G https://127.0.0.1:9090/api/v1/metadata?metric=http_requests_total
{
"status": "success",
"data": {
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
},
{
"type": "counter",
"help": "Amount of HTTP requests",
"unit": ""
}
]
}
}
以下端點會回傳 Prometheus Alertmanager 探索的目前狀態概觀。
GET /api/v1/alertmanagers
作用中和已捨棄的 Alertmanagers 都會包含在回應中。
$ curl https://127.0.0.1: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"
}
]
}
}
以下狀態端點會公開目前的 Prometheus 組態。
以下端點會回傳目前載入的組態檔。
GET /api/v1/status/config
組態會以傾印的 YAML 檔案形式回傳。由於 YAML 程式庫的限制，YAML 註解不會包含在內。
$ curl https://127.0.0.1:9090/api/v1/status/config
{
"status": "success",
"data": {
"yaml": "<content of the loaded config file in YAML>",
}
}
以下端點會回傳 Prometheus 組態使用的旗標值。
GET /api/v1/status/flags
所有值都是 string 的結果類型。
$ curl https://127.0.0.1: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 新增
以下端點會回傳關於 Prometheus 伺服器的各種執行階段資訊屬性。
GET /api/v1/status/runtimeinfo
回傳的值會根據執行階段屬性的性質而有不同的類型。
$ curl https://127.0.0.1:9090/api/v1/status/runtimeinfo
{
"status": "success",
"data": {
"startTime": "2019-11-02T17:23:59.301361365+01:00",
"CWD": "/",
"reloadConfigSuccess": true,
"lastConfigTime": "2019-11-02T17:23:59+01:00",
"timeSeriesCount": 873,
"corruptionCount": 0,
"goroutineCount": 48,
"GOMAXPROCS": 4,
"GOGC": "",
"GODEBUG": "",
"storageRetention": "15d"
}
}
v2.14 新增
以下端點會回傳關於 Prometheus 伺服器的各種建置資訊屬性。
GET /api/v1/status/buildinfo
所有值都是 string 的結果類型。
$ curl https://127.0.0.1:9090/api/v1/status/buildinfo
{
"status": "success",
"data": {
"version": "2.13.1",
"revision": "cb7cbad5f9a2823a622aaa668833ca04f50a0ea7",
"branch": "master",
"buildUser": "julius@desktop",
"buildDate": "20191102-16:19:59",
"goVersion": "go1.13.1"
}
}
v2.14 新增
以下端點會回傳關於 Prometheus TSDB 的各種基數統計資料。
GET /api/v1/status/tsdb
URL 查詢參數
limit=<數字>：將每個統計資料集的已回傳項目數限制為指定的數字。預設會回傳 10 個項目。查詢結果的 data 區段包含：
$ curl https://127.0.0.1:9090/api/v1/status/tsdb
{
"status": "success",
"data": {
"headStats": {
"numSeries": 508,
"chunkCount": 937,
"minTime": 1591516800000,
"maxTime": 1598896800143,
},
"seriesCountByMetricName": [
{
"name": "net_conntrack_dialer_conn_failed_total",
"value": 20
},
{
"name": "prometheus_http_request_duration_seconds_bucket",
"value": 20
}
],
"labelValueCountByLabelName": [
{
"name": "__name__",
"value": 211
},
{
"name": "event",
"value": 3
}
],
"memoryInBytesByLabelName": [
{
"name": "__name__",
"value": 8266
},
{
"name": "instance",
"value": 28
}
],
"seriesCountByLabelValuePair": [
{
"name": "job=prometheus",
"value": 425
},
{
"name": "instance=localhost:9090",
"value": 425
}
]
}
}
v2.15 新增
以下端點會回傳關於 WAL 重播的資訊。
GET /api/v1/status/walreplay
$ curl https://127.0.0.1:9090/api/v1/status/walreplay
{
"status": "success",
"data": {
"min": 2,
"max": 5,
"current": 40,
"state": "in progress"
}
}
v2.28 新增
這些是為進階使用者公開資料庫功能的 API。除非設定了 --web.enable-admin-api，否則不會啟用這些 API。
快照會在 TSDB 資料目錄下的 snapshots/<datetime>-<rand> 中建立所有目前資料的快照，並將目錄做為回應回傳。它會選擇性地略過僅存在於頭區塊且尚未壓縮到磁碟的快照資料。
POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot
URL 查詢參數
skip_head=<bool>：略過頭區塊中存在的資料。可選。$ curl -XPOST https://127.0.0.1:9090/api/v1/admin/tsdb/snapshot
{
"status": "success",
"data": {
"name": "20171210T211224Z-2be650b6d019eb54"
}
}
快照現在位於 <data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54。
v2.1 新增，且從 v2.9 起支援 PUT
DeleteSeries 會刪除時間範圍內所選系列的資料。實際資料仍然存在磁碟上，並會在未來的壓縮中清除，或是可以透過點擊清除墓碑端點來明確清除。
如果成功，會回傳 204。
POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series
URL 查詢參數
match[]=<series_selector>：重複的標籤比對器引數，用於選取要刪除的系列。必須提供至少一個 match[] 引數。start=<rfc3339 | unix_timestamp>：起始時間戳記。可選，預設為可能的最短時間。end=<rfc3339 | unix_timestamp>：結束時間戳記。可選，預設為可能的最長時間。若未提及開始和結束時間，則會清除資料庫中相符系列的所有資料。
範例
$ curl -X POST \
-g 'https://127.0.0.1:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
v2.1 新增，且從 v2.9 起支援 PUT
CleanTombstones 會從磁碟中移除已刪除的資料，並清除現有的墓碑。這可以在刪除系列後用於釋放空間。
如果成功，會回傳 204。
POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones
這不需要任何參數或主體。
$ curl -XPOST https://127.0.0.1:9090/api/v1/admin/tsdb/clean_tombstones
v2.1 新增，且從 v2.9 起支援 PUT
Prometheus 可以設定為 Prometheus 遠端寫入協定的接收器。這不被認為是擷取範例的有效方式。請謹慎用於特定的低量使用案例。它不適合取代透過抓取進行的擷取，並將 Prometheus 變成基於推送的指標收集系統。
透過設定 --web.enable-remote-write-receiver 來啟用遠端寫入接收器。啟用後，遠端寫入接收器端點為 /api/v1/write。請在此處找到更多詳細資訊。
v2.33 新增
Prometheus 可以設定為 OTLP 指標協定的接收器。這不被認為是擷取範例的有效方式。請謹慎用於特定的低量使用案例。它不適合取代透過抓取進行的擷取。
透過設定 --web.enable-otlp-receiver 來啟用 OTLP 接收器。啟用後，OTLP 接收器端點為 /api/v1/otlp/v1/metrics。
v2.47 新增
以下端點提供關於與 Prometheus 伺服器本身相關的作用中狀態通知的資訊。通知會在 Web UI 中使用。
這些端點為實驗性。它們未來可能會變更。
/api/v1/notifications 端點會回傳所有目前作用中通知的清單。
GET /api/v1/notifications
範例
$ curl https://127.0.0.1:9090/api/v1/notifications
{
"status": "success",
"data": [
{
"text": "Prometheus is shutting down and gracefully stopping all operations.",
"date": "2024-10-07T12:33:08.551376578+02:00",
"active": true
}
]
}
v3.0 新增
/api/v1/notifications/live 端點會使用伺服器傳送事件串流發生時的即時通知。已刪除的通知會隨 active: false 一起傳送。當連線到端點時，將會傳送作用中的通知。
GET /api/v1/notifications/live
範例
$ curl https://127.0.0.1:9090/api/v1/notifications/live
data: {
"status": "success",
"data": [
{
"text": "Prometheus is shutting down and gracefully stopping all operations.",
"date": "2024-10-07T12:33:08.551376578+02:00",
"active": true
}
]
}
注意：如果已達到訂閱者最大數量，則 /notifications/live 端點會回傳 204 No Content 回應。您可以使用旗標 --web.max-notifications-subscribers 設定接聽者的最大數量，預設值為 16。
GET /api/v1/notifications/live
204 No Content
v3.0 新增
此文件為開放原始碼。請協助透過提交問題或提取要求來改善它。