HTTP API

當前穩定的 HTTP API 可以透過 Prometheus 伺服器上的 /api/v1 訪問。任何非破壞性的新增內容都將新增在該端點下。

OpenAPI 規範

HTTP API 的 OpenAPI 規範可在 /api/v1/openapi.yaml 獲取。預設情況下，為了獲得更廣泛的相容性，它返回 OpenAPI 3.1。使用 ?openapi_version=3.2 可獲取 OpenAPI 3.2，其中包括高階功能和端點（如 /api/v1/notifications/live）。

這種機器可讀的規範描述了所有可用的端點、請求引數、響應格式和模式。

OpenAPI 規範可用於：

• 生成各種程式語言的客戶端庫。
• 驗證 API 請求和響應。
• 生成互動式 API 文件。
• 測試 API 端點。

格式概述

API 響應格式為 JSON。每個成功的 API 請求都返回 2xx 狀態碼。

到達 API 處理程式的無效請求將返回 JSON 錯誤物件以及以下 HTTP 響應碼之一：

• 400 Bad Request：當引數缺失或不正確時。
• 422 Unprocessable Entity：當無法執行表示式時（RFC4918 ）。
• 503 Service Unavailable：當查詢超時或中止時。

在到達 API 端點之前發生的錯誤可能會返回其他非 2xx 狀態碼。

如果存在不影響請求執行的錯誤，可能會返回一個警告陣列。對於可能是或可能不是誤報的潛在查詢問題，可能會額外返回一個資訊級註釋（info-level annotations）陣列。所有成功收集的資料都將在 data 欄位中返回。

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 annotations 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 標誌的值，且受其上限限制。
• limit=<number>：返回序列的最大數量。不影響標量或字串，但會截斷矩陣和向量的序列數。可選。0 表示停用。
• lookback_delta=<duration | float>：僅針對此查詢以 duration 格式或浮點秒數覆蓋回溯期（lookback period）。可選。
• stats=<string>：在響應中包含查詢統計資訊。如果設定為 all，則包含詳細的統計資訊（耗時和樣本計數）。可選。參見查詢統計資訊。

如果省略 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://: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 標誌的值，且受其上限限制。
• limit=<number>：返回序列的最大數量。可選。0 表示停用。
• lookback_delta=<duration | float>：僅針對此查詢以 duration 格式或浮點秒數覆蓋回溯期（lookback period）。可選。
• stats=<string>：在響應中包含查詢統計資訊。如果設定為 all，則包含詳細的統計資訊（耗時和樣本計數）。可選。參見查詢統計資訊。

您可以透過使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 請求頭直接在請求體中對這些引數進行 URL 編碼。在指定可能會超出伺服器端 URL 字元限制的大型查詢時，這非常有用。

查詢結果的 data 部分具有以下格式：

{
  "resultType": "matrix",
  "result": <value>
}

關於 <value> 佔位符的格式，請參見範圍向量結果格式。

以下示例在 30 秒的範圍內評估表示式 up，查詢解析度為 15 秒。

curl 'https://: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" ]
            ]
         }
      ]
   }
}

查詢統計資訊

當設定了 stats 引數（例如 stats=all）時，響應中的 data 會包含一個具有以下結構的 stats 物件：

• timings：查詢執行不同階段的持續時間（以秒為單位）（例如 evalTotalTime、execQueueTime）。
• 樣本（samples）:
  • totalQueryableSamples：在查詢期間載入的樣本總數。對於多步驟的範圍向量函式，每一步都會計算整個時間視窗。
  • totalQueryableSamplesPerStep：（僅在 stats=all 且啟用了每步統計時提供。）每步載入的樣本計數；語義與每步的 totalQueryableSamples 相同。
  • samplesRead：讀取（I/O）的樣本總數。對於範圍查詢中的範圍向量函式，每步僅計算新點；對於其他查詢，此值等於 totalQueryableSamples。
  • samplesReadPerStep：（僅在 stats=all 且啟用了每步統計時提供。）每步讀取的樣本數（範圍向量採用增量語義）。
  • peakSamples：評估期間記憶體中的樣本峰值數。

