Back to Details

prometheus-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prometheus API Skill

Prometheus API 技能

Query Prometheus monitoring systems via HTTP API at 
/api/v1
.
通过路径为
/api/v1
的HTTP API查询Prometheus监控系统。

Quick Reference

快速参考

Instant Query

即时查询

bash
curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'
bash
curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'

Range Query

范围查询

bash
curl 'http://<prometheus>:9090/api/v1/query_range?query=<promql>&start=<ts>&end=<ts>&step=<duration>'
bash
curl 'http://<prometheus>:9090/api/v1/query_range?query=<promql>&start=<ts>&end=<ts>&step=<duration>'

Response Format

响应格式

All responses return JSON:
json
{
  "status": "success" | "error",
  "data": <result>,
  "errorType": "<string>",
  "error": "<string>",
  "warnings": ["<string>"]
}
HTTP codes: 
400
(bad params), 
422
(expression error), 
503
(timeout).
所有响应均返回JSON格式：
json
{
  "status": "success" | "error",
  "data": <result>,
  "errorType": "<string>",
  "error": "<string>",
  "warnings": ["<string>"]
}
HTTP状态码：
400
（参数错误）、
422
（表达式错误）、
503
（请求超时）。

Query Endpoints

查询端点

EndpointPurposeKey Parameters
/api/v1/query
Instant query
query
, 
time
, 
timeout
, 
limit
/api/v1/query_range
Range query
query
, 
start
, 
end
, 
step
, 
timeout
, 
limit
/api/v1/format_query
Format PromQL
query
/api/v1/series
Find series by labels
match[]
, 
start
, 
end
, 
limit
/api/v1/labels
List label names
start
, 
end
, 
match[]
, 
limit
/api/v1/label/<name>/values
Label values
start
, 
end
, 
match[]
, 
limit
/api/v1/query_exemplars
Query exemplars
query
, 
start
, 
end
端点用途关键参数
/api/v1/query
即时查询
query
, 
time
, 
timeout
, 
limit
/api/v1/query_range
范围查询
query
, 
start
, 
end
, 
step
, 
timeout
, 
limit
/api/v1/format_query
格式化PromQL
query
/api/v1/series
通过标签查找时序
match[]
, 
start
, 
end
, 
limit
/api/v1/labels
列出标签名称
start
, 
end
, 
match[]
, 
limit
/api/v1/label/<name>/values
查询标签值
start
, 
end
, 
match[]
, 
limit
/api/v1/query_exemplars
查询示例数据
query
, 
start
, 
end

Metadata & Status Endpoints

元数据与状态端点

EndpointPurpose
/api/v1/targets
Target discovery status (
state=active|dropped|any
)
/api/v1/targets/metadata
Metric metadata from targets
/api/v1/metadata
All metric metadata
/api/v1/rules
Alerting/recording rules
/api/v1/alerts
Active alerts
/api/v1/alertmanagers
Alertmanager discovery
/api/v1/status/config
Current config YAML
/api/v1/status/flags
CLI flags
/api/v1/status/runtimeinfo
Runtime info
/api/v1/status/buildinfo
Build info
/api/v1/status/tsdb
TSDB cardinality stats
/api/v1/status/walreplay
WAL replay progress
端点用途
/api/v1/targets
目标发现状态（
state=active|dropped|any
）
/api/v1/targets/metadata
来自监控目标的指标元数据
/api/v1/metadata
所有指标元数据
/api/v1/rules
告警/记录规则
/api/v1/alerts
活跃告警
/api/v1/alertmanagers
Alertmanager发现状态
/api/v1/status/config
当前配置YAML
/api/v1/status/flags
CLI启动参数
/api/v1/status/runtimeinfo
运行时信息
/api/v1/status/buildinfo
构建信息
/api/v1/status/tsdb
TSDB基数统计
/api/v1/status/walreplay
WAL重放进度

Admin Endpoints (require 
--web.enable-admin-api
)

管理端点（需要开启
--web.enable-admin-api
参数）

EndpointMethodPurpose
/api/v1/admin/tsdb/snapshot
POSTCreate TSDB snapshot
/api/v1/admin/tsdb/delete_series
POSTDelete series (
match[]
, 
start
, 
end
)
/api/v1/admin/tsdb/clean_tombstones
POSTClean deleted data
端点请求方法用途
/api/v1/admin/tsdb/snapshot
POST创建TSDB快照
/api/v1/admin/tsdb/delete_series
POST删除时序（参数
match[]
, 
start
, 
end
）
/api/v1/admin/tsdb/clean_tombstones
POST清理已删除数据

Common PromQL Patterns

常用PromQL模式

promql
undefined
promql
undefined

Rate of counter over 5m

5分钟内计数器的增长率

rate(http_requests_total[5m])
rate(http_requests_total[5m])

Sum by label

按标签求和

sum by (job) (rate(http_requests_total[5m]))
sum by (job) (rate(http_requests_total[5m]))

Percentile from histogram

直方图百分位计算

histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

Filter by label

按标签过滤

up{job="prometheus", instance=~".*:9090"}
up{job="prometheus", instance=~".*:9090"}

Increase over time

时间段内的增长量

increase(http_requests_total[1h])
increase(http_requests_total[1h])

Average over time range

时间范围内的平均值

avg_over_time(process_cpu_seconds_total[5m])
undefined
avg_over_time(process_cpu_seconds_total[5m])
undefined

Result Types

结果类型

  • vector: 
    [{"metric": {...}, "value": [timestamp, "value"]}]
  • matrix: 
    [{"metric": {...}, "values": [[ts, "val"], ...]}]
  • scalar: 
    [timestamp, "value"]
  • string: 
    [timestamp, "string"]
  • vector: 
    [{"metric": {...}, "value": [timestamp, "value"]}]
  • matrix: 
    [{"metric": {...}, "values": [[ts, "val"], ...]}]
  • scalar: 
    [timestamp, "value"]
  • string: 
    [timestamp, "string"]

Scripts

脚本

Query script: 
scripts/prom_query.py
bash
undefined
查询脚本：
scripts/prom_query.py
bash
undefined

Instant query

即时查询

python scripts/prom_query.py http://localhost:9090 'up'
python scripts/prom_query.py http://localhost:9090 'up'

Range query

范围查询

python scripts/prom_query.py http://localhost:9090 'rate(http_requests_total[5m])'
--start '2024-01-01T00:00:00Z' --end '2024-01-01T01:00:00Z' --step '1m'
python scripts/prom_query.py http://localhost:9090 'rate(http_requests_total[5m])'
--start '2024-01-01T00:00:00Z' --end '2024-01-01T01:00:00Z' --step '1m'

Output: table, json, csv

输出格式：table、json、csv

python scripts/prom_query.py http://localhost:9090 'up' --format table

Health check: `scripts/prom_health.py`

```bash
python scripts/prom_health.py http://localhost:9090
python scripts/prom_query.py http://localhost:9090 'up' --format table

健康检查：`scripts/prom_health.py`

```bash
python scripts/prom_health.py http://localhost:9090

Detailed Reference

详细参考

For complete API documentation: references/api_reference.md
For PromQL functions: references/promql_functions.md
完整API文档：references/api_reference.md
PromQL函数说明：references/promql_functions.md