查詢函式

某些函式具有預設引數，例如 year(v=vector(time()) instant-vector)。這意味著存在一個瞬時向量引數 v，如果未提供，它將預設使用表示式 vector(time()) 的值。

`abs()`

abs(v instant-vector) 返回一個向量，其中包含輸入向量中所有轉換為其絕對值的浮點樣本。輸入向量中的直方圖（Histogram）樣本將被靜默忽略。

`absent()`

absent(v instant-vector) 如果傳遞給它的向量具有任何元素（浮點樣本或直方圖樣本），則返回一個空向量；如果傳遞給它的向量沒有元素，則返回一個值為 1 的單元素向量。

這對於在給定的指標名稱和標籤組合不存在任何時間序列時進行告警非常有用。

absent(nonexistent{job="myjob"})
# => {job="myjob"}

absent(nonexistent{job="myjob",instance=~".*"})
# => {job="myjob"}

absent(sum(nonexistent{job="myjob"}))
# => {}

在頭兩個示例中，absent() 會嘗試智慧地從輸入向量中推導單元素輸出向量的標籤。

`absent_over_time()`

absent_over_time(v range-vector) 如果傳遞給它的範圍向量具有任何元素（浮點樣本或直方圖樣本），則返回一個空向量；如果傳遞給它的範圍向量沒有元素，則返回一個值為 1 的單元素向量。

這對於在某段時間內給定的指標名稱和標籤組合不存在任何時間序列時進行告警非常有用。

absent_over_time(nonexistent{job="myjob"}[1h])
# => {job="myjob"}

absent_over_time(nonexistent{job="myjob",instance=~".*"}[1h])
# => {job="myjob"}

absent_over_time(sum(nonexistent{job="myjob"})[1h:])
# => {}

在頭兩個示例中，absent_over_time() 會嘗試智慧地從輸入向量中推導單元素輸出向量的標籤。

`ceil()`

ceil(v instant-vector) 返回一個向量，其中包含輸入向量中的所有浮點樣本，且這些樣本會被向上取整到大於或等於其原始值的最接近的整數。輸入向量中的直方圖樣本將被靜默忽略。

ceil(+Inf) = +Inf
ceil(±0) = ±0
ceil(1.49) = 2.0
ceil(1.78) = 2.0

`changes()`

對於每個輸入的序列，changes(v range-vector) 以瞬時向量的形式返回其值在提供的時間範圍內發生變化的次數。浮點樣本後跟直方圖樣本（反之亦然）計為一次變化。計數器直方圖（counter histogram）樣本後跟儀表直方圖（gauge histogram）樣本（且其值完全相同，反之亦然）不計為變化。

`clamp()`

clamp(v instant-vector, min scalar, max scalar) 將 v 中所有浮點樣本的值限制在下限 min 和上限 max 之間。輸入向量中的直方圖樣本將被靜默忽略。

特殊情況

如果 min > max，則返回一個空向量
如果 min 或 max 是 NaN，則浮點樣本會被限制為 NaN

`clamp_max()`

clamp_max(v instant-vector, max scalar) 將 v 中所有浮點樣本的值限制在上限 max 以內。輸入向量中的直方圖樣本將被靜默忽略。

`clamp_min()`

clamp_min(v instant-vector, min scalar) 將 v 中所有浮點樣本的值限制在下限 min 以上。輸入向量中的直方圖樣本將被靜默忽略。

`day_of_month()`

