クエリ関数

一部の関数にはデフォルト引数があります。例：year(v=vector(time()) instant-vector)。これは、引数 v がインスタントベクトルであり、提供されない場合は式 vector(time()) の値にデフォルト設定されることを意味します。

`abs()`

abs(v instant-vector) は、入力ベクトル内のすべての浮動小数点サンプルを絶対値に変換したベクトルを返します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`absent()`

absent(v instant-vector) は、渡されたベクトルに要素（浮動小数点サンプルまたはヒストグラムサンプル）がある場合は空のベクトルを返し、渡されたベクトルに要素がない場合は値 1 の 1 要素ベクトルを返します。

これは、特定のメトリック名とラベルの組み合わせに対して時系列が存在しない場合にアラートを出すのに役立ちます。

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

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

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

最初の 2 つの例では、absent() は入力ベクトルから 1 要素出力ベクトルのラベルを導き出そうとします。

`absent_over_time()`

absent_over_time(v range-vector) は、渡されたレンジベクトルに要素（浮動小数点サンプルまたはヒストグラムサンプル）がある場合は空のベクトルを返し、渡されたレンジベクトルに要素がない場合は値 1 の 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:])
# => {}

最初の 2 つの例では、absent_over_time() は入力ベクトルから 1 要素出力ベクトルのラベルを導き出そうとします。

`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) は、指定された時間範囲内で値が変更された回数をインスタントベクトルとして返します。浮動小数点サンプルとヒストグラムサンプルの前後関係、またはその逆は変更としてカウントされます。同じ値を持つカウンターヒストグラムサンプルとゲージヒストグラムサンプルの前後関係、またはその逆は変更としてカウントされません。

`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 内の浮動小数点サンプルをタイムスタンプ（1970 年 1 月 1 日 UTC からの経過秒数）として解釈し、各タイムスタンプの月の日（UTC）を返します。返される値は 1 から 31 です。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`day_of_week()`

day_of_week(v=vector(time()) instant-vector) は、v 内の浮動小数点サンプルをタイムスタンプ（1970 年 1 月 1 日 UTC からの経過秒数）として解釈し、各タイムスタンプの曜（UTC）を返します。返される値は 0 から 6 で、0 は日曜日などを意味します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`day_of_year()`

day_of_year(v=vector(time()) instant-vector) は、v 内の浮動小数点サンプルをタイムスタンプ（1970 年 1 月 1 日 UTC からの経過秒数）として解釈し、各タイムスタンプの年内の日数（UTC）を返します。返される値は、平年は 1 から 365、うるう年は 1 から 366 です。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`days_in_month()`

days_in_month(v=vector(time()) instant-vector) は、v 内の浮動小数点サンプルをタイムスタンプ（1970 年 1 月 1 日 UTC からの経過秒数）として解釈し、各タイムスタンプの月の日数（UTC）を返します。返される値は 28 から 31 です。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`delta()`

delta(v range-vector) は、レンジベクトル v 内の各時系列要素の最初の値と最後の値の差を計算し、指定された差と等価なラベルを持つインスタントベクトルを返します。差はレンジベクトルセレクターで指定された時間範囲全体をカバーするように外挿されるため、サンプル値がすべて整数の場合でも非整数結果が得られる可能性があります。

以下の例の式は、現在から 2 時間前の CPU 温度の差を返します。

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

delta はヒストグラムサンプルに対して、v 内の最初と最後のネイティブヒストグラムのそれぞれのコンポーネント（観測の合計と数、バケット）の差を計算した新しいヒストグラムを計算します。ただし、範囲内に浮動小数点サンプルとヒストグラムサンプルの両方が含まれる v の要素は、警告レベルのアノテーションでフラグ付けされ、結果ベクトルから除外されます。

delta はゲージ（浮動小数点およびヒストグラムの両方）でのみ使用する必要があります。

`deriv()`

deriv(v range-vector) は、レンジベクトル v 内の各浮動小数点時系列の 1 秒あたりの導関数を、単純線形回帰を使用して計算します。レンジベクトルには、計算を実行するために少なくとも 2 つの浮動小数点サンプルが必要です。レンジベクトルに +Inf または -Inf が見つかった場合、計算された傾きとオフセット値は NaN になります。

