[TOC]

Prometheus 查詢語言

PromQL（Prometheus Query Language）是 Prometheus 自己開發(fā)的表達(dá)式語言血崭，語言表現(xiàn)力很豐富宰睡，內(nèi)置函數(shù)也很多。使用它可以對時序數(shù)據(jù)進(jìn)行篩選和聚合。

1. PromQL 語法

1.1 數(shù)據(jù)類型

PromQL 表達(dá)式計算出來的值有以下幾種類型：

• 瞬時向量 (Instant vector): 一組時序投蝉，每個時序只有一個采樣值
• 區(qū)間向量 (Range vector): 一組時序，每個時序包含一段時間內(nèi)的多個采樣值
• 標(biāo)量數(shù)據(jù) (Scalar): 一個浮點數(shù)
• 字符串 (String): 一個字符串，暫時未用

1.2 時序選擇器

1.2.1 瞬時向量選擇器

瞬時向量選擇器用來選擇一組時序在某個采樣點的采樣值懊蒸。

最簡單的情況就是指定一個度量指標(biāo)，選擇出所有屬于該度量指標(biāo)的時序的當(dāng)前采樣值悯搔。比如下面的表達(dá)式：

http_requests_total

可以通過在后面添加用大括號包圍起來的一組標(biāo)簽鍵值對來對時序進(jìn)行過濾骑丸。比如下面的表達(dá)式篩選出了 job 為 prometheus，并且 group 為 canary 的時序：

http_requests_total{job="prometheus", group="canary"}

匹配標(biāo)簽值時可以是等于妒貌，也可以使用正則表達(dá)式通危。總共有下面幾種匹配操作符：

• =：完全相等
• !=： 不相等
• =~： 正則表達(dá)式匹配
• !~： 正則表達(dá)式不匹配

下面的表達(dá)式篩選出了 environment 為 staging 或 testing 或 development灌曙，并且 method 不是 GET 的時序：

http_requests_total{environment=~"staging|testing|development",method!="GET"}

度量指標(biāo)名可以使用內(nèi)部標(biāo)簽 __name__ 來匹配菊碟，表達(dá)式 http_requests_total 也可以寫成 {__name__="http_requests_total"}。表達(dá)式 {__name__=~"job:.*"} 匹配所有度量指標(biāo)名稱以 job: 打頭的時序平匈。

1.2.2 區(qū)間向量選擇器

區(qū)間向量選擇器類似于瞬時向量選擇器框沟，不同的是它選擇的是過去一段時間的采樣值≡鎏浚可以通過在瞬時向量選擇器后面添加包含在 [] 里的時長來得到區(qū)間向量選擇器忍燥。比如下面的表達(dá)式選出了所有度量指標(biāo)為 http_requests_total 且 job 為 prometheus 的時序在過去 5 分鐘的采樣值。

http_requests_total{job="prometheus"}[5m]

說明：時長的單位可以是下面幾種之一：

• s：seconds
• m：minutes
• h：hours
• d：days
• w：weeks
• y：years

1.2.3 偏移修飾器

前面介紹的選擇器默認(rèn)都是以當(dāng)前時間為基準(zhǔn)時間隙姿，偏移修飾器用來調(diào)整基準(zhǔn)時間梅垄，使其往前偏移一段時間。偏移修飾器緊跟在選擇器后面，使用 offset 來指定要偏移的量队丝。比如下面的表達(dá)式選擇度量名稱為 http_requests_total 的所有時序在 5 分鐘前的采樣值靡馁。

http_requests_total offset 5m

下面的表達(dá)式選擇 http_requests_total 度量指標(biāo)在 1 周前的這個時間點過去 5 分鐘的采樣值。

http_requests_total[5m] offset 1w

2. PromQL 操作符

2.1 二元操作符

PromQL 的二元操作符支持基本的邏輯和算術(shù)運算机久，包含算術(shù)類臭墨、比較類和邏輯類三大類。

2.1.1 算術(shù)類二元操作符

算術(shù)類二元操作符有以下幾種：