伺服器還公開了兩個 Prometheus 指標：prometheus_engine_query_samples_total（已載入的樣本數）和 prometheus_engine_query_samples_read_total（已讀取的樣本數）。有關 promql-per-step-stats 功能標誌的資訊，請參見每步統計。

格式化查詢表示式

以下端點以美化方式格式化 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://:9090/api/v1/format_query?query=foo/bar'

{
   "status" : "success",
   "data" : "foo / bar"
}

將 PromQL 表示式解析為抽象語法樹 (AST)

此端點是實驗性的，未來可能會發生變化。目前它僅供 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://: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 端點，用於查詢有關序列及其標籤的元資料。

注意這些 API 端點可能會返回在所選時間範圍內沒有樣本的序列元資料，和/或透過刪除 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 請求頭直接在請求體中對 these 引數進行 URL 編碼。在指定可能會超出伺服器端 URL 字元限制的大量或動態序列選擇器時，這非常有用。

查詢結果的 data 部分包含一系列物件，這些物件具有用於標識每個序列的標籤名稱/值對。請注意，start 和 end 時間是近似值，結果可能包含在給定時間間隔內沒有樣本的序列標籤值。

以下示例返回與選擇器 up 或 process_start_time_seconds{job="prometheus"} 匹配的所有序列：

curl -g 'https://: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 部分是一個字串標籤名稱列表。請注意，start 和 end 時間是近似值，結果可能包含在給定時間間隔內沒有樣本的序列標籤名稱。

下面是一個示例。

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 部分是一個字串標籤值列表。請注意，start 和 end 時間是近似值，結果可能包含在給定時間間隔內沒有樣本的序列標籤值。

此示例查詢 http_status_code 標籤的所有標籤值：

curl https://:9090/api/v1/label/http_status_code/values

{
   "status" : "success",
   "data" : [
      "200",
      "504"
   ]
}

標籤名稱可以選擇使用“值轉義”方法進行編碼，如果名稱包含 / 字元，則此步驟是必需的。以這種方式對名稱進行編碼：

• 在標籤前加上 U__。
• 字母、數字和冒號按原樣顯示。
• 將單個下劃線轉換為雙下劃線。
• 對於所有其他字元，使用其 UTF-8 碼位作為十六進位制整數，並在前後加上下劃線。因此 變為 _20_ 且 . 變為 _2e_。

有關文字轉義的更多資訊，可以在原始的 UTF-8 提案文件 中找到。

此示例查詢 http.status_code 標籤的所有標籤值：

curl https://:9090/api/v1/label/U__http_2e_status_code/values

{
   "status" : "success",
   "data" : [
      "200",
      "404"
   ]
}

搜尋指標名稱、標籤名稱和標籤值

這些端點是實驗性的，必須透過 --enable-feature=search-api 啟用。

以下端點為指標名稱、標籤名稱和標籤值提供流式發現結果：

GET /api/v1/search/metric_names
POST /api/v1/search/metric_names
GET /api/v1/search/label_names
POST /api/v1/search/label_names
GET /api/v1/search/label_values
POST /api/v1/search/label_values

這些端點返回換行符分隔的 JSON（NDJSON），內容型別為 application/x-ndjson。流式傳輸協定為：

• 零個或多個批次行（batch lines），每個包含一個 results 陣列和一個可選的 warnings 陣列。
• 如果在傳送第一批後，在流中間迭代失敗，則流將以掛尾行（trailer line）（status、has_more、可選 warnings）或錯誤行（error line）（status、errorType、error）結束。

