Prometheus API 使用了 JSON 格式的响应内容。 输入时间戳可以由 RFC3339 格式或者 Unix 时间戳提供，后面可选的小数位可以精确到亚秒级别。输出时间戳以 Unix 时间戳的方式呈现。所有的 API请求返回的格式均使用以下的 JSON 格式：
{
"status": "success" | "error",
"data": <data>,
// Only set if status is "error".
// additional data.
"errorType": "<string>",
"error": "<string>"
}
表达式查询
我们可以分别通过 /api/v1/query 和 /api/v1/query_range 查询 PromQL 表达式瞬时或者一定时间范围内的查询结果。当 API 调用成功后，Prometheus 会返回 JSON 格式的响应内容。
表达式查询结果会在 data 部分的 result 字段中返回以下的响应值。响应数据格式一共分为四种：
瞬时向量
通过使用 QUERY API 我们可以查询 PromQL 在特定时间点下的计算结果。
URL 请求参数：
query=<string> : PromQL 表达式。
time=<rfc3339 | unix_timestamp> : 用于指定用于计算 PromQL的时间戳。可选参数，默认情况下使用当前系统时间。
当 API 调用成功后，Prometheus 会返回 JSON 格式的响应内容，并且在 data 部分返回查询结果。data 部分格式如下：
{
"resultType":"vector",
"result": <value>
}
data 返回查询结果。value指的是查询结果数据，具体的格式取决于resultType，不同的结果类型，会有不同的结果数据格式。瞬时数据的resultType为vector。区间数据的resultType为matrix。当返回数据类型 resultType 为 vector 时，是一组时间序列，每个时间序列包含单个样本。result 响应格式如下：
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ]
},
...
]
这个 url 的查询结果为当前时间node_disk_io_now指标的查询结果。
Url="http://10.4.**.**:32075/api/v1/query?query=node_disk_io_now";
{
"status":"success",
"data":{
"resultType":"vector",
"result":[
{
"metric":{
"__name__":"node_disk_io_now",
"app":"prometheus",
"component":"node-exporter",
"device":"dm-0",
"instance":"10.4.**.**:9100",
"job":"kubernetes-endpoints",
"kubernetes_name":"prometheus-node-exporter",
"kubernetes_namespace":"monitoring"
},
"value":[
1542939382.369,
"0"
]
},
{
"metric":{
"__name__":"node_disk_io_now",
"app":"prometheus",
"component":"node-exporter",
"device":"dm-1",
"instance":"10.4.**.**:9100",
"job":"kubernetes-endpoints",
"kubernetes_name":"prometheus-node-exporter",
"kubernetes_namespace":"monitoring"
},
"value":[
1542939382.369,
"0"
]
}
]
}
}
注1：如果只是简单输入 http://ip:port/api/v1/query 会返回：
{"status":"error","errorType":"bad_data","error":"parse error at char 1: no expression found in input"}
注2：如果 time 参数缺省，则使用当前服务器时间。
注3：value 的值是时间戳和当前的值
区间向量
通过使用 QUERY_RANGE API 我们则可以直接查询 PromQL表达式在一段时间内返回的计算结果。
URL 请求参数：
query=<string> : PromQL 表达式。
start=<rfc3339 | unix_timestamp> : 起始时间戳。
end=<rfc3339 | unix_timestamp> : 结束时间戳。
step=<duration | float> : 查询时间步长，时间区间内每 step 秒执行一次。
当使用 QUERY_RANGE API 查询 PromQL 表达式时，返回结果一定是一个区间向量：
{
"resultType": "matrix",
"result": <value>
}
当返回数据类型 resultType 为 matrix 时，是一组时间序列，每个时间序列包含一段时间范围内的样本数据。result 响应格式如下：
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ]
},
...
]
这个 url 的查询结果为2018-11-22 17:20:23到2018-11-22 17:20:33这十秒内 ，指标http_requests_total的查询结果：
Url="http://10.4.54.31:32075/api/v1/query_range?query=http_requests_total&start=1542878423.447&end=1542878433.447&step=10s";
{
"status":"success",
"data":{
"resultType":"matrix",
"result":[
{
"metric":{
"__name__":"http_requests_total",
"code":"200",
"handler":"prometheus",
"instance":"node1",
"job":"kubernetes-nodes",
"method":"get"
},
"values":[
[
1542878423.447,
"86031"
],
[
1542878433.447,
"86032"
]
]
}
]
}
}
标量
当返回数据类型 resultType 为 scalar 时，是一个浮点型的数据值。result 响应格式如下：
[ <unix_time>, "<scalar_value>" ]
字符串
当返回数据类型 resultType 为 string 时，是一个简单的字符串值。result 响应格式如下：
[ <unix_time>, "<string_value>" ]
字符串类型的响应内容格式和标量相同。
元数据查询
标签选择器查询
我们可以通过 /api/v1/series 返回与特定标签集匹配的时间序列列表。
URL 请求参数：
match[]=<series_selector> : 表示标签选择器是 series_selector。必须至少提供一个 match[] 参数。
start=<rfc3339 | unix_timestamp> : 起始时间戳。
end=<rfc3339 | unix_timestamp> : 结束时间戳。
如我们查出所有job名为kubernetes-cadvisor的up指标和所有kubernetes_name名为kube-state-metrics的process_start_time_seconds指标：
Url="http://10.4.**.**:32075/api/v1/series?match[]=up{job=\"kubernetes-cadvisor\"}&match[]=process_start_time_seconds{kubernetes_name=\"kube-state-metrics\"}";
{
"status":"success",
"data":[
{
"__name__":"process_start_time_seconds",
"app":"prometheus",
"component":"node-exporter",
"instance":"10.4.**.**:9100",
"job":"kubernetes-endpoints",
"kubernetes_name":"prometheus-node-exporter",
"kubernetes_namespace":"monitoring"
},
{
"__name__":"up",
"app":"kube-state-metrics",
"instance":"10.233.102.139:8080",
"job":"kubernetes-endpoints",
"kubernetes_name":"kube-state-metrics",
"kubernetes_namespace":"monitoring"
}
]
}
标签值查询
我们可以通过 /api/v1/label/‘label_name’/values 返回带有指定标签的标签值列表。
如我们查出所有标签名为 job 的标签值:
Url="http://10.4.**.**:32075/api/v1/label/job/values";
{
"status":"success",
"data":[
"kubernetes-cadvisor",
"kubernetes-endpoints",
"kubernetes-nodes",
"kubernetes-pods"
]
}
==========================================================
PromQL简介
Prometheus 提供了一种功能表达式语言 PromQL，允许用户实时选择和汇聚时间序列数据。表达式的结果可以在浏览器中显示为图形，也可以显示为表格数据，或者由外部系统通过 HTTP API 调用。
时间序列过滤器
选择指标名称为 http_requests_total 的所有时间序列：
http_requests_total
可以通过向花括号 {} 里附加一组标签来进一步过滤时间序列。例如：选择指标名称为 http_requests_total，job 标签值为 prometheus，group 标签值为 canary 的时间序列：
http_requests_total{job="prometheus",group="canary"}
PromQL 还支持用户根据时间序列的标签匹配模式来对时间序列进行过滤，目前主要支持两种匹配模式：完全匹配和正则匹配。总共有以下几种标签匹配运算符：
= : 选择与提供的字符串完全相同的标签。
!= : 选择与提供的字符串不相同的标签。
=~ : 选择正则表达式与提供的字符串（或子字符串）相匹配的标签。
!~ : 选择正则表达式与提供的字符串（或子字符串）不匹配的标签。
例如：选择指标名称为 http_requests_total，环境为 staging、testing 或 development，HTTP 方法不为 GET 的时间序列：
http_requests_total{environment=~"staging|testing|development",method!="GET"}
我们还可以使用内置的 __name__ 标签来指定监控指标名称。例如：表达式 http_requests_total 等效于 {name=“http_requests_total”}。以下表达式选择指标名称以 job: 开头的所有指标：
{__name__=~"job:.*"}
区间向量过滤器
区间向量与瞬时向量的工作方式类似，唯一的差异在于在区间向量表达式中我们需要定义时间选择的范围，时间范围通过时间范围选择器 [] 进行定义，以指定应为每个返回的区间向量样本值中提取多长的时间范围。
时间范围通过数字来表示，单位可以使用以下其中之一的时间单位：
s - 秒
m - 分钟
h - 小时
d - 天
w - 周
y - 年
例如：选择在过去 5 分钟内指标名称为 http_requests_total，job 标签值为 prometheus 的所有时间序列：
http_requests_total{job="prometheus"}[5m]
时间位移操作
在瞬时向量表达式或者区间向量表达式中，都是以当前时间为基准。如果我们想查询5 分钟前的瞬时样本数据，或昨天一天的区间内的样本数据呢? 这个时候我们就可以使用位移操作，位移操作的关键字为 offset。
以下表达式返回相对于当前查询时间过去 5 分钟的 http_requests_total 值：
http_requests_total offset 5m