day_of_month(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳對應的月份第幾天（UTC 時間）。返回的值在 1 到 31 之間。輸入向量中的直方圖樣本將被靜默忽略。

`day_of_week()`

day_of_week(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳對應的星期幾（UTC 時間）。返回的值在 0 到 6 之間，其中 0 表示星期日等。輸入向量中的直方圖樣本將被靜默忽略。

`day_of_year()`

day_of_year(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳對應的年份第幾天（UTC 時間）。平年返回的值在 1 到 365 之間，跨躍年則在 1 到 366 之間。輸入向量中的直方圖樣本將被靜默忽略。

`days_in_month()`

days_in_month(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳對應月份的天數（UTC 時間）。返回的值在 28 到 31 之間。輸入向量中的直方圖樣本將被靜默忽略。

`delta()`

delta(v range-vector) 計算範圍向量 v 中每個時間序列元素的第一個值和最後一個值之間的差值，返回一個包含給定差值和等效標籤的瞬時向量。該差值會被外推（extrapolated）以覆蓋範圍向量選擇器中指定的完整時間範圍，因此即使樣本值全是整數，也有可能得到非整數的結果。

以下示例表示式返回當前與 2 小時前之間的 CPU 溫度差值

delta(cpu_temp_celsius{host="zeus"}[2h])

delta 作用於直方圖樣本的方式是計算一個新的直方圖，其中每個元件（觀測值的總和和計數、桶）都是 v 中第一個和最後一個原生直方圖中相應元件之間的差值。然而，在結果向量中，將省略 v 中每個在範圍內包含浮點樣本和直方圖樣本混合的元素，並透過 warn 級別的註解（annotation）進行標記。

delta 應該僅與儀表盤（Gauge，包括浮點型和直方圖型）一起使用。

`deriv()`

deriv(v range-vector) 使用簡單線性迴歸計算範圍向量 v 中每個浮點時間序列的每秒導數。範圍向量必須至少包含兩個浮點樣本才能進行計算。當在範圍向量中發現 +Inf 或 -Inf 時，計算出的斜率和偏移值將為 NaN。

deriv 應該僅與儀表盤（Gauge）一起使用，且僅對浮點樣本有效。範圍向量中僅包含直方圖樣本的元素將被完全忽略。對於包含浮點樣本和直方圖樣本混合的元素，僅使用浮點樣本作為輸入，這會透過 info 級別的註解進行標記。

`end()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

end() 返回當前查詢範圍評估的結束時間戳，即自 UTC 時間 1970 年 1 月 1 日以來的秒數。對於瞬時查詢，這等於評估時間戳。

`double_exponential_smoothing()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

double_exponential_smoothing(v range-vector, sf scalar, tf scalar) 為 v 中範圍內的每個浮點時間序列生成平滑值。平滑因子 sf 越低，舊資料的重要性越高。趨勢因子 tf 越高，考慮的資料趨勢就越多。sf 和 tf 都必須在 0 和 1 之間。欲瞭解更多詳細資訊，請參閱 NIST 工程統計手冊。在 Prometheus V2 中，此函式被稱為 holt_winters。這引起了混淆，因為 Holt-Winters 方法通常是指三重指數平滑。這裡實現的雙重指數平滑也被稱為“Holt 線性”（Holt Linear）平滑。

double_exponential_smoothing 應該僅與儀表盤（Gauge）一起使用，且僅對浮點樣本有效。範圍向量中僅包含直方圖樣本的元素將被完全忽略。對於包含浮點樣本和直方圖樣本混合的元素，僅使用浮點樣本作為輸入，這會透過 info 級別的註解進行標記。

`exp()`

exp(v instant-vector) 計算 v 中所有浮點樣本的指數函式。直方圖樣本將被靜默忽略。特殊情況有

Exp(+Inf) = +Inf
Exp(NaN) = NaN

`floor()`

floor(v instant-vector) 返回一個向量，其中包含輸入向量中的所有浮點樣本，這些樣本會被向下取整到小於或等於其原始值的最接近的整數。輸入向量中的直方圖樣本將被靜默忽略。

floor(+Inf) = +Inf
floor(±0) = ±0
floor(1.49) = 1.0
floor(1.78) = 1.0

`histogram_avg()`

histogram_avg(v instant-vector) 返回儲存在 v 中每個原生直方圖樣本中的觀測值的算術平均值。浮點樣本將被忽略，並且不會出現在返回的向量中。

如下文所示，使用 histogram_avg 從原生直方圖中計算 5 分鐘視窗內的平均請求時長

histogram_avg(rate(http_request_duration_seconds[5m]))

這等價於以下查詢

  histogram_sum(rate(http_request_duration_seconds[5m]))
/
  histogram_count(rate(http_request_duration_seconds[5m]))

`histogram_count()` 和 `histogram_sum()`

histogram_count(v instant-vector) 返回儲存在 v 中每個原生直方圖樣本中的觀測值數量。浮點樣本將被忽略，並且不會出現在返回的向量中。

類似地，histogram_sum(v instant-vector) 返回儲存在每個原生直方圖樣本中的觀測值總和。

按以下方式使用 histogram_count，從一系列直方圖樣本中計算觀測速率（在這種情況下對應於“每秒請求數”）

histogram_count(rate(http_request_duration_seconds[10m]))

`histogram_fraction()`

histogram_fraction(lower scalar, upper scalar, b instant-vector) 返回 b 中包含的每個傳統（classic）或原生直方圖中，介於給定的下限和上限值之間的觀測值的估算比例。b 中的浮點樣本被視為一個或多個傳統直方圖的每個桶（bucket）中的觀測值計數，而 b 中的原生直方圖樣本則分別作為單獨的直方圖進行處理。這與 histogram_quantile() 的工作方式相同。（請參閱該處以瞭解更多詳細資訊。）

如果提供的下限和上限值與桶邊界不重合，則計算出的比例是一個估算值，使用與 histogram_quantile() 相同的插值方法。（請參閱該處以瞭解更多詳細資訊。）特別是在傳統直方圖中，很容易不小心選擇與任何桶邊界相距甚遠的下限或上限值，從而導致巨大的誤差。在計算比例時，直接對桶序列進行操作通常是比對傳統直方圖使用 histogram_fraction() 更健壯的方法。請參閱Apdex 分數的計算作為一個典型示例。

例如，以下表達式計算過去一小時內耗時在 200 毫秒或更短的 HTTP 請求比例

histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))

估算誤差取決於底層原生直方圖的解析度，以及提供的邊界與直方圖中桶邊界的對齊程度。

+Inf 和 -Inf 是有效的邊界值。例如，如果上面表示式中的直方圖包含負觀測值（請求耗時本不應如此），那麼包含所有小於或等於 0.2 的觀測值的合適下限應該是 -Inf，而不是 0。

提供的邊界是包含（inclusive）還是排除（exclusive），僅在提供的邊界與底層原生直方圖中的桶邊界精確對齊時才有意義。在這種情況下，其行為取決於直方圖的 schema 定義。（通常的標準指數 schema 在正值時都採用包含上限和排除下限，負值時則相反。）在沒有邊界精確對齊的情況下，該函式使用插值來估算比例。由於存在這種不確定性，邊界是包含還是排除也就變得無關緊要了。

具有標準指數桶的原生直方圖的特殊情況：在這種情況下，NaN 觀測值被認為在任何桶之外。histogram_fraction(-Inf, +Inf, b) 實際上返回的是非 NaN 觀測值的比例，因此可能小於 1。

`histogram_quantile()`

histogram_quantile(φ scalar, b instant-vector) 從傳統直方圖或原生直方圖中計算 φ 分位數（0 ≤ φ ≤ 1）。（有關 φ 分位數的詳細解釋以及通常的（傳統）直方圖指標型別的使用，請參閱直方圖和摘要。）

b 中的浮點樣本被視為一個或多個傳統直方圖的每個桶中的觀測值計數。每個浮點樣本必須有一個標籤 le，其中標籤值表示該桶的包含上限。（沒有此類標籤的浮點樣本將被靜默忽略。）其他標籤和指標名稱用於標識屬於每個傳統直方圖的桶。直方圖指標型別會自動提供帶有 _bucket 字尾和相應標籤的時間序列。

b 中的（原生）直方圖樣本分別作為單獨的直方圖來處理，並從中計算分位數。

只要不產生命名衝突，b 可以包含傳統直方圖和原生直方圖的混合。

使用 rate() 函式指定用於分位數計算的時間視窗。

示例：一個直方圖指標名為 http_request_duration_seconds（因此傳統直方圖的桶指標名稱為 http_request_duration_seconds_bucket）。在 http_request_duration_seconds 為傳統直方圖的情況下，要計算過去 10 分鐘內請求時長的第 90 百分位數，請使用以下表達式

histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))