{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

如果在流式傳輸開始之前發生錯誤，API 將返回通常的帶有 4xx/5xx 狀態碼的 Prometheus JSON 錯誤物件。如果在流式傳輸開始之後發生錯誤，流將以 NDJSON 錯誤行代替掛尾行結束。

客戶端必須容忍沒有掛尾行的突然 EOF（例如，由於傳輸失敗或伺服器關閉），並且為了向前相容性，必須忽略掛尾行中未知的欄位。

掛尾行中的 has_more 欄位僅作為資訊提示：當前版本的 API 不提供分頁遊標。若要檢索更多結果，請提高 limit（受限於操作員配置的 --web.search.max-limit）或透過 match[] 縮小請求範圍。未來的 API 版本可能會新增遊標。

常用 URL 查詢引數

• match[]=<series_selector>：重複的序列選擇器，用於界定搜尋範圍。可選。
• search[]=<string>：重複的搜尋字串，用於與名稱或值進行匹配。多個值使用“或”（OR）語義。可選。
• fuzz_threshold=<number>：模糊閾值，從 0 到 100。可選。值 0 是最低模糊閾值（要求最寬鬆/匹配最模糊）。
• fuzz_alg=<subsequence | jarowinkler>：匹配演算法。可選。預設為 subsequence。
• case_sensitive=<bool>：切換是否區分大小寫進行匹配。可選。
• sort_by=<string>：排序模式。支援的值取決於具體端點。
• sort_dir=<asc | dsc>：排序方向。可選。僅在 sort_by=alpha 時有效。
• include_score=<bool>：在每個結果中包含相關性得分。可選。
• start=<rfc3339 | unix_timestamp>：開始時間戳。可選。
• end=<rfc3339 | unix_timestamp>：結束時間戳。可選。
• limit=<number>：返回結果的最大數量。可選。預設為 100。
• batch_size=<number>：每個 NDJSON 批次首選的結果數量。可選。預設為 100。

start 和 end 引數將結果縮小到所選的時間視窗。結果可能會包含該時間視窗外稍顯活躍的序列的值，因為 Prometheus 按固定大小的塊（通常為每塊 2 小時）儲存資料。

/api/v1/search/metric_names 的附加引數

• include_metadata=<bool>：在每個結果中包含指標元資料。
• sort_by=<alpha | score>

/api/v1/search/label_names 的附加引數

• sort_by=<alpha | score>

/api/v1/search/label_values 的附加引數

• label=<label_name>：要搜尋其值的標籤名稱。必填。
• sort_by=<alpha | score>

此示例搜尋指標名稱以進行自動補全：

curl -g 'https://:9090/api/v1/search/metric_names?search[]=http_req&sort_by=score&include_metadata=true&limit=5'

{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

此示例在 up 指標中搜索 instance 標籤的標籤值：

curl -g 'https://:9090/api/v1/search/label_values?label=instance&match[]=up&search[]=909&sort_by=score'

{"results":[{"value":"localhost:9090"},{"value":"localhost:9091"}]}
{"status":"success","has_more":true}

查詢 Exemplar

此功能是實驗性的，未來可能會發生變化。以下端點返回特定時間範圍內有效 PromQL 查詢的 Exemplar 列表：

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://: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 之間的整數，其含義如下：

• 0：“左開”（不包含左邊界，包含右邊界）
• 1：“右開”（包含左邊界，不包含右邊界）
• 2：“雙開”（左右邊界均不包含）
• 3：“雙閉”（左右邊界均包含）

請注意，在當前實現的桶（bucket）架構中，正數桶是“左開”的，負數桶是“右開”的，而零桶（具有負左邊界和正右邊界）是“雙閉”的。

抓取池

以下端點返回所有配置的抓取池列表：

GET /api/v1/scrape_pools

JSON 響應的 data 部分是字串抓取池名稱列表。

curl https://:9090/api/v1/scrape_pools

{
  "status": "success",
  "data": {
    "scrapePools": [
      "prometheus",
      "node_exporter",
      "blackbox"
    ]
  }
}

v2.42 中新增

目標

以下端點返回 Prometheus 目標發現當前狀態的概述：

GET /api/v1/targets

預設情況下，活動目標和已丟棄目標都是響應的一部分。如果設定了 keep_dropped_targets 限制，已丟棄目標會受到此限制。labels 表示重新標記（relabeling）發生後的標籤集。discoveredLabels 表示在發生重新標記之前，服務發現期間檢索到的未修改標籤。

curl https://: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",
          "__always_scrape_classic_histograms__": "false",
          "__convert_classic_histograms_to_nhcb__": "false",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "__scrape_interval__": "1m",
          "__scrape_native_histograms__": "false",
          "__scrape_timeout__": "10s",
          "job": "node"
        },
        "scrapePool": "node"
      }
    ]
  }
}

