Prometheus

55708
下载
Prometheus 是一个开源的监控和告警系统,专注于时间序列数据的采集与存储。由 SoundCloud 开发,配备高级查询语言PromQL,便于数据挖掘与分析,并无缝对接多种可视化平台。

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>,
// 如果状态为 "error" 该字段则被设置,data 字段仍然可能包含额外数据。
"errorType": "<string>",
"error": "<string>",
// 如果执行请求时出现了警告,该字段则被设置。data 字段仍然会有数据。
"warnings": ["<string>"],
// 如果执行请求时出现了 info 级别的注释,该字段则被设置。
"infos": ["<string>"]
}

通用占位符定义如下:

  • <rfc3339 | unix_timestamp>:输入时间戳可以使用 RFC3339 格式或以秒为单位的Unix时间戳,可选包含小数点以实现亚秒精度。输出时间戳始终表示为秒为单位的 Unix 时间戳。
  • <series_selector>:Prometheus 时间序列选择器,如http_requests_totalhttp_requests_total{method=~"(GET|POST)"},需要进行URL编码。
  • <duration>Prometheus 持续时间。例如,5m表示5分钟的持续时间。
  • <bool>:布尔值(字符串truefalse)。

注意:带有可能重复的查询参数名称列表可能以[]结尾。

表达式查询

表达式查询可以在特定时刻或时间范围内评估。下面描述了每种类型表达式查询的 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标志的值。

直接在请求体中使用POST方法和Content-Type: application/x-www-form-urlencoded头部 URL 编码这些参数非常有用,当指定一个可能违反服务器端 URL 字符限制的大查询时。

查询结果的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部分由包含识别每个序列的标签名称/值对的对象列表组成。

以下示例返回匹配upprocess_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 不支持特殊浮点值,如NaNInf-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排序返回序列。函数如sortsort_by_label对范围向量没有影响。

瞬时向量

瞬时向量以vector类型返回结果。对应的result属性格式如下:

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

每个序列可能包含"value"键或"histogram"键,但不能同时包含两个。

除非使用函数如sortsort_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=activestate=droppedstate=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 官方文档翻译而成。


observability.cn Authors 2024 | Documentation Distributed under CC-BY-4.0
Copyright © 2017-2024, Alibaba. All rights reserved. Alibaba has registered trademarks and uses trademarks.
浙ICP备2021005855号-32