對於原生直方圖，請改用以下表達式

histogram_quantile(0.9, rate(http_request_duration_seconds[10m]))

會針對 http_request_duration_seconds 中的每個標籤組合計算分位數。要進行聚合，請在 rate() 函數週圍使用 sum() 聚合器。由於 histogram_quantile() 在處理傳統直方圖時需要 le 標籤，因此必須將其包含在 by 子句中。以下表達式對傳統直方圖按 job 聚合第 90 百分位數

histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))

聚合原生直方圖時，該表示式可簡化為

histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m])))

要聚合所有傳統直方圖，只需指定 le 標籤

histogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m])))

對於原生直方圖，聚合所有內容就像往常一樣工作，不需要任何 by 子句

histogram_quantile(0.9, sum(rate(http_request_duration_seconds[10m])))

在分位數的值與桶邊界不重合的（常見）情況下，histogram_quantile() 函式會在該分位數落入的桶內插值計算分位數。對於傳統直方圖、具有自定義桶邊界的原生直方圖以及其他原生直方圖的零桶，它假設觀測值在桶內呈均勻分佈（也稱為 *線性插值*，linear interpolation）。對於具有標準指數分桶 schema 的原生直方圖的非零桶，插值是在以下假設下進行的：桶內的樣本分佈方式可以在假設的更高解析度直方圖中均勻填充這些桶。（這也稱為 *指數插值*，exponential interpolation。有關更多詳細資訊，請參閱原生直方圖規範。）

如果 b 有 0 個觀測值，則返回 NaN。對於 φ < 0，返回 -Inf。對於 φ > 1，返回 +Inf。對於 φ = NaN，返回 NaN。

傳統直方圖的特殊情況

如果 b 包含少於兩個桶，則返回 NaN。
最高桶的上限必須為 +Inf。（否則，返回 NaN。）
如果分位數位於最高桶中，則返回第二高桶的上限。
如果最低桶的上限大於 0，則假設其下限為 0。在這種情況下，將在該桶內應用常用的線性插值。否則，對於位於最低桶中的分位數，將返回最低桶的上限。

原生直方圖的特殊情況

如果具有標準指數桶的原生直方圖包含 NaN 觀測值，且分位數落入現有的指數桶之一中，則由於 NaN 觀測值被視為 +Inf，結果會偏向更高的值。這會透過 info 級別的註解進行標記。
如果具有標準指數桶的原生直方圖包含 NaN 觀測值，且分位數落在所有現有指數桶之上，則返回 NaN。這會透過 info 級別的註解進行標記。
如果直方圖在正數桶中有觀測值但在負數桶中沒有，則假定寬度有限的零桶不包含負觀測值。
如果直方圖在負數桶中有觀測值但在正數桶中沒有，則假定寬度有限的零桶不包含正觀測值。

您可以使用 histogram_quantile(0, v instant-vector) 來獲取直方圖中儲存的估算最小值。

您可以使用 histogram_quantile(1, v instant-vector) 來獲取直方圖中儲存的估算最大值。

傳統直方圖的桶是累加的。因此，以下情況應當總是成立的：

桶中的計數單調遞增（嚴格非遞減）。
在兩個連續桶的上限之間缺乏觀測值會導致這兩個桶中的計數相等。

