本文详细介绍了Prometheus的HTTP API，包括查询格式、表达式查询、范围查询、查询原始数据以及告警管理和TSDB管理等功能。通过实例展示了如何进行即时和范围查询，以及如何操作系列和标签数据。
非常惭愧，有两周多没更新文档了。一方面是工作较忙原因，另一方面是技术也需要实践，积累。今天接着咱们的技术文章分享，最近在研究Prometheus，后续也会有这方面的技术文件与大家分享哈。
在Prometheus里，是通过/api/v1接口来访问数据的。
一、格式介绍
1、API响应的格式是JSON，每个成功的API请求都会返回2xx状态代码。
2、API处理程序的无效请求将返回JSON错误对象以及以下HTTP响应代码之一：400 Bad Request 参数丢失或不正确；
422 Unprocessable Entity 当表达式不能执行时(RCFC49)；
503 Service Unavailable 当查询超时或中止时。。
3、JSON响应格式如下：1
2
3
4
5
6
7
8
9{
"status": "success" | "error",
"data": ,
// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "",
"error": ""
}
二、表达式查询
1. 立刻查询1GET /api/v1/query
URL 查询参数：query=: Prometheus表达式查询字符串.
time=: 指定查询的时间戳。可选的.
timeout=: 超时时间，可选的.
如果省略time参数，则使用当前服务器时间。
查询结果的数据部分具有以下格式：1
2
3
4{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result":
}
是指查询结果数据，具有不同的格式，具体取决于resultType。
下面使用时间表达式2018-07-18T02:10:51.781Z演示示例：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42[[email protected] ~]# curl -s 'http://localhost:9090/api/v1/query?query=up&time=2018-07-18T02:10:51.781Z'|python -mjson.tool
{
"data": {
"result": [
{
"metric": {
"__name__": "up",
"instance": "114.67.154.180:9090",
"job": "prometheus"
},
"value": [
1531879851.781,
"1"
]
},
{
"metric": {
"__name__": "up",
"instance": "mysql",
"job": "mysql"
},
"value": [
1531879851.781,
"1"
]
},
{
"metric": {
"__name__": "up",
"instance": "node_exporter",
"job": "centos_linux"
},
"value": [
1531879851.781,
"1"
]
}
],
"resultType": "vector"
},
"status": "success"
}
2. 范围查询1GET /api/v1/query_range
URL 查询参数：query=: Prometheus表达式查询字符串.
start=: 开始时间戳.
end=: 结束时间戳.
step=: 查询平率步长.
timeout=: 超时时间，可选的.
查询结果的数据部分具有以下格式：1
2
3
4{
"resultType": "matrix",
"result":
}
以下示例设置表达式在30秒范围内，查询分辨率为15秒：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72[[email protected] ~]# curl -s 'http://localhost:9090/api/v1/query_range?query=up&start=2018-07-18T02:10:30.781Z&end=2018-07-18T02:11:00.781Z&step=15s'|python -mjson.tool
{
"data": {
"result": [
{
"metric": {
"__name__": "up",
"instance": "114.67.154.180:9090",
"job": "prometheus"
},
"values": [
[
1531879830.781,
"1"
],
[
1531879845.781,
"1"
],
[
1531879860.781,
"1"
]
]
},
{
"metric": {
"__name__": "up",
"instance": "mysql",
"job": "mysql"
},
"values": [
[
1531879830.781,
"1"
],
[
1531879845.781,
"1"
],
[
1531879860.781,
"1"
]
]
},
{
"metric": {
"__name__": "up",
"instance": "node_exporter",
"job": "centos_linux"
},
"values": [
[
1531879830.781,
"1"
],
[
1531879845.781,
"1"
],
[
1531879860.781,
"1"
]
]
}
],
"resultType": "matrix"
},
"status": "success"
}
根据平率的次数返回相对应次数的结果。
三、查询原数据
按标签匹配器查找系列1GET /api/v1/series
URL 查询参数：match[]=: 重复的系列选择器参数，用于选择要返回的系列。必须至少提供一个match []参数.
start=: 开始时间戳.
end=: 结束时间戳.
查询结果的数据部分包含一个对象列表，这些对象包含标识每个系列的标签名称/值对。
以下示例返回匹配到up或process_start_time_seconds{job="prometheus"}的系列结果：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41[[email protected] ~]# curl -s -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'|python -mjson.tool
{
"data": [
{
"__name__": "process_start_time_seconds",
"instance": "114.67.154.180:9090",
"job": "prometheus"
},
{
"__name__": "process_start_time_seconds",
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
{
"__name__": "up",
"instance": "114.67.154.180:9090",
"job": "prometheus"
},
{
"__name__": "up",
"instance": "127.0.0.1:9090",
"job": "prometheus"
},
{
"__name__": "up",
"instance": "db-127.0.0.1",
"job": "mysql"
},
{
"__name__": "up",
"instance": "mysql",
"job": "mysql"
},
{
"__name__": "up",
"instance": "node_exporter",
"job": "centos_linux"
}
],
"status": "success"
}
1. 查询标签值1GET /api/v1/label//values
JSON响应的数据部分是字符串标签名称的列表。
此示例查询job标签的所有标签数据：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20[[email protected] ~]# curl -s http://localhost:9090/api/v1/label/job/values|python -mjson.tool
{
"data": [
"centos_linux",
"mysql",
"prometheus"
],
"status": "success"
}
[[email protected] ~]# curl -s http://localhost:9090/api/v1/label/instance/values|python -mjson.tool
{
"data": [
"114.67.154.180:9090",
"127.0.0.1:9090",
"db-127.0.0.1",
"mysql",
"node_exporter"
],
"status": "success"
}
四、Targets1GET /api/v1/targets
只返回当前活跃的targets：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58[[email protected] ~]# curl -s http://localhost:9090/api/v1/targets|python -mjson.tool
{
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "114.67.154.180:9104",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"instance": "mysql",
"job": "mysql"
},
"health": "up",
"labels": {
"instance": "mysql",
"job": "mysql"
},
"lastError": "",
"lastScrape": "2018-07-18T11:24:03.865575164+08:00",
"scrapeUrl": "http://114.67.154.180:9104/metrics"
},
{
"discoveredLabels": {
"__address__": "114.67.154.180:9090",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "prometheus"
},
"health": "up",
"labels": {
"instance": "114.67.154.180:9090",
"job": "prometheus"
},
"lastError": "",
"lastScrape": "2018-07-18T11:23:58.310157271+08:00",
"scrapeUrl": "http://114.67.154.180:9090/metrics"
},
{
"discoveredLabels": {
"__address__": "114.67.154.180:9100",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"instance": "node_exporter",
"job": "centos_linux"
},
"health": "up",
"labels": {
"instance": "node_exporter",
"job": "centos_linux"
},
"lastError": "",
"lastScrape": "2018-07-18T11:23:57.005890999+08:00",
"scrapeUrl": "http://114.67.154.180:9100/metrics"
}
]
},
"status": "success"
}
五、告警管理1GET /api/v1/alertmanagers
获取当前活跃的告警信息：1
2
3
4
5
6
7[[email protected] ~]# curl -s http://localhost:9090/api/v1/alertmanagers|python -mjson.tool
{
"data": {
"activeAlertmanagers": []
},
"status": "success"
}
六、TSDB Admin APIs
这些是为高级用户公开数据库功能的API。除非设置了–web.enable-admin-api，否则不会启用这些API。
1. 配置
在启动时加上如下参数，即可启动TSDB功能。1/usr/local/prometheus/prometheus --config.file=/usr/local/prometheus/prometheus.yml --storage.tsdb.path=/data/tsdb/ --web.enable-admin-api
2. 快照
快照会将所有当前数据的快照创建到TSDB数据目录下的快照/ - 中，并将该目录作为响应返回。1POST /api/v1/admin/tsdb/snapshot
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21[[email protected] ~]# curl -s -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot|python -mjson.tool
{
"data": {
"name": "20180718T034116Z-3b894be8bf313d55"
},
"status": "success"
}
[[email protected] ~]# ls -lh /data/tsdb/
总用量 4.0K
-rw------- 1 root root 6 7月 18 11:39 lock
drwxr-xr-x 7 root root 209 7月 18 11:41 snapshots
drwxr-xr-x 2 root root 20 7月 18 11:39 wal
[[email protected] ~]# ls -lh /data/tsdb/snapshots/
总用量 0
drwxr-xr-x 3 root root 40 7月 18 11:40 20180718T034030Z-612639dc1ae4d372
drwxr-xr-x 3 root root 40 7月 18 11:40 20180718T034055Z-d813bcea67bd979
drwxr-xr-x 3 root root 40 7月 18 11:40 20180718T034059Z-54e2ebca2b8fcde6
drwxr-xr-x 3 root root 40 7月 18 11:41 20180718T034106Z-3f6e502443f56c1
drwxr-xr-x 3 root root 40 7月 18 11:41 20180718T034116Z-3b894be8bf313d55
snapshots目录存储着每次快照的版本,以及快照日期。
3. Delete Series
v2.1中的新功能
如果成功，则返回2041POST /api/v1/admin/tsdb/delete_series
URL 查询参数：match[]=: 选择要删除的系列的重复标签匹配器参数。必须至少提供一个match []参数。.
start=: 开始时间戳.
end=: 结束时间戳.
注意，如果不提供开始和结束时间，将会删除match[]在数据库中匹配到的所有数据！1curl -XPOST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
4. Clean Tombstones
CleanTombstones从磁盘中删除已删除的数据并清理现有的逻辑删除。这可以在删除系列后使用以释放空间。
如果成功，则返回204。1POST /api/v1/admin/tsdb/clean_tombstones
这不需要参数或正文。1$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones
v2.1中的新功能.
文完。
扫一扫
180
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
