Prometheus：在 HTTP API 中使用 PromQL

ゝ一世哀愁。 2022-12-05 10:27 483阅读 0赞

**目录**

概述

API 响应格式

表达式查询

瞬时数据查询

区间数据查询

查询元数据

通过标签选择器查找时间序列

查询标签值

响应数据格式

区间向量

瞬时向量

标量

字符串

--------------------

# 概述 #

Prometheus是一套使用Go语言进行编写的监控工具，专注于基础监控，默认仅保留15天的监控数据，15天的监控数据，已经足够运维人员去排查和分析运维故障。Prometheus有专门的PQL语言，可以对采集上来的指标进行多维度、函数分析，具有高度的指标定制化能力。

> Prometheus 当前稳定的 HTTP API 可以通过 `/api/v1` 访问。

# API 响应格式 #

Prometheus API 使用了 JSON 格式的响应内容。 当 API 调用成功后将会返回 `2xx` 的 HTTP 状态码。

反之，当 API 调用失败时可能返回以下几种不同的 HTTP 状态码：

>  *  `404 Bad Request` ：当参数错误或者缺失时。
>  *  `422 Unprocessable Entity` : 当表达式无法执行时。
>  *  `503 Service Unavailable` : 当请求超时或者被中断时。

所有的 API 请求返回的格式均使用以下的 JSON 格式：

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

输入时间戳可以由 [RFC3339][] 格式或者 Unix 时间戳提供，后面可选的小数位可以精确到亚秒级别。

输出时间戳以 Unix 时间戳的方式呈现。

查询参数名称可以用中括号 `[]` 重复次数。`<series_selector>` 占位符提供像 `http_requests_total` 或者 `http_requests_total{method=~"(GET|POST)"}` 的 Prometheus 时间序列选择器，并需要在 URL 中编码传输。

`<duration>` 占位符指的是 `[0-9]+[smhdwy]` 形式的 Prometheus 持续时间字符串。例如：5m 表示 5 分钟的持续时间。

`<bool>` 提供布尔值（字符串 true 和 false）。

# 表达式查询 #

> 通过 HTTP API 我们可以分别通过 `/api/v1/query` 和 `/api/v1/query_range` 查询 PromQL 表达式当前或者一定时间范围内的计算结果。

# 瞬时数据查询 #

> 一个时间点某指标的值

通过使用 `QUERY API` 我们可以查询 PromQL **在特定时间点下的计算结果**。

GET /api/v1/query

URL 请求参数：

*  `query=<string>` : PromQL 表达式。
 *  `time=<rfc3339 | unix_timestamp>` : 用于指定用于计算 PromQL 的时间戳。可选参数，默认情况下使用当前系统时间。
 *  `timeout=<duration>` : 超时设置。可选参数，默认情况下使用全局设置的参数 `-query.timeout`。

如果 `time` 参数缺省，则使用当前服务器时间。

当 API 调用成功后，Prometheus 会返回 JSON 格式的响应内容，格式如上小节所示。并且在 data 部分返回查询结果。data 部分格式如下：

{
    "resultType": "matrix" | "vector" | "scalar" | "string",
    "result": <value>
    }

`<value>` 指的是查询结果数据，具体的格式取决于 `resultType`，不同的结果类型，会有不同的结果数据格式。参考 [响应数据格式][Link 1]。

例如使用以下表达式查询表达式 `up` 在时间点 `2015-07-01T20:10:51.781Z` 的计算结果：

$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z' 
    {
    	"status": "success",
    	"data": {
    		"resultType": "vector",
    		"result": [{
    				"metric": {
    					"__name__": "up",
    					"job": "prometheus",
    					"instance": "localhost:9090"
    				},
    				"value": [1435781451.781, "1"]
    			},
    			{
    				"metric": {
    					"__name__": "up",
    					"job": "node",
    					"instance": "localhost:9100"
    				},
    				"value": [1435781451.781, "0"]
    			}
    		]
    	}
    }

# 区间数据查询 #

指的是在某段时间内metric的取值，每个时间点都包含一系列的值

> **指标类型**
> 
>  *  Gauge，度量值，这个值是有变化的，如CPU使用率，有高有低
>  *  Counter，累计值，从程序开始，只增不减，如开机运行时长

使用 QUERY\_RANGE API 我们则可以直接查询 PromQL 表达式在一段时间返回内的计算结果。

GET /api/v1/query\_range

URL 请求参数：