然而，浮點數精度問題（例如透過 sum(rate(...)) 計算桶時引入的微小差異）或無效資料可能會破壞這些假設。在這種情況下，histogram_quantile 將無法返回有意義的結果。為了緩解這個問題，histogram_quantile 假設連續桶之間的微小相對差異是由浮點精度誤差引起的並忽略它們。（忽略兩個桶之間差異的閾值是兩個桶之和的一萬億分之一 (1e-12)。）此外，如果在此調整後仍然存在非單調的桶計數，它們將被增加到前一個桶的值以強制單調性。後者是輸入資料存在實際問題的證據，因此會透過內容為 input to histogram_quantile needed to be fixed for monotonicity 的 info 級別註解進行標記。如果您遇到此註解，應當查詢並清除無效資料的源頭。

`histogram_quantiles()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

histogram_quantiles(v instant-vector, quantile_label string, φ_1 scalar, φ_2 scalar, ...) 從傳統直方圖或原生直方圖中計算多個（介於 1 到 10 個之間） φ 分位數（0 ≤ φ ≤ 1）。分位數計算的工作方式與 histogram_quantile() 相同。第二個引數（一個字串）指定了用於在查詢結果中標識不同分位數的標籤名稱。

histogram_quantiles(sum(rate(foo[1m])), "quantile", 0.9, 0.99)
# => {quantile="0.9"} 123
     {quantile="0.99"} 128

`histogram_stddev()` 和 `histogram_stdvar()`

histogram_stddev(v instant-vector) 返回 v 中每個原生直方圖樣本的觀測值估算標準差。為了進行此估算，假定桶內的所有觀測值都具有桶邊界均值（mean）的值。對於零桶和具有自定義邊界的桶，使用算術平均值。對於通常的指數桶，使用幾何平均值。浮點樣本將被忽略，並且不會出現在返回的向量中。

類似地，histogram_stdvar(v instant-vector) 返回 v 中每個原生直方圖樣本的觀測值估算方差。

`hour()`

hour(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳對應的小時（UTC 時間）。返回的值在 0 到 23 之間。輸入向量中的直方圖樣本將被靜默忽略。

`idelta()`

idelta(v range-vector) 計算範圍向量 v 中最後兩個樣本之間的差值，返回一個包含給定差值和等效標籤的瞬時向量。這兩個樣本必須同為浮點樣本或同為直方圖樣本。在結果向量中，將省略 v 中最後兩個樣本之一是浮點樣本而另一個是直方圖樣本的元素，並透過 warn 級別的註解進行標記。

idelta 應該僅與儀表盤（Gauge，包括浮點型和直方圖型）一起使用。

`increase()`

increase(v range-vector) 計算範圍向量中時間序列的增長量。單調性的破壞（例如由於目標重啟導致的計數器重置）會被自動調整。增長量會被外推以覆蓋範圍向量選擇器中指定的完整時間範圍，因此即使計數器僅以整數增量增加，也有可能得到非整數的結果。

以下示例表示式返回過去 5 分鐘內測得的 HTTP 請求數，針對範圍向量中的每個時間序列

increase(http_requests_total{job="api-server"}[5m])

increase 作用於直方圖樣本的方式是計算一個新的直方圖，其中每個元件（觀測值的總和和計數、桶）都是 v 中第一個和最後一個原生直方圖中相應元件之間的增長量。然而，在結果向量中，將省略 v 中每個在範圍內包含浮點樣本 and 直方圖樣本混合的元素，並透過 warn 級別的註解進行標記。

increase 應該僅與計數器（Counter，包括浮點型和直方圖型）一起使用。它是 rate(v) 乘以指定時間範圍視窗下的秒數的語法糖，主要應當用於提高人類可讀性。在記錄規則中使用 rate，以便在每秒的基礎上一致地跟蹤增長量。

`info()`

info 函式是一個實驗，旨在改善圍繞引入來自資訊指標（info metrics）標籤的使用者體驗（UX）。此函式的行為在未來的 Prometheus 版本中可能會發生變化，包括從 PromQL 中移除。info 必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

info(v instant-vector, [data-label-selector instant-vector]) 為 v 中的每個時間序列尋找所有具有匹配 *標識* 標籤（稍後會詳細介紹）的資訊序列（info series），並將其 *資料* 標籤（即非標識標籤）的並集新增到該時間序列中。第二個引數 data-label-selector 是可選的。它不是一個真正的瞬時向量，而是使用了其語法的一個子集。它必須以花括號（{ ... }）開頭和結尾，且只能包含標籤匹配器。這些標籤匹配器用於限制要考慮的資訊序列以及要新增到 v 中的資料標籤。

如果在特定時間戳下，v 中給定的時間序列沒有匹配的資訊序列（例如因為資訊序列已經失效/過期），則其行為取決於資料標籤匹配器：如果 data-label-selector 包含任何不匹配空字串的匹配器（例如 {data=~".+"}），那麼由於所需的資訊補充（enrichment）不可用，該時間序列將從該時間戳的結果中丟棄。如果所有匹配器都匹配空字串（例如 {data=~".*"}），或者未提供 data-label-selector，則返回未經資訊補充的時間序列。

資訊序列的“標識標籤”是唯一標識該資訊序列的標籤子集。其餘的標籤被視為 *資料標籤*（也稱為非標識標籤）。（注意，Prometheus 關於時間序列標識的概念總是包含 *所有* 標籤。為了 info 函式的需要，我們在“邏輯上”以不同於傳統 Prometheus 視角的方式定義了資訊序列的標識。）資訊序列的標識標籤用於將其與常規（非資訊）序列進行關聯（join），即那些具有與資訊序列標識標籤相同標籤的序列。由 info 函式新增到常規序列中的資料標籤，實際上編碼了元資料的鍵值對。（這意味著，在傳統的 Prometheus 視角中，資料標籤的變化構成了舊資訊序列的結束和新資訊序列的開始，而 info 函式的“邏輯”視角則是該資訊序列繼續存在，只是具有了不同的“資料”。）

傳統的新增資料標籤的方法有時被稱為“連線查詢（join query）”，如以下示例所示

  rate(http_server_request_duration_seconds_count[2m])
* on (job, instance) group_left (k8s_cluster_name)
  target_info

該查詢的核心是表示式 rate(http_server_request_duration_seconds_count[2m])。但為了從資訊指標（info metric）中新增資料標籤，使用者必須使用繁瑣（且不那麼直觀）的語法來指定要使用哪個資訊指標（target_info）、標識標籤是什麼（on (job, instance)），以及要新增哪些資料標籤（group_left (k8s_cluster_name)）。

這個查詢不僅冗長且難以編寫，還可能陷入“身份危機”：如果 target_info 的任何資料標籤發生變化，Prometheus 就會將其視為時間序列的變化（如上文所述，Prometheus 本身並沒有非標識標籤的概念）。如果舊的 target_info 序列沒有被正確標記為失效（在某些攝取路徑中可能會發生這種情況），上面的查詢將在最長 5 分鐘內（回溯增量，lookback delta）報錯，因為它會發現與 target_info 的舊版本和新版本同時衝突的匹配。

info 函式不僅能解決此衝突（優先使用較新的時間序列），而且還簡化了語法，因為它知道可用資訊序列及其標識標籤是什麼。使用 info 函式後，示例查詢如下所示

info(
  rate(http_server_request_duration_seconds_count[2m]),
  {k8s_cluster_name=~".+"}
)

新增 *所有* 資料標籤的常見情況可以透過完全省略 info 函式的第二個引數來實現，從而使示例更加簡化

info(rate(http_server_request_duration_seconds_count[2m]))

雖然 info 通常會自動尋找所有匹配的資訊序列，但也可以透過提供 __name__ 標籤匹配器來限制它們，例如 {__name__="target_info"}。

請注意，如果 v 中有任何與 data-label-selector 匹配的時間序列（如果未指定該引數，則為預設的 target_info），它們將被視為資訊序列並保持原樣返回。

限制

在當前的迭代中，info 預設僅考慮名稱為 target_info 的資訊序列。它還假設資訊序列的標識標籤為 instance 和 job。然而，info 確實支援其他資訊序列名稱，這可以透過 __name__ 標籤匹配器來實現。例如，可以顯式宣告同時考慮 target_info 和 build_info，如下所示：{__name__=~"(target|build)_info"}。但是，標識標籤必須始終為 instance 和 job。

當僅提供否定的 __name__ 匹配器（例如 {__name__!="target_info"}）時，info 會考慮所有匹配 .+_info 的指標，然後將否定匹配器作為過濾器應用。這是因為僅憑否定匹配器無法確切地確定需要考慮哪些資訊指標。

這些限制在一定程度上違背了 info 函式的初衷。在當前階段，這是一項實驗，旨在瞭解這種方法在實踐中究竟有多大用處。info 函式的最終版本將會確實考慮所有匹配的資訊序列及其相應的標識標籤。

`irate()`

irate(v range-vector) 計算範圍向量中時間序列的每秒瞬時增長率。這是基於最後兩個資料點的。單調性的破壞（例如由於目標重啟導致的計數器重置）會被自動調整。這兩個樣本必須同為浮點樣本或同為直方圖樣本。在結果向量中，將省略 v 中最後兩個樣本之一是浮點樣本而另一個是直方圖樣本的元素，並透過 warn 級別的註解進行標記。

irate 應該僅與計數器（Counter，包括浮點型和直方圖型）一起使用。

以下示例表示式返回回溯最多 5 分鐘的最後兩個最新資料點的每秒 HTTP 請求率，針對範圍向量中的每個時間序列

irate(http_requests_total{job="api-server"}[5m])

irate 應該僅在對易變且快速變化的計數器進行繪圖時使用。對於告警和緩慢變化的計數器，請使用 rate，因為瞬時變化率可能會重置 FOR 子句，而且完全由稀疏尖峰組成的圖表很難閱讀。

請注意，當將 irate() 與聚合運算子（例如 sum()）或隨時間聚合的函式（任何以 _over_time 結尾的函式）結合使用時，請務必先進行 irate() 計算，然後再進行聚合。否則，當目標重啟時，irate() 將無法檢測到計數器重置。

`label_join()`

對於 v 中的每個時間序列，label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...) 使用 separator 連線所有 src_labels 的值，並返回包含已連線值的帶有 dst_label 標籤的時間序列。在該函式中可以有任意數量的 src_labels。

label_join 以相同的方式作用於浮點樣本和直方圖樣本。

此示例將返回一個向量，其中每個時間序列都添加了一個值為 a,b,c 的 foo 標籤

label_join(up{job="api-server",src1="a",src2="b",src3="c"}, "foo", ",", "src1", "src2", "src3")

`label_replace()`

對於 v 中的每個時間序列，label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string) 將正則表示式 regex 與 src_label 標籤的值進行匹配。如果匹配成功，則返回的時間序列中 dst_label 標籤的值將是 replacement 的展開結果，連同輸入中的原始標籤。正則表示式中的捕獲組（capturing group）可以使用 $1、$2 等進行引用。正則表示式中的命名捕獲組可以使用 $name 進行引用（其中 name 是捕獲組名稱）。如果正則表示式不匹配，則原樣返回該時間序列。

label_replace 以相同的方式作用於浮點樣本和直方圖樣本。

此示例將返回在 service 標籤處具有值 a:c 且在 foo 標籤處具有值 a 的時間序列

label_replace(up{job="api-server",service="a:c"}, "foo", "$1", "service", "(.*):.*")

第二個示例具有與第一個示例相同的效果，並展示了命名捕獲組的使用方法

label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P<name>.*):(?P<version>.*)")

`max_of()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