deriv はゲージでのみ使用する必要があり、浮動小数点サンプルでのみ機能します。ヒストグラムサンプルのみを含むレンジベクトルの要素は完全に無視されます。浮動小数点サンプルとヒストグラムサンプルの両方を含む要素の場合、浮動小数点サンプルのみが入力として使用されます。これは情報レベルのアノテーションでフラグ付けされます。

`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 Linear」とも呼ばれます。

double_exponential_smoothing はゲージでのみ使用する必要があり、浮動小数点サンプルでのみ機能します。ヒストグラムサンプルのみを含むレンジベクトルの要素は完全に無視されます。浮動小数点サンプルとヒストグラムサンプルの両方を含む要素の場合、浮動小数点サンプルのみが入力として使用されます。これは情報レベルのアノテーションでフラグ付けされます。

`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 内の各ヒストグラムサンプルに格納されている観測値の算術平均を返します。浮動小数点サンプルは無視され、結果ベクトルには表示されません。

ネイティブヒストグラムから 5 分間のウィンドウにわたる平均リクエスト期間を計算するために、以下のように histogram_avg を使用します。

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 に含まれる各クラシックまたはネイティブヒストグラムについて、指定された下限と上限の値の間の観測値の推定割合を返します。b 内の浮動小数点サンプルは、1 つ以上のクラシックヒストグラムの各バケットの観測値の数と見なされます。一方、b 内のネイティブヒストグラムサンプルは、それぞれ個別にヒストグラムとして扱われます。これは histogram_quantile() と同じように機能します。（詳細についてはそちらを参照してください。）

指定された下限と上限の値がバケット境界と一致しない場合、計算された割合は推定値になります。この推定には、histogram_quantile() と同じ補間方法が使用されます。（詳細についてはそちらを参照してください。）特にクラシックヒストグラムでは、バケット境界から非常に離れた下限または上限の値を選択してしまうことが容易であり、誤差が大きくなります。クラシックヒストグラムで histogram_fraction() を使用する代わりに、割合を計算する際に直接バケット系列を操作する方が堅牢なアプローチとなることがよくあります。Apdex スコアの計算を典型的な例として参照してください。

たとえば、次の式は、過去 1 時間のリクエストのうち、200ms 以下であったリクエストの割合を計算します。

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

推定誤差は、基になるネイティブヒストグラムの解像度と、指定された境界がヒストグラムのバケット境界にどれだけ近く整列しているかによって異なります。

+Inf および -Inf は有効な境界値です。たとえば、上記の式でヒストグラムに負の観測値（リクエスト期間では通常発生しないはずですが）が含まれていた場合、0.2 以下すべての観測値を含めるための適切な下限は、0 ではなく -Inf になります。

指定された境界が包括的か排他的かは、指定された境界が基になるネイティブヒストグラムのバケット境界に正確に整列している場合にのみ関連します。この場合、動作はヒストグラムのスキーマ定義に依存します。（通常の標準指数スキーマはすべて、正の値に対しては上限が包括的で下限が排他的、負の値に対してはその逆です。）境界が正確に整列していない場合、関数は補間を使用して割合を推定します。結果の不確実性により、境界が包括的か排他的かは関係なくなります。

標準指数バケットを持つネイティブヒストグラムの特殊ケース：NaN 観測値は、この場合、どのバケットにも含まれないと見なされます。histogram_fraction(-Inf, +Inf, b) は実質的に非 NaN 観測値の割合を返し、したがって 1 未満になる可能性があります。

`histogram_quantile()`

histogram_quantile(φ scalar, b instant-vector) は、クラシックヒストグラムまたはネイティブヒストグラムから φ-分位数（0 ≤ φ ≤ 1）を計算します。（φ-分位数および（クラシック）ヒストグラムメトリックタイプの一般的な使用方法の詳細については、ヒストグラムとサマリーを参照してください。）

