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 响应包格式如下:
通用占位符定义如下:
<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 端点。
即时查询
以下端点用于在单个时间点计算即时查询:
URL 查询参数:
query=<string>
:Prometheus 表达式查询字符串。time=<rfc3339 | unix_timestamp>
:评估时间戳。可选。timeout=<duration>
:评估超时。可选,默认值为-query.timeout
标志的值。
如果省略了time
参数,则使用当前服务器时间。
直接在请求体中使用POST
方法和Content-Type: application/x-www-form-urlencoded
头部 URL 编码这些参数非常有用,当指定一个可能违反服务器端 URL 字符限制的大查询时。
查询结果的data
部分具有以下格式:
<value>
指的是查询结果数据,其格式取决于resultType
。参见表达式查询结果格式。
以下示例在时间2015-07-01T20:10:51.781Z
评估表达式up
:
范围查询
以下端点用于在一个时间范围内评估表达式查询:
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
部分具有以下格式:
对于<value>
占位符的格式,请参阅范围向量结果格式。
以下示例在30秒范围内以15秒的解析度评估表达式up
:
格式化查询表达式
以下端点以美化的方式格式化 PromQL 表达式:
URL查询参数:
query=<string>
:Prometheus 表达式查询字符串。
可以通过使用POST
方法和Content-Type: application/x-www-form-urlencoded
头部直接在请求体中对这些参数进行 URL 编码。这对于指定可能超出服务器端 URL 字符限制的大查询非常有用。
查询结果的data
部分包含格式化的查询表达式。注意,格式化字符串会删除任何注释。
以下示例格式化了foo/bar
表达式:
查询元数据
Prometheus 提供了一系列 API 端点,用于查询关于序列及其标签的元数据。
注意:这些 API 端点可能会返回指定时间范围内不存在样例的序列的元数据,以及通过删除 API 端点标记为已删除的序列的元数据。至于返回额外序列元数据的确切范围则属于实现细节,可能在未来发生改变。
按标签匹配查找序列
以下端点返回匹配特定标签集的时间序列列表。
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"}
中的任一选择器的所有序列:
获取标签名称
以下端点返回标签名称列表:
URL查询参数:
start=<rfc3339 | unix_timestamp>
:开始时间戳。可选。end=<rfc3339 | unix_timestamp>
:结束时间戳。可选。match[]=<series_selector>
:选取要读取指标名称的序列的重复序列选择器参数(repeated series selector)。可选。limit=<number>
:返回的最大序列数量。可选。0表示禁用。
JSON 响应的data
部分是一个字符串标签名称列表。
以下是一个示例。
查询标签值
以下端点返回提供的标签名称的值列表:
URL查询参数:
start=<rfc3339 | unix_timestamp>
:开始时间戳。可选。end=<rfc3339 | unix_timestamp>
:结束时间戳。可选。match[]=<series_selector>
:选取要读取指标名称的序列的重复序列选择器参数。可选。limit=<number>
:返回的最大序列数量。可选。0表示禁用。
JSON 响应的data
部分是一个字符串标签值列表。
以下示例查询job
标签的所有标签值:
查询示例
这是实验性的功能,其功能在未来可能会发生变化。
以下端点返回有效 PromQL 查询在特定时间范围内的示例(exemplars)列表:
URL查询参数:
query=<string>
:Prometheus 表达式查询字符串。start=<rfc3339 | unix_timestamp>
:开始时间戳。end=<rfc3339 | unix_timestamp>
:结束时间戳。
查询结果格式
查询表达式可能会在data
部分的result
属性中返回以下响应值。<sample_value>
占位符是数值样例值。JSON 不支持特殊浮点值,如NaN
、Inf
和 -Inf
,因此样例值会作为引号中的 JSON 字符串而不是原始数字被传输。
如果响应中存在实验性原生 Histogram(native histogram),则会出现 "histogram"
和 "histograms"
键。
范围向量
范围向量以matrix
类型返回结果。对应的result
属性格式如下:
每个序列可能包含"values"
或"histograms"
键,或两者都有。对于给定的时间戳,同一类型的样本(float 或 Histogram)只会有一个。
按照metric
排序返回序列。函数如sort
和sort_by_label
对范围向量没有影响。
瞬时向量
瞬时向量以vector
类型返回结果。对应的result
属性格式如下:
每个序列可能包含"value"
键或"histogram"
键,但不能同时包含两个。
除非使用函数如sort
或sort_by_label
,否则序列的返回顺序没有保证。
标量
标量结果以scalar
类型返回结果。对应的result
属性格式如下:
字符串
字符串结果以string
类型返回结果。对应的result
属性格式如下:
原生 Histogram
上面使用的 <histogram>
占位符格式如下。
注意,原生 Histogram 是一个实验特性,下方的格式可能会有变化。
<<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 发现状态的概览:
活跃 Target 和被丢弃的 Target 默认都被包含在响应中。如果已设置keep_dropped_targets
了参数,被丢弃的 Target 会受到限制,。labels
表示在 relabeling(重标签)发生后的标签集。discoveredLabels
表示在服务发现前未经过 relabeling 的原始标签集。
state
查询参数允许调用者根据活跃或被丢弃的 Target 进行筛选(例如,state=active
、state=dropped
、state=any
)。注意,筛选掉的 Target 仍然会返回空数组。其他值会被忽略。
scrapePool
查询参数允许调用者根据抓取池名称进行筛选。
规则
/rules
API 端点返回当前加载的告警和记录规则(recording rules)列表。此外,它还返回由 Prometheus 实例触发的当前活跃告警。
由于/rules
端点相对较新,因此其稳定性保证不如使用更广泛的 API v1。
URL 查询参数:
type=alert|record
:只返回告警规则(例如type=alert
)或记录规则(例如type=record
)。当参数不存在或为空时,不进行过滤。rule_name[]=string
:只返回具有给定规则名称的规则。如果参数重复,会返回任何提供的名称的规则。如果过滤出了所有一组规则中的规则,则该组不会返回。当参数不存在或为空时,不进行过滤。rule_group[]=string
:只返回具有给定规则组名称的规则。如果参数重复,会返回任何提供的规则组名称的规则。当参数不存在或为空时,不进行过滤。file[]=string
:只返回具有给定文件路径的规则。如果参数重复,会返回任何提供的文件路径的规则。当参数不存在或为空时,不进行过滤。exclude_alerts=bool
:只返回规则,不返回活跃告警。match[]=label_selector
:只返回已配置了满足标签选择器的标签的规则。如果参数重复,会返回匹配任意一组标签选择器的规则。注意,匹配发生在规则定义中的标签上,而不是模板展开后的值(对于告警规则)。可选。
告警
/alerts
端点返回当前所有活跃告警的列表。
由于/alerts
端点相对较新,因此它没有 API v1 那样的稳定性保证。
查询目标元数据
以下端点返回从目标收集的指标值的元数据。此功能处于实验阶段,未来可能发生变化。
URL 查询参数:
match_target=<label_selectors>
:通过目标的标签集匹配目标的标签选择器。如果为空,则选择所有目标。metric=<string>
:要检索其元数据的指标名称。如果为空,则检索所有指标的元数据。limit=<number>
:匹配的最大目标数量。
查询结果中的data
部分包含一个对象列表,这些对象包含指标元数据和目标标签集。
以下示例返回go_goroutines
指标的所有元数据条目,来自具有标签job="prometheus"
的前两个 Target。
以下示例返回所有带有标签instance="127.0.0.1:9090"
的 Target 的指标元数据。
查询指标元数据
它返回当前从 Target 收集的指标的相关元数据。但它不会提供任何 Target 信息。
这是实验性的,并可能在未来发生变化。
URL 查询参数:
limit=<数字>
:要返回的最大指标数量。limit_per_metric=<数字>
:每种指标返回的最大元数据数量。metric=<字符串>
:用于过滤元数据的指标名称。如果留空,则检索所有指标元数据。
查询结果的data
部分是一个对象,其中每个键是指标名称,每个值是一个列表,包含针对该指标名称在所有 Target 上暴露的所有唯一元数据对象。
以下示例返回两个指标。请注意,http_requests_total
指标列表中的对象多于一个。至少有一个 Target 的HELP
值与其余部分不匹配。
以下示例仅返回每个指标的一个元数据条目。
以下示例仅返回http_requests_total
指标的元数据。
Alertmanagers
以下端点返回有关当前状态的 Prometheus Alertmanager 的发现概览:
活跃和丢弃的 Alertmanager 都被包含在响应中。
状态
以下状态端点展示了当前 Prometheus 配置信息。
配置
以下端点返回当前加载的配置文件:
配置以 YAML 文件形式返回。由于 YAML 库的限制,YAML 注释不会被包括。
标志
以下端点返回 Prometheus 配置时使用的标志值:
所有值都是字符串类型。
自 v2.2 版本起新增
运行时信息
以下端点返回 Prometheus 服务器的各种运行时信息属性:
返回的值根据运行时属性的性质不同,类型也有所不同。
**注意:**Prometheus 版本之间可能会无通知地更改返回的运行时属性。
自 v2.14 版本起新增
构建信息
以下端点返回 Prometheus 服务器的各种构建信息属性:
所有值都是字符串类型。
注意: Prometheus 版本之间可能会无通知地更改返回的构建属性。
自 v2.14 版本起新增
TSDB 状态统计
以下端点返回有关 Prometheus TSDB 的各种基数统计信息:
URL 查询参数:
limit=<number>
:限制返回的项目数量,对于每组统计数据。默认情况下,返回 10 项。
查询结果的 data
部分包含:
- headStats:提供了关于 TSDB 头部块的以下数据:
- numSeries:序列的数量。
- chunkCount:块的数量。
- minTime:当前最小时间戳(毫秒)。
- maxTime:当前最大时间戳(毫秒)。
- seriesCountByMetricName:提供指标名称及其序列计数的列表。
- labelValueCountByLabelName:提供标签名称及其值计数的列表。
- memoryInBytesByLabelName:提供标签名称及其使用字节数的列表。内存使用量通过将给定标签名称的所有值相加来计算。
- seriesCountByLabelPair:提供标签值对及其序列计数的列表。
自 v2.15 新增
WAL 回放统计
以下端点返回关于 WAL 回放(replay)的信息:
注意:此端点在服务器标记就绪之前可用,并实时更新以方便监控 WAL 回放的进度。
- read: 已经回放的段的数量。
- total: 需要回放的总段数量。
- progress: 回放的进度(0%-100%)。
- state: 回放的状态。可能的状态:
- waiting: 等待回放开始。
- in progress: 回放正在进行中。
- done: 回放已完成。
自 v2.28 版本新增
TSDB 管理 API
这些是为高级用户暴露数据库功能的 API。除非设置了--web.enable-admin-api
,否则这些 API 不会启用。
快照
快照将当前的所有数据保存到snapshots/<datetime>-<rand>
下的 TSDB 数据目录,并返回目录作为响应。它可选地跳过仅存在于头块中或未被压缩的的数据的快照。
URL 查询参数:
skip_head=<bool>
: 跳过存在于头块中的数据。可选。
快照现在位于<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54
从 v2.1 版本起新增,从 v2.9 版本起支持 PUT
删除序列
DeleteSeries
API用于删除指定时间范围内的一系列数据。实际的数据仍然存储在磁盘上,将会在未来的压缩中被清理。你也可以通过访问清理墓碑端点进行显式清理。
如果操作成功,将返回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>
:结束时间戳。可选,默认为可能的时间最大值。
如果不指定开始和结束时间,则会清除数据库中与匹配序列相关的所有数据。
示例:
注意:此端点标记样本为已删除,但受影响时间段相关的关联序列元数据仍然会在元数据查询中返回(即使在清理墓碑之后)。元数据删除的确切范围是实现细节,未来可能会发生变化。
自 v2.1 版本新增,从 v2.9版本起支持PUT
清理墓碑
CleanTombstones
API 用于从磁盘中移除已删除的数据并清理现有墓碑。在删除序列后使用此 API 可以释放空间。
如果操作成功,将返回204
状态码。
HTTP请求方法:
POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones
此 API 无需参数或主体。
示例:
*自 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 官方文档翻译而成。