max_of(a scalar, b scalar) 返回兩個標量值 a 和 b 中較大的那一個。

`min_of()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

min_of(a scalar, b scalar) 返回兩個標量值 a 和 b 中較小的那一個。

`ln()`

ln(v instant-vector) 計算 v 中所有浮點樣本的自然對數。輸入向量中的直方圖樣本會被靜默忽略。特殊情況包括

ln(+Inf) = +Inf
ln(0) = -Inf
ln(x < 0) = NaN
ln(NaN) = NaN

`log2()`

log2(v instant-vector) 計算 v 中所有浮點樣本的二進位制對數（以 2 為底的對數）。輸入向量中的直方圖樣本會被靜默忽略。其特殊情況與 ln 相同。

`log10()`

log10(v instant-vector) 計算 v 中所有浮點樣本的常用對數（以 10 為底的對數）。輸入向量中的直方圖樣本會被靜默忽略。其特殊情況與 ln 相同。

`minute()`

minute(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳所對應小時中的分鐘值（UTC 時間）。返回值的範圍是 0 到 59。輸入向量中的直方圖樣本會被靜默忽略。

`month()`

month(v=vector(time()) instant-vector) 將 v 中的浮點樣本解釋為時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數），並返回每個時間戳所對應的月份（UTC 時間）。返回值的範圍是 1 到 12，其中 1 代表一月，依此類推。輸入向量中的直方圖樣本會被靜默忽略。

`predict_linear()`

predict_linear(v range-vector, t scalar) 基於區間向量 v，使用簡單線性迴歸預測時間序列在 t 秒後的值。區間向量必須至少包含兩個浮點樣本才能進行計算。如果區間向量中存在 +Inf 或 -Inf，則預測值將為 NaN。

predict_linear 僅應與儀表（gauge）指標一起使用，且僅對浮點樣本有效。區間向量中僅包含直方圖樣本的元素將被完全忽略。對於混合包含浮點樣本和直方圖樣本的元素，僅使用浮點樣本作為輸入，這會伴隨一個資訊級別（info-level）的註解提示。

`range()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