state 查詢引數允許呼叫者按活動或已丟棄的目標進行過濾（例如，state=active、state=dropped、state=any）。注意，對於被過濾掉的目標，仍會返回一個空陣列。其他值將被忽略。

curl 'https://: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://: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": []
  }
}

重新標記步驟

此端點是實驗性的，未來可能會發生變化。目前它僅供 Prometheus 自身之 Web UI 使用，並且端點名稱和返回的確切格式在不同 Prometheus 版本之間可能會有所不同。如果 UI 不再需要它，也可能會被刪除。

以下端點返回重新標記規則的逐步列表及其對給定目標標籤集的影響。

GET /api/v1/targets/relabel_steps

URL 查詢引數

• scrapePool=<string>：目標的抓取池名稱，用於確定要應用的重新標記規則。必填。
• labels=<string>：一個 JSON 物件，包含應用任何重新標記之前的目標標籤集。必填。

以下示例返回 prometheus 抓取池中已發現目標的重新標記步驟，其標籤集為 {"__address__": "localhost:9090", "job": "prometheus"}：

curl -g 'https://:9090/api/v1/targets/relabel_steps?scrapePool=prometheus&labels={"__address__":"localhost:9090","job":"prometheus"}'

{
   "data" : {
      "steps" : [
         {
            "keep" : true,
            "output" : {
               "__address__" : "localhost:9090",
               "env" : "development",
               "job" : "prometheus"
            },
            "rule" : {
               "action" : "replace",
               "regex" : "(.*)",
               "replacement" : "development",
               "separator" : ";",
               "target_label" : "env"
            }
         },
         {
            "keep" : false,
            "output" : {},
            "rule" : {
               "action" : "drop",
               "regex" : "localhost:.*",
               "replacement" : "$1",
               "separator" : ";",
               "source_labels" : [
                  "__address__"
               ]
            }
         }
      ]
   },
   "status" : "success"
}

規則

/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 屬性。您可以在後續請求中的 group_next_token 引數中使用此 groupNextToken 屬性的值，以便分頁瀏覽其餘規則組。最終響應中將不會出現 groupNextToken 屬性，這表示您已檢索到所有可用的規則組。請注意，如果在分頁過程中規則組被修改，無法保證響應的一致性。
• group_next_token：當設定了 group_limit 屬性時，在先前的請求中返回的分頁標記。分頁標記用於迭代分頁瀏覽大量的規則組。若要使用 group_next_token 引數，group_limit 引數也必須存在。如果與下一個標記一致的規則組在您分頁瀏覽規則組時被刪除，則將返回狀態碼為 400 的響應。

curl https://: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://: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"
}

查詢目標元資料

以下端點返回當前從目標抓取的指標元資料。該端點的侷限性在於，僅返回直接從目標抓取的元資料，透過遠端寫入或 OTLP 傳送到 Prometheus 的元資料不包含在此端點中，並且不會顯示在 UI 的“Explore Metrics”中。此功能是實驗性的，未來可能會發生變化。

GET /api/v1/targets/metadata

URL 查詢引數

• match_target=<label_selectors>：透過標籤集匹配目標的標籤選擇器。如果留空，則選擇所有目標。
• metric=<string>：要檢索元資料的指標名稱。如果留空，則檢索所有指標元資料。
• limit=<number>：要匹配的最大目標數。