b 内の浮動小数点サンプルは、1 つ以上のクラシックヒストグラムの各バケットの観測値の数と見なされます。各浮動小数点サンプルには、バケットの包括的な上限を示す 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() アグリゲータで囲みます。le ラベルはクラシックヒストグラムを処理するために histogram_quantile() で必要とされるため、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() 関数は、分位数値が入るバケット内で分位数値を補間します。クラシックヒストグラム、カスタムバケット境界を持つネイティブヒストグラム、およびその他のネイティブヒストグラムのゼロバケットでは、バケット内の観測値が均一に分布すると仮定します（「線形補間」とも呼ばれます）。標準指数バケットを持つネイティブヒストグラムの非ゼロバケットでは、より高解像度の仮想ヒストグラムでバケットを均一に埋めるように観測値が分布していると仮定して補間が行われます。（「指数補間」とも呼ばれます。詳細については、ネイティブヒストグラム仕様を参照してください。）

b の観測値が 0 の場合、NaN が返されます。φ < 0 の場合、-Inf が返されます。φ > 1 の場合、+Inf が返されます。φ = NaN の場合、NaN が返されます。

クラシックヒストグラムの特殊ケース

b に 2 つ未満のバケットが含まれている場合、NaN が返されます。
最も高いバケットには +Inf という上限が必要です。（それ以外の場合、NaN が返されます。）
分位数が最も高いバケットにある場合、2 番目に高いバケットの上限が返されます。
最も低いバケットの最小値は、そのバケットの上限が 0 より大きい場合、0 と仮定されます。この場合、そのバケット内では通常の線形補間が適用されます。それ以外の場合、分位数が最も低いバケットにある場合、最も低いバケットの上限が返されます。

ネイティブヒストグラムの特殊ケース

標準指数バケットを持つネイティブヒストグラムに NaN 観測値があり、分位数が既存の指数バケットのいずれかに入っている場合、NaN 観測値が +Inf として扱われるため、結果はより高い値に偏ります。これは情報レベルのアノテーションでフラグ付けされます。
標準指数バケットを持つネイティブヒストグラムに NaN 観測値があり、分位数が既存の指数バケットのすべてを超える場合、NaN が返されます。これは情報レベルのアノテーションでフラグ付けされます。
有限幅のゼロバケットは、ヒストグラムに正のバケットに観測値があるが、負のバケットにはない場合、負の観測値が含まれていないと仮定されます。
有限幅のゼロバケットは、ヒストグラムに負のバケットに観測値があるが、正のバケットにはない場合、正の観測値が含まれていないと仮定されます。

histogram_quantile(0, v instant-vector) を使用すると、ヒストグラムに格納されている推定最小値を取得できます。

histogram_quantile(1, v instant-vector) を使用すると、ヒストグラムに格納されている推定最大値を取得できます。

クラシックヒストグラムのバケットは累積的です。したがって、次のことが常に成り立つはずです。

バケット内の数は単調増加（厳密に非減少）します。
2 つの連続するバケットの上限の間に観測値がない場合、それらの 2 つのバケットに同じ数が格納されます。

しかし、浮動小数点精度の問題（たとえば、sum(rate(...)) の計算によって導入されたわずかな差異）や無効なデータにより、これらの仮定が満たされない場合があります。その場合、histogram_quantile は意味のある結果を返せません。この問題を軽減するために、histogram_quantile は、2 つの連続するバケット間のわずかな相対差は浮動小数点精度のエラーによるものと仮定し、それらを無視します。（差を無視するしきい値は、両方のバケットの合計の 1 兆分の 1（1e-12）です。）さらに、この調整後も非単調なバケット数がある場合、それらは前のバケットの値に増やされて単調性が強制されます。後者は実際の問題の証拠であるため、input to histogram_quantile needed to be fixed for monotonicity という情報レベルのアノテーションでフラグ付けされます。このアノテーションが表示された場合は、無効なデータのソースを見つけて削除する必要があります。

`histogram_stddev()` と `histogram_stdvar()`

histogram_stddev(v instant-vector) は、v 内の各ヒストグラムサンプルの観測値の推定標準偏差を返します。この推定のために、バケット内のすべての観測値は、バケット境界の平均値を持つと仮定されます。ゼロバケットおよびカスタム境界を持つバケットでは、算術平均が使用されます。通常の指数バケットでは、幾何平均が使用されます。浮動小数点サンプルは無視され、結果ベクトルには表示されません。

同様に、histogram_stdvar(v instant-vector) は、v 内の各ヒストグラムサンプルの観測値の推定標準分散を返します。

`hour()`