range() 返回當前查詢範圍評估的時間跨度（以秒為單位），等價於 end() - start()。對於瞬時查詢，它將返回 0。

`rate()`

rate(v range-vector) 計算區間向量中時間序列的每秒平均增長率。單調性的中斷（例如由於目標重啟導致的計數器重置）會被自動調整。此外，該計算還會外推到時間範圍的邊界，以處理抓取丟失或抓取週期與時間範圍未完全對齊的情況。

以下示例表示式返回區間向量中每個時間序列在過去 5 分鐘內的每秒平均 HTTP 請求率

rate(http_requests_total{job="api-server"}[5m])

rate 作用於原生直方圖的方式是計算一個新的直方圖，其每個元件（觀測值的總和和計數、桶）都是 v 中第一個和最後一個原生直方圖中對應元件的增長率。然而，在時間範圍內混合包含浮點樣本和原生直方圖樣本的 v 中的任何元素，都將從結果向量中排除，並伴隨一個警告級別（warn-level）的註解提示。

rate 僅應與計數器指標（包括浮點數計數器和直方圖計數器）一起使用。它最適合用於告警，以及繪製變化緩慢的計數器的圖表。

請注意，當將 rate() 與聚合運算子（例如 sum()）或隨時間聚合的函式（任何以 _over_time 結尾的函式）結合使用時，務必先計算 rate()，然後再進行聚合。否則，在目標重啟時，rate() 將無法檢測到計數器重置。

`resets()`

對於每個輸入時間序列，resets(v range-vector) 以瞬時向量的形式返回在提供的時間範圍內的計數器重置次數。兩個連續浮點樣本之間值的任何下降都會被解釋為計數器重置。原生直方圖中的重置檢測更加複雜：任何桶（包括零值桶）或觀測值計數的減少都構成計數器重置，此外，任何之前有值的桶的消失、零值桶寬度的變窄，或者任何不屬於相容的解析度降低的模式（schema）更改，也都被視為計數器重置。