查詢結果的 data 部分包含一個物件列表，這些物件包含指標元資料和目標標籤集。

以下示例返回標籤為 job="prometheus" 的前兩個目標中 go_goroutines 指標的所有元資料條目。

curl -G https://: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://: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://: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://: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://: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": ""
      }
    ]
  }
}

Alertmanager 列表

以下端點返回 Prometheus Alertmanager 發現的當前狀態概覽

GET /api/v1/alertmanagers

響應中同時包含處於活動狀態和被丟棄的 Alertmanager。

curl https://: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://: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://: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://:9090/api/v1/status/runtimeinfo

{
  "status": "success",
  "data": {
    "startTime": "2019-11-02T17:23:59.301361365+01:00",
    "CWD": "/",
    "hostname" : "DESKTOP-717H17Q",
    "serverTime": "2025-01-05T18:27:33Z",
    "reloadConfigSuccess": true,
    "lastConfigTime": "2019-11-02T17:23:59+01:00",
    "timeSeriesCount": 873,
    "corruptionCount": 0,
    "goroutineCount": 48,
    "GOMAXPROCS": 4,
    "GOGC": "",
    "GODEBUG": "",
    "storageRetention": "15d"
  }
}

注意確切返回的執行時屬性在 Prometheus 版本之間可能會發生變化，恕不另行通知。

v2.14 新增

構建資訊

以下端點返回有關 Prometheus 伺服器的各種構建資訊屬性

GET /api/v1/status/buildinfo

所有值的返回結果型別均為 string。

curl https://: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"
  }
}

注意確切返回的構建屬性在 Prometheus 版本之間可能會發生變化，恕不另行通知。

v2.14 新增

TSDB 統計資訊

以下端點返回有關 Prometheus TSDB 的各種基數統計資訊

GET /api/v1/status/tsdb

URL 查詢引數

• limit=<number>：限制每組統計資訊返回的條目數。預設情況下返回 10 個條目。最大允許限制為 10000。

查詢結果的 data 部分包含

• headStats：這提供有關 TSDB 頭部塊（head block）的以下資料
  • numSeries：時間序列的數量。
  • chunkCount：資料塊（chunk）的數量。
  • minTime：當前最小時間戳（以毫秒為單位）。
  • maxTime：當前最大時間戳（以毫秒為單位）。
• seriesCountByMetricName: 這將提供一個指標名稱及其序列數量的列表。
• labelValueCountByLabelName: 這將提供一個標籤名稱及其值數量的列表。
• memoryInBytesByLabelName 這將提供一個標籤名稱及其所用記憶體（以位元組為單位）的列表。記憶體使用量是透過將給定標籤名稱的所有值的長度相加計算得出的。
• seriesCountByLabelPair 這將提供一個標籤值對及其序列數量的列表。

curl https://: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
      }
    ]
  }
}

v3.6.0 新增

TSDB 資料塊

注意：此端點是實驗性的，將來可能會發生變化。端點名稱和返回資料的確切格式在 Prometheus 版本之間可能會有所不同。此端點返回的確切元資料是實現細節，在未來的 Prometheus 版本中可能會發生變化。

以下端點返回當前載入的 TSDB 資料塊列表及其元資料。

GET /api/v1/status/tsdb/blocks

此端點為每個資料塊返回以下資訊

• ulid：資料塊的唯一 ID。
• minTime：資料塊的最小時間戳（以毫秒為單位）。
• maxTime：資料塊的最大時間戳（以毫秒為單位）。
• 統計資訊 (stats):
  • numSeries：資料塊中序列的數量。
  • numSamples：資料塊中樣本的數量。
  • numChunks：資料塊中資料塊（chunk）的數量。
• 壓縮 (compaction):
  • level：資料塊的壓縮級別。
  • sources：用於壓縮此資料塊的源資料塊的 ULID 列表。