>  *  `query=<string>` : PromQL 表达式。
>  *  `start=<rfc3339 | unix_timestamp>` : 起始时间戳。
>  *  `end=<rfc3339 | unix_timestamp>` : 结束时间戳。
>  *  `step=<duration | float>` : 查询时间步长，时间区间内每 step 秒执行一次。
>  *  `timeout=<duration>` : 超时设置。可选参数，默认情况下使用全局设置的参数 `-query.timeout`。

当使用 QUERY\_RANGE API 查询 PromQL 表达式时，返回结果一定是一个区间向量：

{
    "resultType": "matrix",
    "result": <value>
    }

> 注意：
> 
> **在 QUERY\_RANGE API 中 PromQL 只能使用瞬时向量选择器类型的表达式。**

对于 `<value>` 占位符的格式，详见 [区间向量查询结果格式][Link 2]。

例如使用以下表达式查询表达式 `up` 在 30 秒范围内以 15 秒为间隔计算 PromQL 表达式的结果。

$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
     {
    	"status": "success",
    	"data": {
    		"resultType": "matrix",
    		"result": [{
    				"metric": {
    					"__name__": "up",
    					"job": "prometheus",
    					"instance": "localhost:9090"
    				},
    				"values": [
    					[1435781430.781, "1"],
    					[1435781445.781, "1"],
    					[1435781460.781, "1"]
    				]
    			},
    			{
    				"metric": {
    					"__name__": "up",
    					"job": "node",
    					"instance": "localhost:9091"
    				},
    				"values": [
    					[1435781430.781, "0"],
    					[1435781445.781, "0"],
    					[1435781460.781, "1"]
    				]
    			}
    		]
    	}
    }

# 查询元数据 #

## 通过标签选择器查找时间序列 ##

以下表达式**返回与特定标签集匹配的时间序列列表**：

GET /api/v1/series

URL 请求参数：

>  *  `match[]=<series_selector>` : 表示标签选择器是 `series_selector`。**必须至少提供一个 `match[]` 参数。**
>  *  `start=<rfc3339 | unix_timestamp>` : 起始时间戳。
>  *  `end=<rfc3339 | unix_timestamp>` : 结束时间戳。

返回结果的 data 部分，是由 key-value 键值对的对象列表组成的。

例如使用以下表达式查询表达式 `up` 或 `process_start_time_seconds{job="prometheus"}` 的计算结果：

$ curl - g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}' 
    
    {
    	"status": "success",
    	"data": [
           {
    			"__name__": "up",
    			"job": "prometheus",
    			"instance": "localhost:9090"
    		},
    		{
    			"__name__": "up",
    			"job": "node",
    			"instance": "localhost:9091"
    		},
    		{
    			"__name__": "process_start_time_seconds",
    			"job": "prometheus",
    			"instance": "localhost:9090"
    		}
    	]
    }

## 查询标签值 ##

> 一个指标，可以包括多个标签（label），用来指示这个指标的具体表示信息，起到对一个指标的修饰作用，标签可使用正则表达式进行匹配。

下面这个例子返回了**带有指定标签的的时间序列列表**：

GET /api/v1/label/<label\_name>/values

返回结果的 `data` 部分是一个标签值列表。例如，以下表达式返回结果的 data 部分是标签名称为 `job` 的所有标签值：

$ curl http: //localhost:9090/api/v1/label/job/values
    	{
    		"status": "success",
    		"data": [
    			"node",
    			"prometheus"
    		]
    	}

标签支持正则表达式，使用=~(Rexp)，如node\_cpu\_seconds\_total\{mode=\\~"idle|iowait"\}，类似于SQL语句。

select * from node_cpu_seconds_total where mode = 'idle' or mode = 'iowait'

标签过滤器可以有多个，用逗号进行隔开，相当于执行了where … and … 语句，如node\_cpu\_seconds\_total\{mode="idle",cpu='0'\}，类似于SQL语句。

select * from node_cpu_seconds_total where mode = 'idle' and cpu = '0'

配合标签，我们可以精确的找到我们需要用于展示或者计算的指标值。

#  响应数据格式 #

表达式查询结果可能会在 data 部分的 `result` 字段中返回以下的响应值。其中 `<sample_value>` 占位符是数值样本值。由于 json 不支持特殊浮点值，例如：`NaN`, `Inf`, 和 `-Inf`，所以样本值将会作为字符串（而不是原始数值）来进行传输。

## 区间向量 ##

当返回数据类型 resultType 为 `matrix` 时，`result` 响应格式如下：