hour(v=vector(time()) instant-vector) は、v 内の float サンプルをタイムスタンプ（UTC 1970年1月1日からの経過秒数）として解釈し、各タイムスタンプの 1 日の時（UTC）を返します。返される値は 0 から 23 までです。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`idelta()`

idelta(v range-vector) は、範囲ベクトル v の最後の 2 つのサンプルの差を計算し、指定された差分と等価なラベルを持つ instant vector を返します。両方のサンプルは float サンプルまたはヒストグラムサンプルのいずれかでなければなりません。最後の 2 つのサンプルのいずれかが float サンプルで、もう一方がヒストグラムサンプルである v の要素は、結果ベクトルから省略され、warn レベルのアノテーションでフラグが付けられます。

idelta は、ゲージ（float およびヒストグラムの両方）でのみ使用する必要があります。

`increase()`

increase(v range-vector) は、範囲ベクトル内の時系列の増加量を計算します。単調性の断絶（ターゲットの再起動によるカウンターリセットなど）は自動的に調整されます。増加量は、範囲ベクトルセレクターで指定された時間範囲全体をカバーするように外挿されるため、カウンターが整数インクリメントのみで増加する場合でも非整数結果が得られる可能性があります。

以下の例の式は、範囲ベクトル内の各時系列ごとに、過去 5 分間に測定された HTTP リクエスト数を返します。

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

increase は、ヒストグラムサンプルに対して、v 内の最初のネイティブヒストグラムと最後のネイティブヒストグラムの各コンポーネント（観測の合計とカウント、バケット）の増加量から新しいヒストグラムを計算することによって作用します。ただし、範囲内に float サンプルとヒストグラムサンプルの混合が含まれる v の各要素は、結果ベクトルから省略され、warn レベルのアノテーションでフラグが付けられます。

increase は、カウンター（float およびヒストグラムの両方）でのみ使用する必要があります。これは rate(v) に指定された時間範囲の秒数を乗算したもののシンタックスシュガーであり、主に人間が読みやすくするために使用されます。recording rule では rate を使用して、増加量を秒単位で一貫して追跡するようにしてください。

`info()`

info 関数は、info metricsのラベルを含める際の UX を改善するための実験的な機能です。この関数の動作は、PromQL からの削除を含む、将来の Prometheus のバージョンで変更される可能性があります。info は、`--enable-feature=promql-experimental-functions` の feature flag を介して有効にする必要があります。

info(v instant-vector, [data-label-selector instant-vector]) は、v 内の各時系列に対して、*識別*ラベルが一致するすべての info series を検索し（詳細は後述）、それらの *data* （つまり、識別以外の）ラベルの和集合を時系列に追加します。2 番目の引数 data-label-selector はオプションです。これは実際の instant vector ではありませんが、その構文の一部を使用します。波括弧（{ ... }）で始まり、波括弧で終わる必要があり、ラベルマッチングのみを含むことができます。ラベルマッチングは、どの info series を考慮し、どの data labels を v に追加するかを制限するために使用されます。

info series の識別ラベルは、info series を一意に識別するラベルのサブセットです。残りのラベルは *data labels*（非識別ラベルとも呼ばれます）と見なされます。（Prometheus の時系列識別子の概念には常に *すべての* ラベルが含まれることに注意してください。info 関数の目的のために、従来の Prometheus のビューとは異なる方法で info series の識別を「論理的」に定義します。）info series の識別ラベルは、通常の（info でない）series、つまり識別ラベルと同じラベルを持つ series に結合するために使用されます。data labels は、info 関数によって通常の series に追加されるもので、メタデータのキーと値のペアを効果的にエンコードします。（これは、従来の Prometheus のビューでの data labels の変更が、ある info series の終了と新しい info series の開始を構成することを意味しますが、info 関数の「論理的」ビューでは、同じ info series が異なる「data」で存在し続けるということです。）

data labels を追加する従来の一般的なアプローチは、以下の例で示されるように、「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 から data labels を追加するには、どの info metric を使用するか（target_info）、識別ラベルは何か（on (job, instance)）、どの data labels を追加するか（group_left (k8s_cluster_name)）を指定するために、複雑で（あまり明白ではない）構文を使用する必要があります。

