Prometheus API接口
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>
: 数据点之间的时间间隔,如15s
或1m
示例:
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\"}"
这里,我们删除了标签job
为expired
的所有序列。
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指南和使用说明。