HTTP API

2024-09-17

当前稳定版的 HTTP API 在 Prometheus 服务器上可以通过/api/v1接口访问。任何不会破坏现有功能的新增功能都将在此端点下增加。

格式概览

API 响应格式为 JSON。每个成功的 API 请求返回一个2xx状态码。

无效请求到达 API 处理器时，将返回一个 JSON 错误对象和以下 HTTP 响应代码之一：

400 Bad Request：参数缺失或不正确。
422 Unprocessable Entity：无法执行表达式（RFC4918）。
503 Service Unavailable：查询超时或中断。

在 API 端点被访问之前发生的错误也可能导致其他非2xx代码被返回。

如果存在不影响请求执行的错误，则可能返回一个警告数组。对于可能或可能不是误报的查询问题，可能会返回一个信息级别的注释数组。所有成功收集的数据将在”data”字段中返回。

JSON 响应包格式如下：

{
  "status": "success" | "error",
  "data": <data>,

  // 如果状态为 "error" 该字段则被设置，data 字段仍然可能包含额外数据。
  "errorType": "<string>",
  "error": "<string>",

  // 如果执行请求时出现了警告，该字段则被设置。data 字段仍然会有数据。
  "warnings": ["<string>"],
  // 如果执行请求时出现了 info 级别的注释，该字段则被设置。
  "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 '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
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标志的值。

查询结果的data部分具有以下格式：

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

对于<value>占位符的格式，请参阅范围向量结果格式。

以下示例在30秒范围内以15秒的解析度评估表达式up：

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

格式化查询表达式

以下端点以美化的方式格式化 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 'http://localhost:9090/api/v1/format_query?query=foo/bar'
{
   "status" : "success",
   "data" : "foo / bar"
}

查询元数据

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头部直接在请求体中对这些参数进行 URL 编码。这对于指定可能超出服务器端 URL 字符限制的大量或动态序列选择器非常有用。

查询结果的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"}'
{
   "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>：选取要读取指标名称的序列的重复序列选择器参数（repeated 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部分是一个字符串标签值列表。

以下示例查询job标签的所有标签值：

$ curl http://localhost:9090/api/v1/label/job/values
{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}

查询示例

这是实验性的功能，其功能在未来可能会发生变化。
以下端点返回有效 PromQL 查询在特定时间范围内的示例（exemplars）列表：

GET /api/v1/query_exemplars
POST /api/v1/query_exemplars

URL查询参数：

query=<string>：Prometheus 表达式查询字符串。
start=<rfc3339 | unix_timestamp>：开始时间戳。
end=<rfc3339 | unix_timestamp>：结束时间戳。

$ curl -g 'http://localhost: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（native histogram），则会出现 "histogram" 和 "histograms" 键。

范围向量

范围向量以matrix类型返回结果。对应的result属性格式如下：

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ],
    "histograms": [ [ <unix_time>, <histogram> ], ... ]
  },
  ...
]

每个序列可能包含"values"或"histograms"键，或两者都有。对于给定的时间戳，同一类型的样本（float 或 Histogram）只会有一个。

按照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

上面使用的 <histogram> 占位符格式如下。

注意，原生 Histogram 是一个实验特性，下方的格式可能会有变化。

{
  "count": "<count_of_observations>",
  "sum": "<sum_of_observations>",
  "buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
}

<<font style="color:rgb(51, 51, 51);background-color:rgb(249, 242, 244);">boundary_rule</font>>占位符是一个介于 0 和 3 之间的整数，其含义如下：

0：「左开」（左边界排除，右边界包含）
1：「右开」（左边界包含，右边界排除）
2：「双开」（两边都排除）
3：「双闭」（两边都包含）

请注意，当前实现的桶方案下，正向桶为「左开」，负向桶为「右开」，零桶（带有负左边界和正右边界）为「双闭」。

Targets

以下端点返回 Prometheus Target 发现状态的概览：

GET /api/v1/targets

活跃 Target 和被丢弃的 Target 默认都被包含在响应中。如果已设置keep_dropped_targets了参数，被丢弃的 Target 会受到限制，。labels表示在 relabeling（重标签）发生后的标签集。discoveredLabels表示在服务发现前未经过 relabeling 的原始标签集。

$ 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",
        "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查询参数允许调用者根据活跃或被丢弃的 Target 进行筛选（例如，state=active、state=dropped、state=any）。注意，筛选掉的 Target 仍然会返回空数组。其他值会被忽略。

$ 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",
        "globalUrl": "http://example-prometheus:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 50688943,
        "health": "up"
      }
    ],
    "droppedTargets": []
  }
}

scrapePool查询参数允许调用者根据抓取池名称进行筛选。

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

规则

/rulesAPI 端点返回当前加载的告警和记录规则（recording rules）列表。此外，它还返回由 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：只返回已配置了满足标签选择器的标签的规则。如果参数重复，会返回匹配任意一组标签选择器的规则。注意，匹配发生在规则定义中的标签上，而不是模板展开后的值（对于告警规则）。可选。

$ curl http://localhost:9090/api/v1/rules