• version：資料塊版本。

curl https://:9090/api/v1/status/tsdb/blocks

{
  "status": "success",
  "data": {
    "blocks": [
      {
        "ulid": "01JZ8JKZY6XSK3PTDP9ZKRWT60",
        "minTime": 1750860620060,
        "maxTime": 1750867200000,
        "stats": {
          "numSamples": 13701,
          "numSeries": 716,
          "numChunks": 716
        },
        "compaction": {
          "level": 1,
          "sources": [
            "01JZ8JKZY6XSK3PTDP9ZKRWT60"
          ]
        },
        "version": 1
      }
    ]
  }
}

v2.15 新增

WAL 重放統計資訊

以下端點返回有關 WAL 重放的資訊

GET /api/v1/status/walreplay

• read：到目前為止已重放的分段（segment）數量。
• total：需要重放的總分段數量。
• progress：重放進度（0 - 100%）。
• state：重放狀態。可能的狀態
  • waiting：等待重放開始。
  • in progress：重放正在進行中。
  • done：重放已完成。

curl https://:9090/api/v1/status/walreplay

{
  "status": "success",
  "data": {
    "min": 2,
    "max": 5,
    "current": 40,
    "state": "in progress"
  }
}

注意該端點在伺服器被標記為就緒之前即可用，並會即時更新，以便於監控 WAL 重放的進度。

v2.28 新增

自身指標

注意：此端點是實驗性的，將來可能會發生變化。

以下端點以結構化 JSON 形式返回來自 Prometheus 內部客戶端登錄檔的自身檢測指標。這些指標與 Prometheus 文字展示格式中 /metrics 端點上暴露的指標相同，但為了便於 Web UI 程式設計訪問而以 JSON 格式返回。

該響應使用 io.prometheus.client.MetricFamily Protocol Buffer 訊息的標準 ProtoJSON  表示。

GET /api/v1/status/self_metrics

URL 查詢引數

• metric_name_pattern=<string>：指標名稱的正則表示式過濾器（完全錨定，類似於 PromQL 標籤匹配器）。僅返回名稱完全匹配該模式的指標系列（metric family）。例如，metric_name_pattern=prometheus_tsdb_.* 將返回所有名稱以 prometheus_tsdb_ 開頭的指標系列。可選。省略時，返回所有指標系列。

每個返回的指標系列都是一個 ProtoJSON 編碼的 MetricFamily，其中包含

• name：指標名稱。
• help：指標幫助說明字串。
• type：指標型別（COUNTER、GAUGE、SUMMARY、HISTOGRAM、UNTYPED）。
• unit：指標單位，如果已設定（可選）。
• metric：單獨指標的列表，每個指標包含
  • label：{name, value} 標籤對列表。
  • gauge、counter、summary、histogram 或 untyped：特定型別的指標資料。

curl 'https://:9090/api/v1/status/self_metrics?metric_name_pattern=prometheus_build_info'

{
  "status": "success",
  "data": [
    {
      "name": "prometheus_build_info",
      "help": "A metric with a constant '1' value labeled by version, revision, branch, goversion from which prometheus was built, and the goos and goarch for the build.",
      "type": "GAUGE",
      "metric": [
        {
          "label": [
            { "name": "branch", "value": "main" },
            { "name": "goarch", "value": "amd64" },
            { "name": "goos", "value": "linux" },
            { "name": "goversion", "value": "go1.26.1-X:nodwarf5" },
            { "name": "revision", "value": "7b5a4090e38d9e1ad7697c7641234f4ed135a6c7" },
            { "name": "tags", "value": "netgo,builtinassets" },
            { "name": "version", "value": "3.11.0-rc.0" }
          ],
          "gauge": {
            "value": 1
          }
        }
      ]
    }
  ]
}

TSDB 管理 API

這些是為高階使用者提供資料庫功能的 API。除非設定了 --web.enable-admin-api，否則不啟用這些 API。

快照 (Snapshot)