このクエリは、冗長で記述が難しいだけでなく、「アイデンティティクライシス」に陥る可能性もあります。target_info の data labels のいずれかが変更された場合、Prometheus はそれを series の変更と見なします（前述のように、Prometheus は非識別ラベルのネイティブな概念を持っていません）。古い target_info series が適切に stale としてマークされていない場合（特定のエングレスパスで発生する可能性があります）、クエリは 5m（lookback delta）まで失敗します。これは、古い target_info と新しい target_info の両方で競合するマッチが見つかるためです。

info 関数は、この競合を新しい series の方に解決するだけでなく、利用可能な info series とそれらの識別ラベルを把握しているため、構文を簡略化します。例のクエリは、info 関数を使用すると次のようになります。

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

すべての data labels を追加するという一般的なケースは、info 関数の 2 番目の引数を省略することで達成でき、例はさらに簡略化されます。

info(rate(http_server_request_duration_seconds_count[2m]))

info は通常、すべてのマッチする info series を自動的に検索しますが、__name__ ラベルマッチングを提供することで制限できます。例: {__name__="target_info"}。

制限事項

現在のバージョンでは、info はデフォルトで target_info という名前の info series のみを考慮します。また、識別 info series ラベルが instance と job であると仮定します。info は、__name__ ラベルマッチングを介して、他の info series 名もサポートしています。例: target_info と build_info の両方を考慮するには、次のように指定します: {__name__=~"(target|build)_info"}。ただし、識別ラベルは常に instance と job である必要があります。

これらの制限は、info 関数の目的を部分的に無効にしています。現在の段階では、このアプローチが実際にどれほど役立つかを見つけるための実験です。最終的な info 関数のバージョンは、すべてのマッチする info series とそれらに適した識別ラベルを考慮します。

`irate()`

irate(v range-vector) は、範囲ベクトル内の時系列の 1 秒あたりの即時増加率を計算します。これは最後の 2 つのデータポイントに基づいています。単調性の断絶（ターゲットの再起動によるカウンターリセットなど）は自動的に調整されます。両方のサンプルは float サンプルまたはヒストグラムサンプルのいずれかでなければなりません。最後の 2 つのサンプルのいずれかが float サンプルで、もう一方がヒストグラムサンプルである v の要素は、結果ベクトルから省略され、warn レベルのアノテーションでフラグが付けられます。

irate は、カウンター（float およびヒストグラムの両方）でのみ使用する必要があります。

以下の例の式は、範囲ベクトル内の各時系列ごとに、過去 5 分間を遡って、最も最近の 2 つのデータポイントに基づいて HTTP リクエストの 1 秒あたりのレートを返します。

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

irate は、揮発性で急激に変動するカウンターをグラフ化する場合にのみ使用してください。アラートやゆっくり変動するカウンターには rate を使用してください。なぜなら、レートの短い変化で FOR 句がリセットされる可能性があり、まれなスパイクのみで構成されるグラフは読みにくくなるためです。

irate() を集計演算子（例: sum()）や時間集計関数（_over_time で終わる任意の関数）と組み合わせる場合は、常にまず irate() を適用し、その後集計してください。そうしないと、ターゲットが再起動したときに irate() がカウンターリセットを検出できなくなります。

`label_join()`

label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...) は、v 内の各時系列について、指定された src_labels のすべての値を separator を使用して結合し、結合された値を含む dst_label ラベルを持つ時系列を返します。この関数では、src_labels の数はいくつでも構いません。

label_join は、float サンプルとヒストグラムサンプルに同じように作用します。

この例では、各時系列に foo ラベルが追加され、その値が a,b,c になるベクトルが返されます。

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

`label_replace()`

label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string) は、v 内の各時系列について、src_label の値に対して正規表現 regex をマッチさせます。マッチした場合、返される時系列の dst_label ラベルの値は replacement の展開結果となり、元のラベルも保持されます。正規表現のキャプチャグループは $1、$2 などで参照できます。名前付きキャプチャグループは $name（name はキャプチャグループ名）で参照できます。正規表現がマッチしない場合は、時系列は変更されずに返されます。

label_replace は、float サンプルとヒストグラムサンプルに同じように作用します。

この例では、service ラベルの値が a:c、foo ラベルの値が a である時系列が返されます。

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

