跳至主要內容

Prometheus API接口

bsfc.tech大约 5 分钟中间件

Prometheus的API分为管理API和查询API,管理API主要是Prometheus Server自身的状态和管理操作。查询API,是主要给做二次开发使用的。

管理API

1. 重载配置 (POST /-/reload)

用途: 该API允许您无须重启Prometheus服务即可重新加载配置文件,包括 scrape targets 和 alerting rules 的更新。

请求示例:

curl -X POST 'http://your-prometheus-server/-/reload'

请注意,此功能需要在Prometheus启动时启用相应的命令行标志,并且可能依赖于Prometheus的部署方式(如Docker容器或Kubernetes部署有特定的考虑)。

2. 查看和管理告警规则 (GET, POST, DELETE /api/v1/rules)

  • GET: 用于获取当前配置的所有规则组和规则。
  • POST: 可以用来添加或修改规则。
  • DELETE: 允许删除特定的规则或规则组。

查看规则示例:

curl 'http://your-prometheus-server/api/v1/rules'

3. 靶标管理 (GET /api/v1/targets)

虽然没有直接的API来修改靶标(scrape targets),但通过查询此端点,您可以获取当前所有配置的靶标状态,包括哪些正在被抓取、哪些失败以及它们的标签信息。这对于监控和诊断Scrape配置问题非常有用。

4. 集群信息和健康检查

  • /api/v1/status/config: 返回当前Prometheus配置。
  • /api/v1/status/runtimeinfo: 提供Prometheus运行时信息,如Go runtime stats。
  • /api/v1/status/flags: 显示Prometheus启动时的标志设置。
  • /api/v1/status/tsdb: 如果使用本地存储,提供关于TSDB的信息。

Prometheus的查询API是其最强大且常用的功能之一,允许用户通过HTTP请求查询存储在Prometheus服务器上的时间序列数据。以下是查询API的几个关键端点及其使用方法:

查询API

1. 即时查询 (GET /api/v1/query)

用于查询指定时间点的指标数据。

请求格式:

http://your-prometheus-server/api/v1/query?query=<expression>&time=<timestamp>
  • <expression>: Prometheus查询表达式,例如 up{job="myjob"}
  • <timestamp>: (可选)查询的时间戳,Unix毫秒时间戳格式,如 1578810010000

示例:

curl 'http://your-prometheus-server/api/v1/query?query=up{job="prometheus"}'

2. 范围查询 (GET /api/v1/query_range)

用于查询一段时间范围内的数据。

请求格式:

http://your-prometheus-server/api/v1/query_range?query=<expression>&start=<start_timestamp>&end=<end_timestamp>&step=<duration>
  • <expression>: 同上
  • <start_timestamp>: 查询开始的Unix毫秒时间戳
  • <end_timestamp>: 查询结束的Unix毫秒时间戳
  • <duration>: 数据点之间的时间间隔,如 15s1m

示例:

curl 'http://your-prometheus-server/api/v1/query_range?query=http_requests_total&start=1609459200000&end=1609545600000&step=1m'

此例查询了从2021-01-01 00:00:00到2021-01-02 00:00:00,每分钟一个数据点的http_requests_total

参数编码与格式

在实际使用中,特别是当查询表达式包含特殊字符时,建议使用URL编码或通过 -G 参数与 --data-urlencode 结合使用curl命令,确保正确传递查询参数。

注意事项

  • 确保Prometheus服务器地址正确,并根据实际情况调整查询参数。
  • 查询大量数据或频繁查询可能会影响Prometheus服务器性能,合理安排查询计划。
  • 使用这些API时,遵循最佳安全实践,尤其是在公开网络环境中,考虑使用HTTPS并实施必要的认证机制。

TSDB Admin APIs

该API是为高级用户公开数据库功能的API。除非设置了--web.enable-admin-api,否则不会启用这些API。 Prometheus TSDB(Time Series Database)Admin APIs 提供了一系列工具来管理和维护Prometheus内部的TSDB。这些API允许用户执行各种任务,如清理旧数据、压缩数据块等。 以下是Prometheus TSDB Admin APIs的一些关键操作:

1. 清理过期数据 (POST /api/v1/admin/wal/trim)

用途: 清除WAL(Write-Ahead Log)中不再需要的日志文件。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/wal/trim'

2. 压缩数据块 (POST /api/v1/admin/tsdb/compact)

用途: 强制压缩数据块,减少磁盘空间占用。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/tsdb/compact'

3. 清空TSDB (POST /api/v1/admin/tsdb/clear)

用途: 清空整个TSDB中的数据。这是一个危险的操作,应该谨慎使用。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/tsdb/clear'

4. 删除过期数据 (POST /api/v1/admin/tsdb/delete_series)

用途: 根据给定的条件删除特定的序列。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/tsdb/delete_series' \
  --data-urlencode "match[]=up{job=\"expired\"}"

这里,我们删除了标签jobexpired的所有序列。

5. 删除快照 (POST /api/v1/admin/snapshot/delete)

用途: 删除指定的快照文件。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/snapshot/delete' \
  --data-urlencode "name=snapshot_name"

6. 快照TSDB (POST /api/v1/admin/snapshot)

用途: 创建TSDB的快照。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/snapshot' \
  --data-urlencode "name=snapshot_name"

7. 检查块完整性 (POST /api/v1/admin/tsdb/check_blocks)

用途: 检查所有块的完整性。

请求示例:

curl -X POST 'http://your-prometheus-server/api/v1/admin/tsdb/check_blocks'

注意事项

  • 上述API操作可能会对Prometheus服务器产生较大的影响,特别是在处理大量数据时。因此,在生产环境中执行这些操作时要格外小心。
  • 对于删除数据、清空TSDB等操作,务必确认清楚后再执行,因为这些操作通常是不可逆的。
  • 一些操作(如删除序列或清空TSDB)可能需要特殊的权限才能执行。

安全性

在使用这些API时,请确保采取适当的安全措施,例如使用HTTPS和认证机制。如果Prometheus服务器对外网开放,则尤其需要注意安全性问题。

如果您需要更详细的信息或具体版本的文档,请查阅Prometheus官方文档,以获得最新的API指南和使用说明。