Snapshot 會在 TSDB 的資料目錄下將所有當前資料建立快照到 snapshots/<datetime>-<rand> 中，並返回該目錄作為響應。它可以選擇跳過僅存在於頭部塊（head block）中且尚未壓縮到磁碟的資料的快照。

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

URL 查詢引數

• skip_head=<bool>：跳過存在於頭部塊中的資料。可選。

curl -XPOST https://:9090/api/v1/admin/tsdb/snapshot

{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

快照現在存在於 <data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54

v2.1 新增，自 v2.9 起支援 PUT

刪除序列

DeleteSeries 用於刪除指定時間範圍內所選序列的資料。實際資料仍然存在於磁碟上，並將在未來的壓縮中被清理，或者可以透過請求 清理墓碑檔案 (Clean Tombstones) 端點來顯式清理。

如果成功，將返回 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://: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://: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 新增

OTLP 接收器

Prometheus 可以配置為 OTLP 指標協議的接收器。這不被認為是攝取樣本的高效方式。在特定的低吞吐量場景下請謹慎使用。它不適合替代透過抓取進行的資料攝取。

透過設定 --web.enable-otlp-receiver 啟用 OTLP 接收器。啟用後，OTLP 接收器端點為 /api/v1/otlp/v1/metrics。

v2.47 新增

OTLP Delta

Prometheus 可以將傳入的指標從增量臨時性（delta temporality）轉換為等效的累積臨時性（cumulative equivalent）。這是使用來自 OpenTelemetry 收集器的 deltatocumulative  完成的。

要啟用，請傳遞 --enable-feature=otlp-deltatocumulative。

v3.2 新增

通知

以下端點提供有關與 Prometheus 伺服器本身相關的活動狀態通知的資訊。通知在 Web UI 中使用。

這些端點是實驗性的。它們將來可能會更改。

活動通知

/api/v1/notifications 端點返回當前所有活動通知的列表。

GET /api/v1/notifications

示例

curl https://: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 端點使用 伺服器傳送事件 (Server-Sent Events)  即時流式傳輸發生的通知。已刪除的通知將以 active: false 傳送。連線到端點時會發送活動通知。

GET /api/v1/notifications/live

示例

curl https://: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 新增

特性 (Features)

以下端點返回 Prometheus 伺服器中已啟用特性的列表

GET /api/v1/features

該端點提供有關 Prometheus 例項中當前已啟用或停用的特性的資訊。特性按類別進行組織，例如 api、promql、promql_functions 等。

data 部分包含一個對映，其中每個鍵是一個特性類別，每個值是特性名稱到其啟用狀態（布林值）的對映。

curl https://:9090/api/v1/features

{
  "status": "success",
  "data": {
    "api": {
      "admin": false,
      "exclude_alerts": true
    },
    "otlp_receiver": {
      "delta_conversion": false,
      "native_delta_ingestion": false
    },
    "prometheus": {
      "agent_mode": false,
      "auto_reload_config": false
    },
    "promql": {
      "anchored": false,
      "at_modifier": true
    },
    "promql_functions": {
      "abs": true,
      "absent": true
    },
    "promql_operators": {
      "!=": true,
      "!~": true
    },
    "rules": {
      "concurrent_rule_eval": false,
      "keep_firing_for": true
    },
    "scrape": {
      "start_timestamp_zero_ingestion": false,
      "extra_metrics": false
    },
    "service_discovery": {
      "azure": true,
      "consul": true
    },
    "templating": {
      "args": true,
      "externalURL": true
    },
    "tsdb": {
      "delayed_compaction": false,
      "exemplar_storage": false
    }
  }
}

備註

• 所有特性名稱均採用 snake_case（蛇形命名法）命名規範
• 設定為 false 的特性可能會在響應中省略
• 客戶端應將缺失的特性視為等同於 false
• 客戶端必須忽略未知的特性名稱和類別，以保持向前相容性

v3.8 新增