この 2 番目の例は、最初の例と同じ効果を持ち、名前付きキャプチャグループの使用を示しています。

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

`ln()`

ln(v instant-vector) は、v 内のすべての float サンプルの自然対数を計算します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。特殊なケースは次のとおりです。

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

`log2()`

log2(v instant-vector) は、v 内のすべての float サンプルの 2 進対数を計算します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。特殊なケースは ln と同等です。

`log10()`

log10(v instant-vector) は、v 内のすべての float サンプルの 10 進対数を計算します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。特殊なケースは ln と同等です。

`minute()`

minute(v=vector(time()) instant-vector) は、v 内の float サンプルをタイムスタンプ（UTC 1970年1月1日からの経過秒数）として解釈し、各タイムスタンプの時の中の分（UTC）を返します。返される値は 0 から 59 までです。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`month()`

month(v=vector(time()) instant-vector) は、v 内の float サンプルをタイムスタンプ（UTC 1970年1月1日からの経過秒数）として解釈し、各タイムスタンプの年の月（UTC）を返します。返される値は 1 から 12 までで、1 は 1 月などを意味します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`predict_linear()`

predict_linear(v range-vector, t scalar) は、範囲ベクトル v に基づいて、*t* 秒後の時系列の値を単純線形回帰を使用して予測します。simple linear regression。計算を実行するには、範囲ベクトルに少なくとも 2 つの float サンプルが必要です。範囲ベクトルに +Inf または -Inf が見つかると、予測値は NaN になります。

predict_linear は、ゲージでのみ使用する必要があり、float サンプルに対してのみ機能します。ヒストグラムサンプルのみを含む範囲ベクトル内の要素は完全に無視されます。ヒストグラムサンプルと float サンプルの混合を含む要素の場合、float サンプルのみが入力として使用され、ヒストグラムサンプルの省略は info レベルのアノテーションでフラグが付けられます。

`rate()`

rate(v range-vector) は、範囲ベクトル内の時系列の 1 秒あたりの平均増加率を計算します。単調性の断絶（ターゲットの再起動によるカウンターリセットなど）は自動的に調整されます。また、計算は時間範囲の終点まで外挿され、スクレイプの欠落やスクレイプサイクルと時間範囲の期間との不完全なアライメントを考慮できます。

以下の例の式は、範囲ベクトル内の各時系列ごとに、過去 5 分間の HTTP リクエストの 1 秒あたりの平均レートを返します。

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

rate は、ネイティブヒストグラムに対して、新しいヒストグラムを計算することによって作用します。このヒストグラムでは、各コンポーネント（観測の合計とカウント、バケット）は、v 内の最初のネイティブヒストグラムと最後のネイティブヒストグラムの各コンポーネントの増加率です。ただし、範囲内に float サンプルとネイティブヒストグラムサンプルの混合が含まれる v の各要素は、結果ベクトルから省略され、warn レベルのアノテーションでフラグが付けられます。

rate は、カウンター（float およびヒストグラムの両方）でのみ使用する必要があります。アラートやゆっくり変動するカウンターのグラフ化に最適です。

rate() を集計演算子（例: sum()）や時間集計関数（_over_time で終わる任意の関数）と組み合わせる場合は、常にまず rate() を適用し、その後集計してください。そうしないと、ターゲットが再起動したときに rate() がカウンターリセットを検出できなくなります。

`resets()`

resets(v range-vector) は、各入力時系列について、提供された時間範囲内のカウンターリセット数を instant vector として返します。連続する float サンプルの値の減少は、カウンターリセットとして解釈されます。ネイティブヒストグラムのリセットは、より複雑な方法で検出されます。バケット（ゼロバケットを含む）のいずれかの値の減少、観測カウントの減少、またはゼロバケットの幅の減少、または互換性のない解像度の低下ではないスキーマ変更は、カウンターリセットと見なされます。

resets は、カウンター（float およびヒストグラムの両方）でのみ使用する必要があります。

float サンプルに続いてヒストグラムサンプル、またはその逆はリセットと見なされます。カウンターヒストグラムサンプルに続いてゲージヒストグラムサンプル、またはその逆もリセットと見なされます（ただし、resets はそもそもゲージには使用すべきではありません。上記参照）。

`round()`