{
    "data": {
        "groups": [
            {
                "rules": [
                    {
                        "alerts": [
                            {
                                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                                "annotations": {
                                    "summary": "高请求延迟"
                                },
                                "labels": {
                                    "alertname": "HighRequestLatency",
                                    "severity": "page"
                                },
                                "state": "firing",
                                "value": "1e+00"
                            }
                        ],
                        "annotations": {
                            "summary": "高请求延迟"
                        },
                        "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

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部分包含一个对象列表，这些对象包含指标元数据和目标标签集。

以下示例返回go_goroutines指标的所有元数据条目，来自具有标签job="prometheus"的前两个 Target。

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"的 Target 的指标元数据。

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": ""
    },
    // ...
  ]
}

查询指标元数据

它返回当前从 Target 收集的指标的相关元数据。但它不会提供任何 Target 信息。
这是实验性的，并可能在未来发生变化。

GET /api/v1/metadata

URL 查询参数：

limit=<数字>：要返回的最大指标数量。
limit_per_metric=<数字>：每种指标返回的最大元数据数量。
metric=<字符串>：用于过滤元数据的指标名称。如果留空，则检索所有指标元数据。

查询结果的data部分是一个对象，其中每个键是指标名称，每个值是一个列表，包含针对该指标名称在所有 Target 上暴露的所有唯一元数据对象。

以下示例返回两个指标。请注意，http_requests_total指标列表中的对象多于一个。至少有一个 Target 的HELP值与其余部分不匹配。

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

Alertmanagers

以下端点返回有关当前状态的 Prometheus Alertmanager 的发现概览：

GET /api/v1/alertmanagers

活跃和丢弃的 Alertmanager 都被包含在响应中。

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

状态

以下状态端点展示了当前 Prometheus 配置信息。

配置

以下端点返回当前加载的配置文件：

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

标志

以下端点返回 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 版本起新增

运行时信息

以下端点返回 Prometheus 服务器的各种运行时信息属性：

GET /api/v1/status/runtimeinfo

返回的值根据运行时属性的性质不同，类型也有所不同。

$ curl http://localhost: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"
  }
}

**注意：**Prometheus 版本之间可能会无通知地更改返回的运行时属性。

自 v2.14 版本起新增

构建信息

以下端点返回 Prometheus 服务器的各种构建信息属性：

GET /api/v1/status/buildinfo

所有值都是字符串类型。

$ curl http://localhost: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 项。

查询结果的 data 部分包含：

headStats：提供了关于 TSDB 头部块的以下数据：
- numSeries：序列的数量。
- chunkCount：块的数量。
- minTime：当前最小时间戳（毫秒）。
- maxTime：当前最大时间戳（毫秒）。
seriesCountByMetricName：提供指标名称及其序列计数的列表。
labelValueCountByLabelName：提供标签名称及其值计数的列表。
memoryInBytesByLabelName：提供标签名称及其使用字节数的列表。内存使用量通过将给定标签名称的所有值相加来计算。
seriesCountByLabelPair：提供标签值对及其序列计数的列表。

$ curl http://localhost: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 回放统计

以下端点返回关于 WAL 回放（replay）的信息：

GET /api/v1/status/walreplay

注意：此端点在服务器标记就绪之前可用，并实时更新以方便监控 WAL 回放的进度。

read: 已经回放的段的数量。
total: 需要回放的总段数量。
progress: 回放的进度（0%-100%）。
state: 回放的状态。可能的状态：
- waiting: 等待回放开始。
- in progress: 回放正在进行中。
- done: 回放已完成。

$ curl http://localhost:9090/api/v1/status/walreplay
{
  "status": "success",
  "data": {
    "min": 2,
    "max": 5,
    "current": 40,
    "state": "in progress"
  }
}

自 v2.28 版本新增

TSDB 管理 API

这些是为高级用户暴露数据库功能的 API。除非设置了--web.enable-admin-api，否则这些 API 不会启用。

快照

快照将当前的所有数据保存到snapshots/<datetime>-<rand>下的 TSDB 数据目录，并返回目录作为响应。它可选地跳过仅存在于头块中或未被压缩的的数据的快照。

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

URL 查询参数：

skip_head=<bool>: 跳过存在于头块中的数据。可选。

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

快照现在位于<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54

从 v2.1 版本起新增，从 v2.9 版本起支持 PUT

删除序列

DeleteSeriesAPI用于删除指定时间范围内的一系列数据。实际的数据仍然存储在磁盘上，将会在未来的压缩中被清理。你也可以通过访问清理墓碑端点进行显式清理。

如果操作成功，将返回204状态码。

HTTP请求方法：

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 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'

注意：此端点标记样本为已删除，但受影响时间段相关的关联序列元数据仍然会在元数据查询中返回（即使在清理墓碑之后）。元数据删除的确切范围是实现细节，未来可能会发生变化。

自 v2.1 版本新增，从 v2.9版本起支持PUT

清理墓碑

CleanTombstonesAPI 用于从磁盘中移除已删除的数据并清理现有墓碑。在删除序列后使用此 API 可以释放空间。

如果操作成功，将返回204状态码。

HTTP请求方法：

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones

此 API 无需参数或主体。

示例：

$ curl -XPOST 'http://localhost:9090/api/v1/admin/tsdb/clean_tombstones'

*自 v2.1 版本新增，从 v2.9 版本起支持 PUT

Remote write 接收器

Prometheus 可以配置为接受 Prometheus remote write 协议。这被认为是一种不高效的数据消费方式。在低流量的使用场景，请谨慎使用。它不适合替代通过抓取的方式进行数据消费，并将 Prometheus 转换为基于推送的指标收集系统的应用场景。

通过设置--web.enable-remote-write-receiver启用 remote write 接收器。启用后，remote write 接收器端点为/api/v1/write。更多详细信息，请参见这里。

*自 v2.33 版本新增

OTLP 接收器

Prometheus 可以配置使用 OTLP（OpenTelemetry Protocol）指标协议的接收器。这被认为是一种不高效的数据消费方式。在低流量的使用场景，请谨慎使用。它不适合替代通过抓取的方式进行数据消费。

通过特征标志--enable-feature=otlp-write-receiver启用 OTLP 接收器。当启用时，OTLP 接收器端点为/api/v1/otlp/v1/metrics。

*自 v2.47 版本新增

_该文档基于 _Prometheus 官方文档翻译而成。