• +：加
• -：減
• *：乘
• /：除
• %：求余
• ^：乘方

算術(shù)類二元操作符可以使用在標(biāo)量與標(biāo)量膘盖、向量與標(biāo)量胧弛，以及向量與向量之間。

二元操作符上下文里的向量特指瞬時向量侠畔，不包括區(qū)間向量结缚。

• 標(biāo)量與標(biāo)量之間，結(jié)果很明顯软棺，跟通常的算術(shù)運算一致红竭。
• 向量與標(biāo)量之間，相當(dāng)于把標(biāo)量跟向量里的每一個標(biāo)量進(jìn)行運算喘落，這些計算結(jié)果組成了一個新的向量茵宪。
• 向量與向量之間，會稍微麻煩一些揖盘。運算的時候首先會為左邊向量里的每一個元素在右邊向量里去尋找一個匹配元素（匹配規(guī)則后面會講）眉厨，然后對這兩個匹配元素執(zhí)行計算，這樣每對匹配元素的計算結(jié)果組成了一個新的向量兽狭。如果沒有找到匹配元素，則該元素丟棄鹿蜀。

2.1.2 比較類二元操作符

比較類二元操作符有以下幾種：

• == (equal)
• != (not-equal)
• > (greater-than)
• < (less-than)
• >= (greater-or-equal)
• <= (less-or-equal)

比較類二元操作符同樣可以使用在標(biāo)量與標(biāo)量箕慧、向量與標(biāo)量，以及向量與向量之間茴恰。默認(rèn)執(zhí)行的是過濾颠焦，也就是保留值。

也可以通過在運算符后面跟 bool 修飾符來使得返回值 0 和 1往枣，而不是過濾伐庭。

• 標(biāo)量與標(biāo)量之間，必須跟 bool 修飾符分冈，因此結(jié)果只可能是 0（false） 或 1（true）圾另。
• 向量與標(biāo)量之間，相當(dāng)于把向量里的每一個標(biāo)量跟標(biāo)量進(jìn)行比較雕沉，結(jié)果為真則保留集乔，否則丟棄。如果后面跟了 bool 修飾符坡椒，則結(jié)果分別為 1 和 0扰路。
• 向量與向量之間尤溜，運算過程類似于算術(shù)類操作符，只不過如果比較結(jié)果為真則保留左邊的值（包括度量指標(biāo)和標(biāo)簽這些屬性）汗唱，否則丟棄宫莱，沒找到匹配也是丟棄。如果后面跟了 bool 修飾符哩罪，則保留和丟棄時結(jié)果相應(yīng)為 1 和 0授霸。

2.1.3 邏輯類二元操作符

邏輯操作符僅用于向量與向量之間。

• and：交集
• or：合集
• unless：補集

具體運算規(guī)則如下：

• vector1 and vector2 的結(jié)果由在 vector2 里有匹配（標(biāo)簽鍵值對組合相同）元素的 vector1 里的元素組成识椰。
• vector1 or vector2 的結(jié)果由所有 vector1 里的元素加上在 vector1 里沒有匹配（標(biāo)簽鍵值對組合相同）元素的 vector2 里的元素組成绝葡。
• vector1 unless vector2 的結(jié)果由在 vector2 里沒有匹配（標(biāo)簽鍵值對組合相同）元素的 vector1 里的元素組成。

2.1.4 二元操作符優(yōu)先級

PromQL 的各類二元操作符運算優(yōu)先級如下：

1. ^
2. *, /, %
3. +, -
4. ==, !=, <=, <, >=, >
5. and, unless
6. or

2.2 向量匹配

前面算術(shù)類和比較類操作符都需要在向量之間進(jìn)行匹配腹鹉。共有兩種匹配類型藏畅，one-to-one 和 many-to-one / one-to-many。

2.2.1 One-to-one 向量匹配