round(v instant-vector, to_nearest=1 scalar) は、v 内のすべての要素のサンプル値を最も近い整数に丸めます。同点の場合は切り上げます。オプションの to_nearest 引数を使用すると、サンプル値を丸める最も近い倍数を指定できます。この倍数は分数でも構いません。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`scalar()`

float サンプルを 1 つだけ含む入力ベクトルが与えられた場合、scalar(v instant-vector) はその float サンプルのサンプル値を scalar として返します。入力ベクトルに float サンプルが 1 つだけ含まれていない場合、scalar は NaN を返します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`sgn()`

sgn(v instant-vector) は、すべての float サンプル値を符号に変換したベクトルを返します。定義は次のとおりです。v が正の場合は 1、v が負の場合は -1、v がゼロの場合は 0。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`sort()`

sort(v instant-vector) は、float サンプル値で昇順にソートされたベクトル要素を返します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

sort は instant query の結果にのみ影響します。range query の結果は常に固定の出力順序を持つことに注意してください。

`sort_desc()`

sort と同じですが、降順にソートします。

`sort_by_label()`

この関数は、機能フラグ --enable-feature=promql-experimental-functions を通じて有効にする必要があります。

sort_by_label(v instant-vector, label string, ...) は、指定されたラベルの値で昇順にソートされたベクトル要素を返します。これらのラベル値が等しい場合、要素は完全なラベルセットでソートされます。sort_by_label は float サンプルとヒストグラムサンプルに同じように作用します。

sort_by_label は instant query の結果にのみ影響します。range query の結果は常に固定の出力順序を持つことに注意してください。

sort_by_label は、natural sort order を使用します。

`sort_by_label_desc()`

この関数は、機能フラグ --enable-feature=promql-experimental-functions を通じて有効にする必要があります。

sort_by_label と同じですが、降順にソートします。

`sqrt()`

sqrt(v instant-vector) は、v 内のすべての float サンプルの平方根を計算します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`time()`

time() は、UTC 1970年1月1日からの経過秒数を返します。これは実際には現在時刻を返すのではなく、式が評価される時刻を返すことに注意してください。

`timestamp()`

timestamp(v instant-vector) は、指定されたベクトルの各サンプルのタイムスタンプを、UTC 1970年1月1日からの経過秒数として返します。float サンプルとヒストグラムサンプルに同じように作用します。

`vector()`

vector(s scalar) は、scalar s を float サンプルに変換し、ラベルのない単一要素の instant vector として返します。

`year()`

year(v=vector(time()) instant-vector) は、UTC における指定された各タイムスタンプの年を返します。入力ベクトル内のヒストグラムサンプルはサイレントに無視されます。

`<aggregation>_over_time()`

以下の関数は、指定された範囲ベクトルの各 series を時間とともに集計し、series ごとの集計結果を持つ instant vector を返します。

avg_over_time(range-vector): 指定された間隔内のすべての float またはヒストグラムサンプルの平均値（詳細は下記参照）。
min_over_time(range-vector): 指定された間隔内のすべての float サンプルの最小値。
max_over_time(range-vector): 指定された間隔内のすべての float サンプルの最大値。
sum_over_time(range-vector): 指定された間隔内のすべての float またはヒストグラムサンプルの合計値（詳細は下記参照）。
count_over_time(range-vector): 指定された間隔内のすべてのサンプルのカウント。
quantile_over_time(scalar, range-vector): 指定された間隔内のすべての float サンプルの φ-quantile（0 ≤ φ ≤ 1）。
stddev_over_time(range-vector): 指定された間隔内のすべての float サンプルの母標準偏差。
stdvar_over_time(range-vector): 指定された間隔内のすべての float サンプルの母標準分散。
last_over_time(range-vector): 指定された間隔内の最新のサンプル。
present_over_time(range-vector): 指定された間隔内の任意の series に対して 1 の値。

--enable-feature=promql-experimental-functions の feature flag が設定されている場合、以下の追加関数が利用可能です。