resets 應該僅用於計數器（包括浮點數計數器和直方圖計數器）。

浮點樣本後緊接直方圖樣本，或者反之，都算作一次重置。計數直方圖樣本後緊接儀表直方圖樣本，或者反之，也算作重置（但請注意，resets 本不應該用於儀表指標，見上文）。

`round()`

round(v instant-vector, to_nearest=1 scalar) 將 v 中所有元素的樣本值四捨五入到最接近的整數。遇到半數（.5）時向上取整。可選引數 to_nearest 允許指定樣本值應四捨五入到的最接近的倍數。該倍數也可以是小數。輸入向量中的直方圖樣本會被靜默忽略。

`scalar()`

給定一個僅包含一個浮點樣本元素的輸入向量，scalar(v instant-vector) 將該浮點樣本的值作為標量返回。如果輸入向量中不是恰好只有一個浮點樣本元素，scalar 將返回 NaN。輸入向量中的直方圖樣本會被靜默忽略。

`sgn()`

sgn(v instant-vector) 返回一個向量，其中所有浮點樣本值都被轉換為它們的正負號，定義如下：如果 v 為正，則返回 1；如果 v 為負，則返回 -1；如果 v 等於 0，則返回 0。輸入向量中的直方圖樣本會被靜默忽略。

`sort()`

sort(v instant-vector) 返回按浮點樣本值升序排列的向量元素。輸入向量中的直方圖樣本會被靜默忽略。

請注意，sort 僅影響瞬時查詢的結果，因為範圍查詢的結果總是具有固定的輸出順序。

`sort_desc()`

與 sort 相同，但按降序排列。

`sort_by_label()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

sort_by_label(v instant-vector, label string, ...) 返回按指定標籤值升序排列的向量元素。如果這些標籤值相同，則元素按其完整的標籤集進行排序。sort_by_label 對浮點樣本和直方圖樣本的作用方式相同。

請注意，sort_by_label 僅影響瞬時查詢的結果，因為範圍查詢的結果總是具有固定的輸出順序。

sort_by_label 使用自然排序順序。

`sort_by_label_desc()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

與 sort_by_label 相同，但按降序排列。

`sqrt()`

sqrt(v instant-vector) 計算 v 中所有浮點樣本的平方根。輸入向量中的直方圖樣本會被靜默忽略。