[{
    		"metric": {
    			"<label_name>": "<label_value>",
    			...
    		},
    		"values": [
    			[ < unix_time > , "<sample_value>"], ...
    		]
    	},
    	...
    ]

其中 `metrics` 表示当前时间序列的特征维度，`values` 包含当前事件序列的一组样本。

## 瞬时向量 ##

当返回数据类型 resultType 为 `vector` 时，`result` 响应格式如下：

[{
    		"metric": {
    			"<label_name>": "<label_value>",
    			...
    		},
    		"value": [ < unix_time > , "<sample_value>"]
    	},
    	...
    ]

其中 `metrics` 表示当前时间序列的特征维度，`values` 包含当前事件序列的一组样本。

## 标量 ##

当返回数据类型 resultType 为 `scalar` 时，`result` 响应格式如下：

[ <unix_time>, "<scalar_value>" ]

由于标量不存在时间序列一说，因此 `result` 表示为当前系统时间一个标量的值。

## 字符串 ##

当返回数据类型 resultType 为 `string` 时，`result` 响应格式如下：

[ <unix_time>, "<string_value>" ]

字符串类型的响应内容格式和标量相同。

# **偏移量offset** #

指标通过偏移量offset关键字，可以查询相对于当前时间点之前的数据，默认获取当前最新数据，如node\_cpu\_seconds\_total offset 5m，获取5分钟前该指标的数据。

# 常见表达式 #

## **基本函数** ##

### **sum** ###

*  sum函数可以对瞬时向量进行求和，如sum(node\_cpu\_seconds\_total)，将统计所有值的总和。类似于select sum(value) from node\_cpu\_seconds\_total
 *  sum后面可以加 by 关键字，表示通过那个维度进行数据统计求和，如sum by (mode) (node\_cpu\_seconds\_total) 类似于 select sum(vaule) from node\_cpu\_seconds\_total group by mode

### **min** ###

*  min函数可以对瞬时向量进行求最小值，min(node\_cpu\_seconds\_total)。类似于select min(value) from node\_cpu\_seconds\_total
 *  同样，也支持by关键字，进行某个维度的求最小值

### **max** ###

*  max函数可以对瞬时向量进行求最大值，max(node\_cpu\_seconds\_total)。类似于select max(value) from node\_cpu\_seconds\_total
 *  同样，也支持by关键字，进行某个维度的求最大值

### **avg** ###

*  avg函数可以对瞬时向量进行求平均avg(node\_cpu\_seconds\_total)。类似于select avg(value) from node\_cpu\_seconds\_total
 *  同样，也支持by关键字，进行某个维度的求最均值

### **count** ###

*  count函数可以对瞬时向量个数求总数，如count(node\_cpu\_seconds\_total)类似于select count(\*) from node\_cpu\_seconds\_total
 *  同样，也支持by关键字，进行某个维度的求最总个数

### **topk** ###

*  topk函数可以对瞬时向量的值从大到小进行排列，并获取前N个值，需要传入两个参数，一个是N，一个是指标，如topk(5,node\_cpu\_seconds\_total)，类似于select \* from (select \* from node\_cpu\_seconds\_total order by value desc) where rownum<=5
 *  同样，也支持by关键字，进行某个维度进行计算

### **bottomk** ###

*  同topk相反，这里不再赘述。

## **计算** ##

### **+ 加法运算** ###

*  指标支持加法运算，一个即时向量，由于标签值不一致，所以会有多个值，这些值可以跟另外一个即时向量进行相加，这里的相加要保持一个原则，那就是需要具有同一个标签值的才会相加。node\_cpu\_seconds\_total + node\_cpu\_seconds\_total，这相当于所有值都多加一个原来的值，总体的值的数量是保持不变的。
 *  相加的两个瞬时向量个数不一致情况：node\_cpu\_seconds\_total和node\_cpu\_seconds\_total\{mode="idle"\}，后者经过过滤后，数量上明显比第一个少，此时输出的结果个数同过滤后数量少的个数一致。
 *  两个即时向量都不具备有同样的标签值情况：如node\_cpu\_seconds\_total + node\_memory\_Active\_bytes，此时由于没有任何一个值具有相同的标签值，所以结果为nodata，此时我们可以用ignoring关键字，对标签值进行忽略，使他们可以进行相加。由于node\_cpu\_seconds\_total比node\_memory\_Active\_bytes多了cpu和mode标签，所以node\_cpu\_seconds\_total数量个数一般大于node\_memory\_Active\_bytes个数，所以需要使用group\_left，node\_cpu\_seconds\_total + ignoring(cpu,mode) group\_left node\_memory\_Active\_bytes，结果集以左边的node\_cpu\_seconds\_total个数为准，如果加号两个即时向量位置相反，则可以使用group\_right，如node\_memory\_Active\_bytes + ignoring(cpu,mode) group\_right node\_cpu\_seconds\_total

