HTTP API
当前稳定的 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>,
// 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 表示禁用。
如果省略 time 参数，则使用当前服务器时间。
您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 请求头，直接在请求体中对这些参数进行 URL 编码。这在指定可能超出服务器端 URL 字符限制的大型查询时非常有用。
查询结果的 data 部分格式如下：
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}<value> 指的是查询结果数据，其格式根据 resultType 而异。参见表达式查询结果格式。
以下示例评估了表达式 up 在 2015-07-01T20:10:51.781Z 时间点的值：
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 表示禁用。
您可以使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 请求头，直接在请求体中对这些参数进行 URL 编码。这在指定可能超出服务器端 URL 字符限制的大型查询时非常有用。
查询结果的 data 部分格式如下：
{
"resultType": "matrix",
"result": <value>
}<value> 占位符的格式，请参见范围向量结果格式。
以下示例评估了表达式 up 在 30 秒范围内的值，查询分辨率为 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" ]
]
}
]
}
}格式化查询表达式
以下端点以美化方式格式化 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 请求头，直接在请求体中对这些参数进行 URL 编码。这在指定可能超出服务器端 URL 字符限制的大量或动态序列选择器时非常有用。
查询结果的 data 部分包含一个对象列表，这些对象包含标识每个序列的标签名称/值对。
以下示例返回与选择器 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 部分是字符串标签名称的列表。
以下是一个示例。
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://: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"
]
}查询示例
此为**实验性功能**，未来可能会更改。以下端点返回特定时间范围内有效 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://: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：“两边闭”（两边边界都包含）
请注意，在当前实现的桶模式下，正值桶是“左开”，负值桶是“右开”，而零桶（具有负左边界和正右边界）是“两边闭合”。
目标
以下端点返回 Prometheus 目标发现的当前状态概述：
GET /api/v1/targets
默认情况下，活跃目标和已删除目标都包含在响应中。已删除目标受 keep_dropped_targets 限制（如果已设置）。labels 表示重新标记后生成的标签集。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",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"__scrape_interval__": "1m",
"__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": []
}
}规则
/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://: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"
}查询目标元数据
以下端点返回有关当前从目标抓取的指标的元数据。此为**实验性功能**，未来可能会更改。
GET /api/v1/targets/metadata
URL 查询参数
match_target=<label_selectors>：按标签集匹配目标的标签选择器。如果留空，则选择所有目标。metric=<string>：要检索元数据的指标名称。如果留空，则检索所有指标元数据。limit=<number>：要匹配的目标最大数量。
查询结果的 data 部分包含一个对象列表，这些对象包含指标元数据和目标标签集。
以下示例返回 go_goroutines 指标的所有元数据条目，这些条目来自标签为 job="prometheus" 的前两个目标。
curl -G http://: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 个项目。
查询结果的 data 部分包括：
- headStats：这提供了有关 TSDB 头块的以下数据：
- numSeries：时间序列的数量。
- chunkCount：数据块的数量。
- 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
}
]
}
}v2.15 新增
WAL 重放统计
以下端点返回有关 WAL 重放的信息：
GET /api/v1/status/walreplay
- read：到目前为止已重放的段数。
- 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 新增
TSDB 管理 API
这些 API 为高级用户暴露数据库功能。除非设置了 --web.enable-admin-api，否则这些 API 不会启用。
快照
Snapshot 会在 TSDB 的数据目录下将所有当前数据创建一个快照到 snapshots/<datetime>-<rand>，并将该目录作为响应返回。它可以选择性地跳过仅存在于头部块中且尚未压缩到磁盘的数据的快照。
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 删除时间范围内选定序列的数据。实际数据仍然存在于磁盘上，并将在未来的压缩中清理，或者可以通过访问 清理墓碑 接口显式清理。
如果成功，将返回 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_tombstonesv2.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 增量
Prometheus 可以将传入的增量指标转换为其累积等效值。这是通过使用 OpenTelemetry Collector 中的 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/livedata: {
"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 新增