Prometheus PromQL 查詢基礎(chǔ)即時查詢與范圍查詢、選擇器、時間修飾符與字面量詳解【免費(fèi)下載鏈接】prometheusThe Prometheus monitoring system and time series database.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pr/prometheus本篇技術(shù)指南以 Prometheus 官方文檔《Querying basics》為主體系統(tǒng)講解 PromQLPrometheus Query Language的數(shù)據(jù)類型、字面量、時間序列選擇器、offset與時間修飾符、子查詢以及查詢引擎的時間語義。讀完本文你將能夠正確編寫即時查詢與范圍查詢、理解 lookback/staleness 機(jī)制的底層行為并結(jié)合開源倉庫中的解析器與引擎源碼定位查詢行為背后的實(shí)現(xiàn)依據(jù)。兩種查詢形態(tài)即時查詢與范圍查詢Prometheus 提供了一套函數(shù)式查詢語言 PromQL讓用戶能夠?qū)崟r地選擇與聚合時間序列數(shù)據(jù)。向 Prometheus 發(fā)送查詢請求時請求可以是即時查詢instant query在單一時間點(diǎn)求值范圍查詢range query在起止時間之間以固定步長step間隔多次求值。兩種情形下 PromQL 的工作方式完全一致范圍查詢本質(zhì)上就是在不同時間戳上多次執(zhí)行的即時查詢。在 Prometheus Web UI 中Table 頁簽對應(yīng)即時查詢Graph 頁簽對應(yīng)范圍查詢。其他程序則可以通過 HTTP API 獲取任意 PromQL 表達(dá)式的求值結(jié)果。樣本Samples浮點(diǎn)樣本與原生直方圖樣本PromQL 在某個時間戳返回的樣本值可能是浮點(diǎn)數(shù)float也可能是**原生直方圖native histogram**樣本浮點(diǎn)樣本就是一個簡單的浮點(diǎn)數(shù)原生直方圖樣本則包含一個完整的直方圖包括 count、sum 和各個桶buckets。一個容易混淆的術(shù)語約定術(shù)語含義histogram sample直方圖樣本在 PromQL 文檔語境下永遠(yuǎn)指原生直方圖classic histogram經(jīng)典直方圖由_bucket、_count、_sum三個后綴的一系列時間序列組成共同描述一個直方圖從 PromQL 的視角看經(jīng)典直方圖里只有浮點(diǎn)樣本并不存在“經(jīng)典直方圖樣本”這一說法。浮點(diǎn)樣本與直方圖樣本都可以具有 counter 或 gauge 的“flavor”語義類型浮點(diǎn)樣本不存儲自身的 flavor由寫查詢的人自行注意約定上包含浮點(diǎn) counter 的時間序列名以_total結(jié)尾以幫助區(qū)分直方圖樣本“知道”自己是 counter 還是 gauge因此引擎可以對不匹配的操作給出可靠告警。例如對 gauge 浮點(diǎn)序列使用rate()函數(shù)查詢不會報(bào)錯但結(jié)果很可能無意義而對 gauge 直方圖執(zhí)行同樣的操作查詢結(jié)果會帶有警告注解warning annotation。此外向量vector和時間序列可以同時混合包含浮點(diǎn)樣本與直方圖樣本。表達(dá)式語言的數(shù)據(jù)類型在 Prometheus 表達(dá)式語言中一個表達(dá)式或子表達(dá)式可以求值為四種類型之一Instant vector即時向量——一組時間序列的集合每個時間序列包含一個樣本所有樣本共享同一時間戳Range vector范圍向量——每個時間序列包含一段時間內(nèi)的多個數(shù)據(jù)點(diǎn)Scalar標(biāo)量——簡單的數(shù)值型浮點(diǎn)值String字符串——簡單的字符串值當(dāng)前尚未使用。不同類型的合法性因使用場景而異對于即時查詢上述任意數(shù)據(jù)類型都可以作為表達(dá)式根節(jié)點(diǎn)的結(jié)果而范圍查詢只支持標(biāo)量類型scalar和即時向量類型instant vector的表達(dá)式。從源碼結(jié)構(gòu)看這四種類型在 類型定義 中以ValueType常量vector、scalar、matrix、string表達(dá)DocumentedType()函數(shù)把內(nèi)部類型名映射為文檔面向用戶的術(shù)語如vector→ instant vector、matrix→ range vector可見文檔術(shù)語與解析器內(nèi)部術(shù)語是一一對應(yīng)的。原生直方圖桶布局的對齊Reconciliation原生直方圖可能具有不同的桶布局bucket layout但在執(zhí)行二元運(yùn)算和聚合運(yùn)算前通?？梢员晦D(zhuǎn)換為兼容的版本。作用于范圍向量、且適用于原生直方圖的函數(shù)同樣會執(zhí)行這種對齊二元運(yùn)算中對齊是成對pairwise進(jìn)行的聚合運(yùn)算與聚合函數(shù)中所有直方圖樣本會被對齊到同一個兼容的桶布局。并非所有桶布局都能被對齊。若操作中遇到不兼容的直方圖對應(yīng)的輸出向量元素會從結(jié)果中移除并帶上 warn 級別的注解annotation。字面量LiteralsPromQL 中不存在“直方圖字面量”。以下是各類字面量的語法說明。字符串字面量字符串字面量由單引號、雙引號或反引號界定。單引號與雙引號字符串遵循與 Go 相同的轉(zhuǎn)義規(guī)則反斜杠開始轉(zhuǎn)義序列后跟a、b、f、n、r、t、v或\也可用八進(jìn)制\nnn、十六進(jìn)制\xnn、\unnnn、\Unnnnnnnn表示特定字符。反引號字符串不解析轉(zhuǎn)義字符。注意與 Go 不同Prometheus不會丟棄反引號內(nèi)的換行符。this is a string these are unescaped: \n \\ \t these are not unescaped: \n \t浮點(diǎn)字面量與時間單位標(biāo)量浮點(diǎn)值可以寫成如下格式空格僅為提高可讀性[-]?( [0-9]*\.?[0-9]([eE][-]?[0-9])? | 0[xX][0-9a-fA-F] | [nN][aA][nN] | [iI][nN][fF] )示例23 -2.43 3.4e-9 0x8f -Inf NaN此外下劃線_可用于十進(jìn)制或十六進(jìn)制數(shù)字之間以提升可讀性1_000_000 .123_456_789 0x_53_AB_F3_82浮點(diǎn)字面量也用于表示以秒為單位的時間長度。十進(jìn)制整數(shù)可以與以下時間單位組合單位含義ms毫秒s秒1s 1000msm分鐘1m 60s忽略閏秒h小時1h 60md天1d 24h忽略夏令時w周1w 7dy年1y 365d忽略閏日給十進(jìn)制整數(shù)加上單位等價于以純浮點(diǎn)字面量表示相同秒數(shù)1s # 等價于 1 2m # 等價于 120 1ms # 等價于 0.001 -2h # 等價于 -7200以下寫法不合法0xABm # 十六進(jìn)制數(shù)不允許加單位后綴 1.5h # 時間單位不能與浮點(diǎn)數(shù)組合 Infd # ±Inf 與 NaN 不允許加單位后綴多個單位可以拼接但必須從大到小排列且同一單位在一個字面量中只能出現(xiàn)一次1h30m # 等價于 5400s即 5400 12h34m56s # 等價于 45296s即 45296 54s321ms # 等價于 54.321持續(xù)時間表達(dá)式Duration expressions在需要時間持續(xù)時間的地方——即范圍向量選擇器和offset持續(xù)時間——都可以使用算術(shù)表達(dá)式。在范圍向量中rate(http_requests_total[5m * 2]) # 10 分鐘范圍 rate(http_requests_total[(52) * 1m]) # 7 分鐘范圍在 offset 持續(xù)時間中http_requests_total offset (1h / 2) # 30 分鐘偏移 http_requests_total offset ((2 ^ 3) * 1m) # 8 分鐘偏移使用offset加持續(xù)時間表達(dá)式時必須用括號包裹整個表達(dá)式不加括號的話offset 計(jì)算只會取第一個持續(xù)時間值。支持的運(yùn)算符遵循常規(guī)優(yōu)先級規(guī)則運(yùn)算符含義加法-減法*乘法/除法%取模^冪運(yùn)算持續(xù)時間表達(dá)式中還可使用以下函數(shù)step()解析為范圍查詢的步長step width即時查詢中解析為0srange()解析為范圍查詢的總時長end time ? start time即時查詢中解析為0s。與 end()結(jié)合尤其有用例如max_over_time(metric[range()] end())可以在整個查詢范圍內(nèi)回溯min_of(duration, duration)返回兩者中較小者用于給持續(xù)時間設(shè)置上限max_of(duration, duration)返回兩者中較大者用于強(qiáng)制最小值。例如max_of(step(), 5s)保證持續(xù)時間不小于5smin_of(range(), 1h)把持續(xù)時間上限封頂在1h。注意修飾符中不支持持續(xù)時間表達(dá)式。等價持續(xù)時間示例5m * 2等價于10m或600s10m - 1m等價于9m或540s(52) * 1m等價于7m或420s1h / 2等價于30m或1800s4h % 3h等價于1h或3600s(2 ^ 3) * 1m等價于8m或480sstep() 1等價于查詢步長增加1smax_of(step(), 5s)等價于查詢步長與5s中的較大者min_of(2 * step() 5s, 5m)等價于“查詢步長兩倍加5s”與5m中的較小者。從源碼看持續(xù)時間表達(dá)式在解析后并不立即求值而是以 AST 節(jié)點(diǎn)DurationExpr形式掛在OriginalOffsetExpr/RangeExpr/StepExpr字段上見 AST 定義在執(zhí)行前由 durationVisitor 統(tǒng)一計(jì)算。該訪問器處理三類節(jié)點(diǎn)VectorSelectoroffset 表達(dá)式、MatrixSelector范圍表達(dá)式和SubqueryExproffset、step、range 三類表達(dá)式。求值過程還包含重要的健壯性檢查見 calculateDuration顯式拒絕 NaN 與 ±Inf防止其繞過邊界檢查后在time.Duration轉(zhuǎn)換時產(chǎn)生未定義值拒絕超出 int64 納秒表示范圍的持續(xù)時間即 |seconds| 不超過 2^63/1e9除零、取模零會直接報(bào)錯范圍向量與子查詢的范圍/步長不允許為負(fù)或零而 offset 允許負(fù)值用于時間前向比較。時間序列選擇器選擇器是 PromQL 的基本構(gòu)件指明查詢引擎要獲取哪些數(shù)據(jù)。即時向量選擇器即時向量選擇器在一給定時間戳處選擇一組時間序列并為每個序列返回一個樣本值。最簡單的形式只寫指標(biāo)名結(jié)果是一個即時向量包含所有該指標(biāo)名的時間序列http_requests_total返回的值是查詢求值時間戳之前最近的那個樣本即時查詢對應(yīng)查詢時間范圍查詢對應(yīng)當(dāng)前 step。使用修飾符 可以覆蓋選擇所依據(jù)的時間戳。只有當(dāng)時間序列的最近樣本距當(dāng)前時刻不超過 lookback period 時該序列才會被返回?？梢杂没ɡㄌ杮}追加逗號分隔的標(biāo)簽匹配器進(jìn)一步過濾http_requests_total{jobprometheus,groupcanary}標(biāo)簽匹配操作符共四個操作符含義與給定字符串完全相等!與給定字符串不相等~與給定字符串正則匹配!~與給定字符串正則不匹配正則匹配是完全錨定的env~foo等價于env~^foo$。例如選擇staging、testing、development三種環(huán)境下、HTTP 方法非GET的所有http_requests_total時間序列http_requests_total{environment~staging|testing|development,method!GET}匹配空值的標(biāo)簽匹配器也會選中根本沒有該標(biāo)簽的時間序列。同一標(biāo)簽名可以出現(xiàn)多個匹配器且全部匹配才返回結(jié)果。給定數(shù)據(jù)集http_requests_total http_requests_total{replicarep-a} http_requests_total{replicarep-b} http_requests_total{environmentdevelopment}查詢http_requests_total{environment}會匹配并返回前三條它們都沒有environment標(biāo)簽而排除http_requests_total{environmentdevelopment}。查詢http_requests_total{replica!rep-a,replica~rep.*}只會匹配http_requests_total{replicarep-b}。向量選擇器必須指定指標(biāo)名或至少一個不匹配空字符串的標(biāo)簽匹配器。以下表達(dá)式非法{job~.*} # Bad!而下面兩個都合法因?yàn)樗鼈兒胁黄ヅ淇諛?biāo)簽值的匹配器{job~.} # Good! {job~.*,methodget} # Good!從源碼看這條規(guī)則由解析器在 validate 階段強(qiáng)制執(zhí)行“A Vector selector must contain at least one non-empty matcher to prevent implicit selection of all metrics (e.g. by a typo)”——防止因拼寫錯誤而隱式選中全部指標(biāo)。標(biāo)簽匹配器也可以作用于指標(biāo)名本身通過匹配內(nèi)部__name__標(biāo)簽實(shí)現(xiàn)。例如http_requests_total等價于{__name__http_requests_total}且!、~、!~也可使用。以下表達(dá)式選中所有名字以job:開頭的指標(biāo){__name__~job:.*}指標(biāo)名不得是bool、on、ignoring、group_left、group_right這些關(guān)鍵字之一。以下表達(dá)式非法on{} # Bad!變通方案是借助__name__標(biāo)簽{__name__on} # Good!范圍向量選擇器范圍向量字面量與即時向量字面量工作方式相同但選擇的是從當(dāng)前時刻向前回溯一段時間內(nèi)的樣本序列。語法上在向量選擇器末尾用方括號[]追加一個浮點(diǎn)字面量指定向前取多少秒的數(shù)據(jù)。常見寫法使用帶時間單位的字面量如[5m]。范圍區(qū)間是左開右閉的時間戳恰好在左邊界上的樣本被排除時間戳恰好在右邊界上的樣本被包含。示例——選擇所有指標(biāo)名為http_requests_total且job標(biāo)簽為prometheus的時間序列在 5 分鐘內(nèi)的所有值http_requests_total{jobprometheus}[5m]offset 修飾符offset修飾符可以改變查詢中單個即時向量或范圍向量的時間偏移。例如以下表達(dá)式返回相對于當(dāng)前查詢求值時刻過去 5 分鐘時http_requests_total的值http_requests_total offset 5m注意offset修飾符必須緊跟選擇器例如這樣寫是對的sum(http_requests_total{methodGET} offset 5m) // GOOD.而下面這種是錯誤的sum(http_requests_total{methodGET}) offset 5m // INVALID.對范圍向量同理。下面返回http_requests_total一周前的 5 分鐘速率rate(http_requests_total[5m] offset 1w)查詢歷史樣本時負(fù)數(shù) offset可以實(shí)現(xiàn)向未來方向的時間比較rate(http_requests_total[5m] offset -1w)注意這允許查詢“超前于”其求值時間向前看。 修飾符修飾符可以改變查詢中單個即時向量或范圍向量的求值時間。修飾符接受的時間值是用浮點(diǎn)字面量表示的Unix 時間戳。例如以下表達(dá)式返回2021-01-04T07:40:0000:00時http_requests_total的值http_requests_total 1609746000與offset相同必須緊跟選擇器。這樣寫是對的sum(http_requests_total{methodGET} 1609746000) // GOOD.而下面這種是錯誤的sum(http_requests_total{methodGET}) 1609746000 // INVALID.對范圍向量同理返回2021-01-04T07:40:0000:00時刻的 5 分鐘速率rate(http_requests_total[5m] 1609746000)修飾符支持上文描述的全部數(shù)字字面量形式。它還可以與offset修飾符一起使用此時 offset 相對于修飾符指定的時間生效無論兩個修飾符的書寫順序如何結(jié)果相同# offset 在 之后 http_requests_total 1609746000 offset 5m # offset 在 之前 http_requests_total offset 5m 1609746000此外start()與end()可作為修飾符的特殊取值對范圍查詢二者分別解析為該范圍查詢的起始與結(jié)束時間且對所有 step 保持不變對即時查詢start()與end()都解析為求值時間。http_requests_total start() rate(http_requests_total[5m] end())注意修飾符允許查詢超前于其求值時間。從源碼結(jié)構(gòu)看修飾符在解析器中以Timestamp *int64字段絕對時間戳和StartOrEnd ItemType字段標(biāo)記start()/end()承載于 VectorSelector 與 SubqueryExpr 上Offset字段則存放執(zhí)行時實(shí)際使用的偏移量由原始 offset、時間、求值時間與子查詢偏移共同計(jì)算得出。子查詢Subquery子查詢允許你針對給定的時間范圍與分辨率運(yùn)行一次即時查詢。子查詢的結(jié)果是一個范圍向量。語法instant_query [ range : [resolution] ] [ float_literal ] [ offset float_literal ]其中resolution分辨率即子查詢內(nèi)部的 step是可選的默認(rèn)取全局求值間隔。從 AST 結(jié)構(gòu)看SubqueryExpr 同時攜帶Range/RangeExpr范圍、Step/StepExpr分辨率與OriginalOffset/OriginalOffsetExpr偏移三者均可使用持續(xù)時間表達(dá)式并在 durationVisitor 中統(tǒng)一求值。運(yùn)算符與函數(shù)Prometheus 支持大量二元運(yùn)算符與聚合運(yùn)算符詳見表達(dá)式語言運(yùn)算符頁也支持若干對數(shù)據(jù)操作的函數(shù)詳見表達(dá)式語言函數(shù)頁。注釋PromQL 支持以#開頭的行注釋# This is a comment正則表達(dá)式Prometheus 中所有正則表達(dá)式均使用 RE2 語法Google RE2具有線性時間復(fù)雜度的確定性匹配特性且正則匹配始終是全程錨定的。常見陷阱GotchasStaleness陳舊樣本與 lookback period查詢采樣所用的時間戳獨(dú)立于實(shí)際現(xiàn)存時間序列數(shù)據(jù)選擇這主要是為了支持聚合sum、avg等這類場景——被聚合的多個時間序列在時間上往往并不精確對齊。正因其獨(dú)立性Prometheus 必須為每個相關(guān)時間序列在這些時間戳上分配一個值它的做法是取“距該時間戳不超過 lookback period 之前的最新樣本”。lookback period 默認(rèn) 5 分鐘可以通過--query.lookback-delta命令行標(biāo)志設(shè)置見命令行參考也可以在單個查詢中通過lookback_delta參數(shù)覆蓋。從源碼看默認(rèn)值定義于 engine.go 的defaultLookbackDelta 5 * time.Minute當(dāng)LookbackDelta為 0 時引擎自動回退到該默認(rèn)值命令行標(biāo)志在 main.go 中注冊為query.lookback-delta描述為 “The maximum lookback duration for retrieving metrics during expression evaluations and federation.”。行為邊界由 TestQueryLookbackDelta 測試用例驗(yàn)證樣本恰好落后一個默認(rèn) lookback5 分鐘時會被查詢?nèi)〉皆俾浜笠粋€毫秒則不再取到。陳舊stale語義當(dāng)某個 target 的抓取或規(guī)則求值不再返回先前存在的時間序列樣本時該序列會被標(biāo)記為 stale當(dāng) target 被移除時其先前抓取的時間序列也會很快被標(biāo)記為 stale若查詢的采樣時間戳晚于序列被標(biāo)記為 stale 的時刻則不再為該序列返回值之后若重新攝入新樣本則按預(yù)期返回序列在不再導(dǎo)出、或 target 不存在時變 stale它們會從圖表中最后采集樣本的時刻消失之后查詢不再返回。一個例外某些自行打時間戳的 exporter 行為不同——其停止導(dǎo)出的序列會在消失前保持最后一個值默認(rèn) 5 分鐘。track_timestamps_staleness配置可以改變該行為。避免慢查詢與過載當(dāng)查詢需要處理大量數(shù)據(jù)時繪圖可能會超時甚至壓垮服務(wù)器或?yàn)g覽器。因此在未知數(shù)據(jù)上構(gòu)建查詢時始終先在 Prometheus 表達(dá)式瀏覽器的表格視圖tabular view中構(gòu)建查詢直到結(jié)果集看起來合理最多幾百條、而非幾千條時間序列。只有當(dāng)數(shù)據(jù)被充分過濾或聚合后再切換到圖表模式。如果表達(dá)式即席ad-hoc繪圖仍然太慢就通過記錄規(guī)則預(yù)先記錄計(jì)算結(jié)果。這一點(diǎn)在 Prometheus 中尤其關(guān)鍵像api_http_requests_total這樣裸的指標(biāo)名選擇器可能擴(kuò)展為數(shù)千條帶不同標(biāo)簽的時間序列。同時要記住對大量時間序列做聚合的表達(dá)式即使輸出只有少數(shù)幾條序列也會給服務(wù)器帶來負(fù)載——正如在關(guān)系數(shù)據(jù)庫中對某一整列求和即便輸出只是一個數(shù)字也會很慢。小結(jié)與延伸閱讀主題關(guān)鍵要點(diǎn)即時/范圍查詢范圍查詢 不同時間戳上的多次即時查詢Table 頁簽即時Graph 頁簽范圍樣本類型浮點(diǎn)樣本與原生直方圖樣本直方圖自帶 counter/gauge 語義可產(chǎn)生可靠性告警四種數(shù)據(jù)類型instant vector、range vector、scalar、string未用范圍查詢僅支持 scalar 與 instant vector字面量字符串三種引號、浮點(diǎn)含下劃線、十六進(jìn)制、時間單位ms/s/m/h/d/w/y 從大到小拼接持續(xù)時間表達(dá)式 - * / % ^與step()、range()、min_of()、max_of()offset 表達(dá)式需加括號中不支持選擇器空值匹配器選中無該標(biāo)簽的序列{job~.*}非法至少需一個非空匹配器offset/均須緊跟選擇器支持負(fù) offset 與start()/end()可超前求值時間Staleness默認(rèn) 5 分鐘 lookback--query.lookback-delta或單查詢lookback_delta可調(diào)更多學(xué)習(xí)材料可參考倉庫中的 示例文檔建議初學(xué)者先通過示例入門、運(yùn)算符、函數(shù)與 HTTP API 參考頁深入實(shí)現(xiàn)可閱讀 promql/parser/parse.go解析與校驗(yàn)、promql/parser/ast.goAST 節(jié)點(diǎn)定義、promql/durations.go持續(xù)時間表達(dá)式求值與 promql/engine.go查詢引擎?！久赓M(fèi)下載鏈接】prometheusThe Prometheus monitoring system and time series database.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pr/prometheus創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考