`start()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

start() 返回當前查詢範圍評估的開始時間戳，即自 UTC 時間 1970 年 1 月 1 日以來的秒數。對於瞬時查詢，這等於評估時間戳。

`step()`

該函式必須透過特性標誌 --enable-feature=promql-experimental-functions 啟用。

step() 以秒數形式返回查詢解析度步長。對於瞬時查詢，它返回 0。

`time()`

time() 返回自 UTC 時間 1970 年 1 月 1 日以來的秒數。請注意，這實際上並不返回當前時間，而是返回計算表示式的時間。

`timestamp()`

timestamp(v instant-vector) 返回給定向量中每個樣本的時間戳（自 UTC 時間 1970 年 1 月 1 日以來的秒數）。它對浮點樣本和直方圖樣本的作用方式相同。

`vector()`

vector(s scalar) 將標量 s 轉換為浮點樣本，並將其作為一個不帶標籤的單元素瞬時向量返回。

`year()`

year(v=vector(time()) instant-vector) 返回每個給定時間在 UTC 下的年份。輸入向量中的直方圖樣本會被靜默忽略。

`<aggregation>_over_time()`

以下函式允許隨時間聚合給定區間向量的每個序列，並返回一個包含每個序列聚合結果的瞬時向量

avg_over_time(range-vector)：指定區間內所有浮點或直方圖樣本的平均值（詳見下文）。
min_over_time(range-vector)：指定區間內所有浮點樣本的最小值。
max_over_time(range-vector)：指定區間內所有浮點樣本的最大值。
sum_over_time(range-vector)：指定區間內所有浮點或直方圖樣本的總和（詳見下文）。
count_over_time(range-vector)：指定區間內所有樣本的計數。
quantile_over_time(scalar, range-vector)：指定區間內所有浮點樣本的 φ-分位數 (0 ≤ φ ≤ 1)。
stddev_over_time(range-vector)：指定區間內所有浮點樣本的總體標準差。
stdvar_over_time(range-vector)：指定區間內所有浮點樣本的總體方差。
last_over_time(range-vector)：指定區間內最新的樣本。
present_over_time(range-vector)：指定區間內任何序列的值設為 1。

如果設定了特性標誌 --enable-feature=promql-experimental-functions，則以下附加函式可用

mad_over_time(range-vector)：指定區間內所有浮點樣本的絕對中位數偏差。
ts_of_min_over_time(range-vector)：指定區間內具有所有浮點樣本中最小值的最後一個浮點樣本的時間戳。
ts_of_max_over_time(range-vector)：指定區間內具有所有浮點樣本中最大值的最後一個浮點樣本的時間戳。
ts_of_last_over_time(range-vector)：指定區間內最新樣本的時間戳。
first_over_time(range-vector)：指定區間內最早的樣本。
ts_of_first_over_time(range-vector)：指定區間內最早樣本的時間戳。

請注意，指定區間內的所有值在聚合中都具有相同的權重，即使這些值在整個區間內的間隔並不均勻。

這些函式對直方圖的作用方式如下

count_over_time、first_over_time、last_over_time 和 present_over_time() 對浮點樣本和直方圖樣本的作用方式相同。
avg_over_time() 和 sum_over_time() 對直方圖樣本的作用方式與對應的聚合運算子一致。如果某個序列在時間範圍內混合包含了浮點樣本和直方圖樣本，則其對應的結果將完全從輸出向量中移除。這種移除會伴隨一個警告級別（warn-level）的註解提示。
所有其他函式以下列方式忽略直方圖樣本：僅包含直方圖樣本的輸入範圍會被靜默地從輸出中移除。對於包含直方圖樣本和浮點樣本的混合範圍，僅處理浮點樣本，而忽略直方圖樣本的操作會伴隨一個資訊級別（info-level）的註解提示。

first_over_time(m[1m]) 與 m offset 1m 的不同之處在於：前者將選擇 1 分鐘範圍*內* m 的第一個樣本，而 m offset 1m 將選擇 1 分鐘偏移*之外且在此之前*的回溯區間內的最新樣本。這在範圍查詢中與 first_over_time(m[step()]) 結合使用時尤其有用（在設定了 --enable-feature=promql-duration-expr 時可用），以確保選擇的樣本位於範圍步長之內。

三角函式

三角函式以弧度為單位。它們會忽略輸入向量中的直方圖樣本。

acos(v instant-vector)：計算 v 中所有浮點樣本的反餘弦值（特殊情況）。
acosh(v instant-vector)：計算 v 中所有浮點樣本的反雙曲餘弦值（特殊情況）。
asin(v instant-vector)：計算 v 中所有浮點樣本的反正弦值（特殊情況）。
asinh(v instant-vector)：計算 v 中所有浮點樣本的反雙曲正弦值（特殊情況）。
atan(v instant-vector)：計算 v 中所有浮點樣本的反正切值（特殊情況）。
atanh(v instant-vector)：計算 v 中所有浮點樣本的反雙曲正切值（特殊情況）。
cos(v instant-vector)：計算 v 中所有浮點樣本的餘弦值（特殊情況）。
cosh(v instant-vector)：計算 v 中所有浮點樣本的雙曲餘弦值（特殊情況）。
sin(v instant-vector)：計算 v 中所有浮點樣本的正弦值（特殊情況）。
sinh(v instant-vector)：計算 v 中所有浮點樣本的雙曲正弦值（特殊情況）。
tan(v instant-vector)：計算 v 中所有浮點樣本的正切值（特殊情況）。
tanh(v instant-vector)：計算 v 中所有浮點樣本的雙曲正切值（特殊情況）。

以下函式對於在角度和弧度之間進行轉換非常有用

deg(v instant-vector)：將 v 中所有浮點樣本的弧度轉換為角度。
pi()：返回圓周率 pi。
rad(v instant-vector)：將 v 中所有浮點樣本的角度轉換為弧度。

本頁內容

查詢函式

abs()

absent()

absent_over_time()

ceil()

changes()

clamp()

clamp_max()

clamp_min()

day_of_month()

day_of_week()

day_of_year()

days_in_month()

delta()

deriv()

end()

double_exponential_smoothing()

exp()

floor()

histogram_avg()

histogram_count() 和 histogram_sum()

histogram_fraction()

histogram_quantile()

histogram_quantiles()

histogram_stddev() 和 histogram_stdvar()

hour()

idelta()

increase()

info()

限制

irate()

label_join()

label_replace()

max_of()

min_of()

ln()

log2()

log10()

minute()

month()

predict_linear()

range()

rate()

resets()

round()

scalar()

sgn()

sort()

sort_desc()

sort_by_label()

sort_by_label_desc()

sqrt()

start()

step()

time()

timestamp()

vector()

year()

<aggregation>_over_time()

三角函式

`abs()`

`absent()`

`absent_over_time()`

`ceil()`

`changes()`

`clamp()`

`clamp_max()`

`clamp_min()`

`day_of_month()`

`day_of_week()`

`day_of_year()`

`days_in_month()`

`delta()`

`deriv()`

`end()`

`double_exponential_smoothing()`

`exp()`

`floor()`

`histogram_avg()`

`histogram_count()` 和 `histogram_sum()`

`histogram_fraction()`

`histogram_quantile()`

`histogram_quantiles()`

`histogram_stddev()` 和 `histogram_stdvar()`

`hour()`

`idelta()`

`increase()`

`info()`

`irate()`

`label_join()`

`label_replace()`

`max_of()`

`min_of()`

`ln()`

`log2()`

`log10()`

`minute()`

`month()`

`predict_linear()`

`range()`

`rate()`

`resets()`

`round()`

`scalar()`

`sgn()`

`sort()`

`sort_desc()`

`sort_by_label()`

`sort_by_label_desc()`

`sqrt()`

`start()`

`step()`

`time()`

`timestamp()`

`vector()`

`year()`

`<aggregation>_over_time()`