Fork me on GitHub

Prometheus系列之《HTTP-API的使用》

非常惭愧,有两周多没更新文档了。一方面是工作较忙原因,另一方面是技术也需要实践,积累。今天接着咱们的技术文章分享,最近在研究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": <data>,

// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "<string>",
"error": "<string>"
}

二、表达式查询

1. 立刻查询

1
GET /api/v1/query

URL 查询参数:

  • query=<string>: Prometheus表达式查询字符串.
  • time=<rfc3339 | unix_timestamp>: 指定查询的时间戳。可选的.
  • timeout=<duration>: 超时时间,可选的.

如果省略time参数,则使用当前服务器时间。

查询结果的数据部分具有以下格式:

1
2
3
4
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}

是指查询结果数据,具有不同的格式,具体取决于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
[root@tanshuai ~]# 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. 范围查询

1
GET /api/v1/query_range

URL 查询参数:

  • query=<string>: Prometheus表达式查询字符串.
  • start=<rfc3339 | unix_timestamp>: 开始时间戳.
  • end=<rfc3339 | unix_timestamp>: 结束时间戳.
  • step=<duration>: 查询平率步长.
  • timeout=<duration>: 超时时间,可选的.

查询结果的数据部分具有以下格式:

1
2
3
4
{
"resultType": "matrix",
"result": <value>
}

以下示例设置表达式在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
[root@tanshuai ~]# 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"
}

根据平率的次数返回相对应次数的结果。

三、查询原数据

按标签匹配器查找系列

1
GET /api/v1/series

URL 查询参数:

  • match[]=<series_selector>: 重复的系列选择器参数,用于选择要返回的系列。必须至少提供一个match []参数.
  • start=<rfc3339 | unix_timestamp>: 开始时间戳.
  • end=<rfc3339 | unix_timestamp>: 结束时间戳.

查询结果的数据部分包含一个对象列表,这些对象包含标识每个系列的标签名称/值对。

以下示例返回匹配到upprocess_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
[root@tanshuai ~]# 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. 查询标签值

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

JSON响应的数据部分是字符串标签名称的列表。

此示例查询job标签的所有标签数据:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[root@tanshuai ~]# curl -s http://localhost:9090/api/v1/label/job/values|python -mjson.tool
{
"data": [
"centos_linux",
"mysql",
"prometheus"
],
"status": "success"
}
[root@tanshuai ~]# 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"
}

四、Targets

1
GET /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
[root@tanshuai ~]# 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"
}

五、告警管理

1
GET /api/v1/alertmanagers

获取当前活跃的告警信息:

1
2
3
4
5
6
7
[root@tanshuai ~]#  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数据目录下的快照/ - 中,并将该目录作为响应返回。

1
POST /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
[root@tanshuai ~]# curl -s -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot|python -mjson.tool
{
"data": {
"name": "20180718T034116Z-3b894be8bf313d55"
},
"status": "success"
}

[root@tanshuai ~]# 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

[root@tanshuai ~]# 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中的新功能

如果成功,则返回204

1
POST /api/v1/admin/tsdb/delete_series

URL 查询参数:

  • match[]=<series_selector>: 选择要删除的系列的重复标签匹配器参数。必须至少提供一个match []参数。.
  • start=<rfc3339 | unix_timestamp>: 开始时间戳.
  • end=<rfc3339 | unix_timestamp>: 结束时间戳.

注意,如果不提供开始和结束时间,将会删除match[]在数据库中匹配到的所有数据!

1
curl -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。

1
POST /api/v1/admin/tsdb/clean_tombstones

这不需要参数或正文。

1
$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

v2.1中的新功能.

文完。

-------------本文结束感谢您的阅读-------------