Prometheus API 文档

📌 快速链接

📈 Grafana 可视化面板 📊 服务器监控面板 🔍 测试 API 查询 📡 实时指标 JSON

🌐 API 基础信息

项目	值
Base URL	`https://huodouai.com/prometheus`
API 版本	v1
认证方式	无需认证（只读查询）
响应格式	JSON
字符编码	UTF-8

⚠️ 安全限制：仅开放查询 API（/api/v1/*），管理 API（/admin、/-/reload、/-/quit、/tsdb 等）已禁止外部访问。

🔍 核心查询 API

1. 即时查询 (Instant Query)

GET /api/v1/query

在单个时间点评估 PromQL 表达式，返回即时查询结果。

参数	类型	必填	说明
query	string	是	PromQL 表达式
time	rfc3339/unix	否	查询时间戳，默认当前时间
timeout	duration	否	查询超时时间

# 查询所有采集目标状态
GET /prometheus/api/v1/query?query=up

# 查询 CPU 使用率
GET /prometheus/api/v1/query?query=100-(avg(rate(node_cpu_seconds_total{mode="idle"}[5m]))*100)

# 查询内存使用率
GET /prometheus/api/v1/query?query=(1-(node_memory_MemAvailable_bytes/node_memory_MemTotal_bytes))*100

2. 范围查询 (Range Query)

GET /api/v1/query_range

在一段时间范围内评估 PromQL 表达式，返回时间序列数据。

参数	类型	必填	说明
query	string	是	PromQL 表达式
start	rfc3339/unix	是	开始时间
end	rfc3339/unix	是	结束时间
step	duration\|float	是	查询步长（如 15s, 1m）

# 查询最近1小时 CPU 使用率趋势（每1分钟一个数据点）
GET /prometheus/api/v1/query_range?query=100-(avg(rate(node_cpu_seconds_total{mode="idle"}[5m]))*100)&start=1h ago&end=now&step=1m

📊 常用指标查询示例

系统资源指标

# CPU 使用率（百分比）
100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# 内存使用率（百分比）
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

# 磁盘使用率（根分区，百分比）
(1 - (node_filesystem_avail_bytes{mountpoint="/",fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes{mountpoint="/",fstype!~"tmpfs|overlay"})) * 100

# 系统负载（5分钟平均）
node_load5

# Swap 使用率（百分比）
(1 - (node_memory_SwapFree_bytes / node_memory_SwapTotal_bytes)) * 100

# 运行进程数
node_processes_pids

# 系统运行时间（秒）
node_time_seconds - node_boot_time_seconds

网络指标

# 网络接收速率（字节/秒，排除虚拟接口）
rate(node_network_receive_bytes_total{device!~"lo|docker.*|veth.*|br.*"}[5m])

# 网络发送速率（字节/秒）
rate(node_network_transmit_bytes_total{device!~"lo|docker.*|veth.*|br.*"}[5m])

# 网络错误包接收速率
rate(node_network_receive_errs_total[5m])

# 网络错误包发送速率
rate(node_network_transmit_errs_total[5m])

磁盘 IO 指标

# 磁盘读取速率（字节/秒）
rate(node_disk_read_bytes_total[5m])

# 磁盘写入速率（字节/秒）
rate(node_disk_written_bytes_total[5m])

# 磁盘 IO 等待时间
rate(node_disk_io_time_seconds_total[5m])

Nginx 指标（如已配置）

# Nginx 活跃连接数
nginx_connections_active

# Nginx 请求速率（请求/秒）
rate(nginx_http_requests_total[5m])

# Nginx 读取中连接数
nginx_connections_reading

# Nginx 写入中连接数
nginx_connections_writing

# Nginx 等待中连接数
nginx_connections_waiting

🎯 元数据查询 API

1. 查询标签值

GET /api/v1/label/<label_name>/values

返回指定标签的所有可能值。

# 查询所有实例名称
GET /prometheus/api/v1/label/instance/values

# 查询所有作业名称
GET /prometheus/api/v1/label/job/values

2. 查询序列

GET /api/v1/series

返回匹配指定标签选择器的时间序列列表。

# 查询所有 node_cpu 相关序列
GET /prometheus/api/v1/series?match[]=node_cpu_seconds_total

# 查询所有采集目标的 up 序列
GET /prometheus/api/v1/series?match[]=up

3. 查询目标状态

GET /api/v1/targets

返回 Prometheus 抓取目标的当前状态。

# 查看所有采集目标状态
GET /prometheus/api/v1/targets

# 仅查看活跃目标
GET /prometheus/api/v1/targets?state=active

4. 查询告警

GET /api/v1/alerts

返回当前触发的所有告警。

# 查看当前所有告警
GET /prometheus/api/v1/alerts

5. 查询告警规则

GET /api/v1/rules

返回当前加载的所有告警规则和记录规则。

# 查看所有规则
GET /prometheus/api/v1/rules

# 仅查看告警规则
GET /prometheus/api/v1/rules?type=alert

📈 响应格式说明

成功响应

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "up",
          "instance": "localhost:9090",
          "job": "prometheus"
        },
        "value": [1694448000, "1"]
      }
    ]
  }
}

错误响应

{
  "status": "error",
  "errorType": "bad_data",
  "error": "invalid parameter 'query': 1:0: parse error"
}

结果类型

resultType	说明
vector	即时向量，单个时间点的结果
matrix	范围向量，一段时间范围的结果
scalar	标量值
string	字符串值

💡 使用技巧

1. 时间格式

# RFC3339 格式
2026-09-11T17:00:00Z

# Unix 时间戳（秒）
1757578800

# 相对时间（仅用于查询，不用于 API 参数）
5m, 1h, 1d  # 在 PromQL 中使用

2. 常用 PromQL 函数

函数	说明	示例
rate()	计算速率	rate(node_cpu_seconds_total[5m])
avg()	平均值	avg(rate(...))
sum()	求和	sum(rate(...))
max()	最大值	max(node_memory_MemTotal_bytes)
min()	最小值	min(node_filesystem_avail_bytes)
increase()	增量	increase(node_network_receive_bytes_total[1h])
topk()	前N个	topk(5, rate(...))
bottomk()	后N个	bottomk(5, ...)

3. 标签过滤

# 精确匹配
node_cpu_seconds_total{mode="idle"}

# 正则匹配
node_network_receive_bytes_total{device=~"eth.*"}

# 排除匹配
node_network_receive_bytes_total{device!~"lo|docker.*"}

# 多条件组合
node_filesystem_avail_bytes{mountpoint="/",fstype!~"tmpfs|overlay"}