### **- 减法运算** ###

*  类似加法运算

### **\* 乘法运算** ###

*  类似加法运算

### **/ 除法运算** ###

*  类似加法运算

## **逻辑比较** ##

### **== 判断是否相等** ###

*  ==用于判断左右两边的值是否相等，如果相等则为1（true），如果不等则为0（false），如node\_cpu\_seconds\_total ==BOOL 0 判断是否有存在0值

### **!= 判断是否不等** ###

*  类似==

### **>= 大于等于** ###

*  >=用于判断左边的值是否大于或等于右边的值，如果满足，则为1（true），如果不满足则为0（false）

### **<=小于等于** ###

*  类似大于等于

### **> 大于** ###

*  类似大于等于

### **< 小于** ###

*  类似大于等于

## **数据集操作** ##

### **and** ###

*  对多个指标的数据集进行标签判断，获取两个指标集具有共同的标签的值node\_cpu\_seconds\_total and node\_cpu\_guest\_seconds\_total，类似sql select \* from node\_cpu\_seconds\_total a,node\_cpu\_guest\_seconds\_total b where a.cpu = b.cpu and a.instance = b.instance and a.job=b.job and a.mode = b.mode

### **or** ###

*  对多个指标集数据进行展示，如果有标签重复，则仅显示其中一个标签的值。

### **unless** ###

*  对多个指标的数据集进行标签判断，获取两个指标集不具有共同的标签的值，结果集以最左边为准，如node\_memory\_Active\_bytes unless node\_cpu\_seconds\_total和node\_cpu\_seconds\_total unless node\_memory\_Active\_bytes结果是不一样的。

## **用于即时向量的函数** ##

### **abs** ###

*  abs返回即时向量的绝对值

### **absent** ###

*  absent用于检测即时向量中，某个标签是否存在，如果不存在，则value为1，如检查标签为node\_arp\_entries\{instance=“localhost:9100”\}是否存在有元素，如果存在则返回nodata，如果不存在value则为1
 *  常用于检测指标是否丢失。

### **ceil** ###

*  用于将浮点数向上化为最接近的一个整数，如值为0.1，则为向上取整，成为1。

### **floor** ###

*  用于将浮点数向下化为最接近的一个整数，如值为0.1，则为向下取整，成为0。

### **clamp\_max** ###

*  该函数需要两个参数，一个是向量，另外一个是封顶值，如果一个向量的值超过该封顶值，该向量的值则为封顶值。

### **clamp\_min** ###

该函数需要两个参数，一个是向量，另外一个是触底值，如果一个向量的值超过该触底值，该向量的值则为触底值。

## **用于区间向量的函数** ##

区间向量的函数执行完成后，便成为了即时向量。

### **absent\_over\_time** ###

*  absent\_over\_time用于检测在给定的区间向量中，是否存在有元素，如果没有则value为1。

### **changes** ###

*  返回给定的区间向量中，对比于当前值，发生变化的元素的数量。

### **delta** ###

*  返回区间向量中，第一个元素和最后一个元素之间的变化值，时间区间也参与算法计算，所以即时第一个元素和最后一个元素均为整数，该值也未必是整数。
 *  须作用在gauge类型的指标

### **deriv** ###

*  返回区间向量中，满足线性规律的每秒变化值
 *  须作用在gauge类型的指标

### **idelta** ###

*  该函数计算区间向量间，最后两个元素的差值，如果区间内没有两个元素，则返回nodata
 *  须作用在gauge类型的指标

### **irate** ###

*  该函数计算区间向量间，最后两个元素的差值，并且除以区间的秒数，如果区间内没有两个元素，则返回nodata。

### **<aggregation>\_over\_time** ###

*  该函数技术按区间向量的最大（max）、最小（min）、平均（avg）、求和（sum）、求总数（）等汇聚值。

[RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
[Link 1]: https://www.yangcs.net/prometheus/4-prometheus/api.html#%E5%93%8D%E5%BA%94%E6%95%B0%E6%8D%AE%E6%A0%BC%E5%BC%8F
[Link 2]: https://www.yangcs.net/prometheus/4-prometheus/api.html#%E5%8C%BA%E9%97%B4%E5%90%91%E9%87%8F