mad_over_time(range-vector): 指定された間隔内のすべての float サンプルの中央絶対偏差。
ts_of_min_over_time(range-vector): 指定された間隔内のすべての float サンプルの最小値を持つ、最後の float サンプルのタイムスタンプ。
ts_of_max_over_time(range-vector): 指定された間隔内のすべての float サンプルの最大値を持つ、最後の float サンプルのタイムスタンプ。
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() は、float サンプルとヒストグラムサンプルに同じように作用します。
avg_over_time() および sum_over_time() は、対応する集計演算子に対応する方法でヒストグラムサンプルに作用します。series が範囲内に float サンプルとヒストグラムサンプルの混合を含む場合、対応する結果は出力ベクトルから完全に削除されます。そのような削除は、warn レベルのアノテーションでフラグが付けられます。
他のすべての関数は、ヒストグラムサンプルを次のように無視します。ヒストグラムサンプルのみを含む入力範囲は、出力からサイレントに削除されます。ヒストグラムサンプルと float サンプルの混合を含む範囲の場合、float サンプルのみが処理され、ヒストグラムサンプルの省略は info レベルのアノテーションでフラグが付けられます。

first_over_time(m[1m]) は m offset 1m とは異なります。前者は 1m の範囲 *内* の m の最初のサンプルを選択しますが、m offset 1m は 1m オフセット *より前* のルックバック間隔内の最新サンプルを選択します。これは、first_over_time(m[step()]) を range query で使用する場合（--enable-feature=promql-duration-expr が設定されている場合に使用可能）に特に役立ち、選択されたサンプルが range step 内にあることを保証します。

三角関数

三角関数はラジアンで動作します。入力ベクトル内のヒストグラムサンプルを無視します。

acos(v instant-vector): v 内のすべての float サンプルの逆余弦を計算します（special cases）。
acosh(v instant-vector): v 内のすべての float サンプルの逆双曲線余弦を計算します（special cases）。
asin(v instant-vector): v 内のすべての float サンプルの逆正弦を計算します（special cases）。
asinh(v instant-vector): v 内のすべての float サンプルの逆双曲線正弦を計算します（special cases）。
atan(v instant-vector): v 内のすべての float サンプルの逆正接を計算します（special cases）。
atanh(v instant-vector): v 内のすべての float サンプルの逆双曲線正接を計算します（special cases）。
cos(v instant-vector): v 内のすべての float サンプルの余弦を計算します（special cases）。
cosh(v instant-vector): v 内のすべての float サンプルの双曲線余弦を計算します（special cases）。
sin(v instant-vector): v 内のすべての float サンプルの正弦を計算します（special cases）。
sinh(v instant-vector): v 内のすべての float サンプルの双曲線正弦を計算します（special cases）。
tan(v instant-vector): v 内のすべての float サンプルの正接を計算します（special cases）。
tanh(v instant-vector): v 内のすべての float サンプルの双曲線正接を計算します（special cases）。

以下は、度とラジアンの変換に役立ちます。

deg(v instant-vector): v 内のすべての float サンプルをラジアンから度に変換します。
pi(): π を返します。
rad(v instant-vector): v 内のすべての float サンプルを度からラジアンに変換します。

このページの内容

クエリ関数

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()

double_exponential_smoothing()

exp()

floor()

histogram_avg()

histogram_count() と histogram_sum()

histogram_fraction()

histogram_quantile()

histogram_stddev() と histogram_stdvar()

hour()

idelta()

increase()

info()

制限事項

irate()

label_join()

label_replace()

ln()

log2()

log10()

minute()

month()

predict_linear()

rate()

resets()

round()

scalar()

sgn()

sort()

sort_desc()

sort_by_label()

sort_by_label_desc()

sqrt()

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()`

`double_exponential_smoothing()`

`exp()`

`floor()`

`histogram_avg()`

`histogram_count()` と `histogram_sum()`

`histogram_fraction()`

`histogram_quantile()`

`histogram_stddev()` と `histogram_stdvar()`

`hour()`

`idelta()`

`increase()`

`info()`

`irate()`

`label_join()`

`label_replace()`

`ln()`

`log2()`

`log10()`

`minute()`

`month()`

`predict_linear()`

`rate()`

`resets()`

`round()`

`scalar()`

`sgn()`

`sort()`

`sort_desc()`

`sort_by_label()`

`sort_by_label_desc()`

`sqrt()`

`time()`

`timestamp()`

`vector()`

`year()`

`<aggregation>_over_time()`