HTTP API
Prometheus 服务器上的当前稳定 HTTP API 可在 /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 表示禁用。lookback_delta=<number>：仅为此查询覆盖 回溯期。可选。
如果省略 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=<number>：仅为此查询覆盖 回溯期。可选。
通过使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 标头，您可以直接在请求正文中 URL 编码这些参数。当指定可能超出服务器端 URL 字符限制的大型查询时，这非常有用。
查询结果的 data 部分具有以下格式
{
"resultType": "matrix",
"result": <value>
}有关 <value> 占位符的格式，请参阅 范围向量结果格式。
以下示例以 15 秒的查询分辨率评估 30 秒范围内的表达式 up。
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 部分由包含标识每个系列的名称/值对的对象的列表组成。请注意，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"
]
}查询样本
这是实验性的，将来可能会发生变化。以下端点返回指定时间范围内有效 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": []
}
}重新标记步骤
此端点是实验性的，将来可能会发生更改。它目前仅供 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属性。您可以使用此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 部分由包含指标元数据和目标标签集的对象的列表组成。
以下示例返回来自前两个标签为 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": ""
}
]
}
}Alertmanagers
以下端点返回 Prometheus alertmanager 发现的当前状态的概述
GET /api/v1/alertmanagers
活动 Alertmanager 和已删除 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 块的以下数据
- numSeries：系列数量。
- chunkCount：块的数量。
- minTime：当前的最小时间戳（毫秒）。
- maxTime：当前的 maximum 时间戳（毫秒）。
- 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 Blocks
注意：此端点是实验性的，未来可能会发生更改。端点名称和返回数据的确切格式可能会在 Prometheus 版本之间发生变化。此端点返回的确切元数据是实现细节，在未来的 Prometheus 版本中可能会发生更改。
以下端点返回当前加载的 TSDB 块及其元数据列表。
GET /api/v1/status/tsdb/blocks
此端点为每个块返回以下信息
ulid：块的唯一 ID。minTime：块的最小时间戳（以毫秒为单位）。maxTime：块的最大时间戳（以毫秒为单位）。stats:numSeries：块中的系列数量。numSamples：块中的样本数量。numChunks：块中的块数量。
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 Replay Stats
以下端点返回有关 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 Admin APIs
这些 API 向高级用户公开数据库功能。这些 API 只有在设置了--web.enable-admin-api 时才启用。
Snapshot
Snapshot 会将所有当前数据快照到 TSDB 数据目录下的 snapshots/<datetime>-<rand> 中，并以目录作为响应返回。它还可以选择跳过仅存在于 head 块且尚未压缩到磁盘的数据。
POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot
URL 查询参数
skip_head=<bool>：跳过 head 块中存在的数据。可选。
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
Delete Series
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>：结束时间戳。可选，默认为可能的最大时间。
未同时指定开始和结束时间将清除数据库中匹配系列的所有数据。
Example
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
Clean Tombstones
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
Remote Write Receiver
Prometheus 可以配置为 Prometheus 远程写入协议的接收器。这不被认为是高效的样本摄取方式。请谨慎用于特定的低流量用例。它不适合替代抓取方式并将其转换为基于推送的指标收集系统。
通过设置 --web.enable-remote-write-receiver 来启用远程写入接收器。启用后，远程写入接收器端点为 /api/v1/write。在此处查找更多详细信息 here。
v2.33 中的新增内容
OTLP Receiver
Prometheus 可以配置为 OTLP Metrics 协议的接收器。这不被认为是高效的样本摄取方式。请谨慎用于特定的低流量用例。它不适合替代抓取方式。
通过设置 --web.enable-otlp-receiver 来启用 OTLP 接收器。启用后，OTLP 接收器端点为 /api/v1/otlp/v1/metrics。
v2.47 中的新增内容
OTLP Delta
Prometheus 可以将传入的指标从增量（delta）临时性转换为其累积（cumulative）等效项。这是通过 deltatocumulative （来自 OpenTelemetry Collector）完成。
要启用，请传递 --enable-feature=otlp-deltatocumulative。
v3.2 中的新增内容
Notifications
以下端点提供有关 Prometheus 服务器本身的状态通知信息。通知用于 Web UI。
这些端点是实验性的。它们在未来可能会发生更改。
Active Notifications
/api/v1/notifications 端点返回所有当前活动通知的列表。
GET /api/v1/notifications
Example
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 中的新增内容
Live Notifications
/api/v1/notifications/live 端点使用 Server-Sent Events 流式传输发生的实时通知。已删除的通知将发送 active: false。活动通知将在连接到端点时发送。
GET /api/v1/notifications/live
Example
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 中的新增内容
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 中的新增内容