這種匹配模式下功咒，兩邊向量里的元素如果其標(biāo)簽鍵值對組合相同則為匹配愉阎，并且只會有一個匹配元素×Ψ埽可以使用 ignoring 關(guān)鍵詞來忽略不參與匹配的標(biāo)簽榜旦，或者使用 on 關(guān)鍵詞來指定要參與匹配的標(biāo)簽。語法如下：

<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>

比如對于下面的輸入：

method_code:http_errors:rate5m{method="get", code="500"}  24
method_code:http_errors:rate5m{method="get", code="404"}  30
method_code:http_errors:rate5m{method="put", code="501"}  3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21

method:http_requests:rate5m{method="get"}  600
method:http_requests:rate5m{method="del"}  34
method:http_requests:rate5m{method="post"} 120

執(zhí)行下面的查詢：

method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

得到的結(jié)果為：

{method="get"}  0.04            //  24 / 600
{method="post"} 0.05            //   6 / 120

也就是每一種 method 里 code 為 500 的請求數(shù)占總數(shù)的百分比景殷。由于 method 為 put 和 del 的沒有匹配元素所以沒有出現(xiàn)在結(jié)果里溅呢。

2.2.2 Many-to-one / one-to-many 向量匹配

這種匹配模式下，某一邊會有多個元素跟另一邊的元素匹配猿挚。這時就需要使用 group_left 或 group_right 組修飾符來指明哪邊匹配元素較多咐旧，左邊多則用 group_left，右邊多則用 group_right绩蜻。其語法如下：

<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>

組修飾符只適用于算術(shù)類和比較類操作符铣墨。

對于前面的輸入，執(zhí)行下面的查詢：

method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

將得到下面的結(jié)果：

{method="get", code="500"}  0.04            //  24 / 600
{method="get", code="404"}  0.05            //  30 / 600
{method="post", code="500"} 0.05            //   6 / 120
{method="post", code="404"} 0.175           //  21 / 120

也就是每種 method 的每種 code 錯誤次數(shù)占每種 method 請求數(shù)的比例办绝。這里匹配的時候 ignoring 了 code伊约，才使得兩邊可以形成 Many-to-one 形式的匹配。由于左邊多孕蝉，所以需要使用 group_left 來指明屡律。

Many-to-one / one-to-many 過于高級和復(fù)雜，要盡量避免使用昔驱。很多時候通過 ignoring 就可以解決問題疹尾。

2.3 聚合操作符

PromQL 的聚合操作符用來將向量里的元素聚合得更少。總共有下面這些聚合操作符：

• sum：求和
• min：最小值
• max：最大值
• avg：平均值
• stddev：標(biāo)準(zhǔn)差
• stdvar：方差
• count：元素個數(shù)
• count_values：等于某值的元素個數(shù)
• bottomk：最小的 k 個元素
• topk：最大的 k 個元素
• quantile：分位數(shù)

聚合操作符語法如下：

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

其中 without 用來指定不需要保留的標(biāo)簽（也就是這些標(biāo)簽的多個值會被聚合）纳本，而 by 正好相反窍蓝，用來指定需要保留的標(biāo)簽（也就是按這些標(biāo)簽來聚合）。

下面來看幾個示例：

sum(http_requests_total) without (instance)

http_requests_total 度量指標(biāo)帶有 application繁成、instance 和 group 三個標(biāo)簽吓笙。上面的表達(dá)式會得到每個 application 的每個 group 在所有 instance 上的請求總數(shù)。效果等同于下面的表達(dá)式：

sum(http_requests_total) by (application, group)

下面的表達(dá)式可以得到所有 application 的所有 group 的所有 instance 的請求總數(shù)巾腕。

sum(http_requests_total)

3. 函數(shù)

Prometheus 內(nèi)置了一些函數(shù)來輔助計算面睛，下面介紹一些典型的。

• abs()：絕對值
• sqrt()：平方根
• exp()：指數(shù)計算
• ln()：自然對數(shù)
• ceil()：向上取整
• floor()：向下取整
• round()：四舍五入取整
• delta()：計算區(qū)間向量里每一個時序第一個和最后一個的差值
• sort()：排序