クエリ関数

いくつかの関数にはデフォルト引数があります。例えば、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 Engineering Statistics Handbook を参照してください。Prometheus V2 では、この関数は holt_winters と呼ばれていました。Holt-Winters 法は通常、三重指数平滑化を指すため、混乱が生じていました。ここで実装されている二重指数平滑化は「Holt線形」とも呼ばれます。

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

下記のように 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) は、各ヒストグラムサンプルに格納されている観測値の合計を返します。

ヒストグラムサンプルの系列から観測値のレート（この場合は「1秒あたりのリクエスト数」に対応）を計算するには、次の方法で 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以下だったHTTPリクエストの割合を計算します。

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）の場合。過去10分間のリクエスト期間の90パーセンタイルを計算するには、http_request_duration_seconds が従来のヒストグラムである場合、以下の式を使用します。

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() 関数は、パーセンタイル値が属するバケット内でパーセンタイル値を補間します。従来のヒストグラムの場合、カスタムバケット境界を持つネイティブヒストグラムの場合、および他のネイティブヒストグラムのゼロバケットの場合、バケット内の観測値が均一に分布していると仮定します（これは 線形補間 とも呼ばれます）。標準の指数バケットスキームを持つネイティブヒストグラムの非ゼロバケットの場合、補間は、バケット内のサンプルが、より高い解像度の仮想ヒストグラム内のバケットを均一に埋めるように分布しているという仮定の下で行われます。（これは 指数補間 とも呼ばれます。詳細についてはネイティブヒストグラムの仕様を参照してください。）

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

`idelta()`

idelta(v range-vector) は、レンジベクタ v 内の最後の2つのサンプル間の差を計算し、与えられた差と等価なラベルを持つインスタントベクタを返します。両方のサンプルは、浮動小数点サンプルまたはヒストグラムサンプルのいずれかである必要があります。最後の2つのサンプルのうち一方が浮動小数点サンプルで他方がヒストグラムサンプルである v 内の要素は、結果ベクタから省略され、警告レベルの注釈でフラグ付けされます。

idelta はゲージ（浮動小数点とヒストグラムの両方）でのみ使用されるべきです。

`increase()`

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

次の例の式は、過去5分間に測定されたHTTPリクエスト数を、レンジベクタ内の時系列ごとに返します。

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

increase は、ヒストグラムサンプルに対して、各コンポーネント（観測値の合計とカウント、バケット）が v 内の最初と最後のネイティブヒストグラムの対応するコンポーネント間の増加である新しいヒストグラムを計算することで動作します。ただし、レンジ内で浮動小数点サンプルとヒストグラムサンプルの両方を含む v 内の各要素は、結果ベクタから省略され、警告レベルの注釈でフラグ付けされます。

increase はカウンター（浮動小数点とヒストグラムの両方）でのみ使用されるべきです。これは rate(v) を指定された時間範囲ウィンドウの秒数で乗算したシンタックスシュガーであり、主に人間が読みやすくするために使用されるべきです。記録ルールでは rate を使用して、増加が1秒あたりのベースで一貫して追跡されるようにします。

`info()`

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

info(v instant-vector, [data-label-selector instant-vector]) は、v の各時系列に対して、一致する *識別* ラベル（これについては後述）を持つすべての情報系列を見つけ、それらの *データ*（つまり、非識別）ラベルの結合を時系列に追加します。2番目の引数 data-label-selector はオプションです。これは実際のインスタントベクタではありませんが、その構文のサブセットを使用します。波括弧（{ ... }）で始まり終わる必要があり、ラベルマッチャーのみを含めることができます。ラベルマッチャーは、考慮する情報系列と、v に追加するデータラベルを制約するために使用されます。

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

データラベルを追加する従来のアプローチは、「結合クエリ」と呼ばれることもあり、次の例で示されています。

  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]) です。しかし、情報メトリックからデータラベルを追加するには、ユーザーは、どの情報メトリックを使用するか（target_info）、識別ラベルが何か（on (job, instance)）、どのデータラベルを追加するか（group_left (k8s_cluster_name)）を指定するために、複雑で（あまり自明ではない）構文を使用する必要があります。

このクエリは冗長で記述が難しいだけでなく、「アイデンティティクライシス」に陥る可能性もあります。target_info のデータラベルのいずれかが変更された場合、Prometheus はそれをシリーズの変更と見なします（上記で述べたように、Prometheus には非識別ラベルのネイティブな概念がないためです）。古い target_info シリーズが適切に陳腐化としてマークされない場合（特定の取り込みパスで発生する可能性があります）、上記のクエリは最大 5 分間（ルックバックデルタ）失敗します。これは、target_info の古いバージョンと新しいバージョンの両方で競合する一致が見つかるためです。

info 関数は、この競合を新しいシリーズを優先して解決するだけでなく、利用可能な情報シリーズとその識別ラベルを認識しているため、構文も簡素化します。info 関数を使用すると、この例のクエリは次のようになります。

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

すべてのデータラベルを追加する一般的なケースは、info 関数の2番目の引数を完全に省略することで実現でき、例をさらに簡素化できます。

info(rate(http_server_request_duration_seconds_count[2m]))

通常、info はすべての一致する情報シリーズを自動的に見つけますが、__name__ ラベルマッチャー（例: {__name__="target_info"}）を提供することで、それらを制限できます。

制限事項

現在のイテレーションでは、info はデフォルトで target_info という名前の情報シリーズのみを考慮します。また、識別情報シリーズラベルは instance と job であると仮定しています。ただし、info は __name__ ラベルマッチャーを介して他の情報シリーズ名をサポートしています。例えば、target_info と build_info の両方を考慮するように明示的に指定するには、次のようにします: {__name__=~"(target|build)_info"}。ただし、識別ラベルは常に instance と job でなければなりません。

これらの制限は、info 関数の目的を部分的に損なっています。現在の段階では、これはこのアプローチが実際にどの程度有用であるかを見極めるための実験です。info 関数の最終バージョンは、実際にはすべての一致する情報シリーズを適切な識別ラベルとともに考慮するでしょう。

`irate()`

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

irate はカウンタ（浮動小数点とヒストグラムの両方）のみに使用すべきです。

次の例の式は、レンジベクトル内の時系列ごとに、過去5分間の最新の2つのデータポイントについて、HTTPリクエストの1秒あたりのレートを返します。

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

irate は、変動が激しく高速に変化するカウンターをグラフ化する場合にのみ使用すべきです。アラートや低速に変化するカウンターには rate を使用してください。レートのわずかな変化によって FOR 句がリセットされる可能性があり、稀なスパイクだけで構成されるグラフは読みにくいためです。

irate() と aggregation operator（例: 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 は、浮動小数点サンプルとヒストグラムサンプルに対して同じように動作します。

この例では、各時系列に foo ラベルが値 a,b,c とともに付加されたベクトルが返されます。

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) は、ラベル src_label の値に対して正規表現 regex を照合します。一致した場合、返される時系列のラベル dst_label の値は、入力の元のラベルとともに replacement の展開になります。正規表現内のキャプチャグループは $1、$2 などで参照できます。正規表現内の名前付きキャプチャグループは $name（name はキャプチャグループ名）で参照できます。正規表現が一致しない場合、時系列は変更されずに返されます。

label_replace は、浮動小数点サンプルとヒストグラムサンプルに対して同じように動作します。

この例では、ラベル 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 内のすべての浮動小数点サンプルの自然対数を計算します。入力ベクトル内のヒストグラムサンプルは黙って無視されます。特殊なケースは以下の通りです。

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

`log2()`

log2(v instant-vector) は、v 内のすべての浮動小数点サンプルの二進対数を計算します。入力ベクトル内のヒストグラムサンプルは黙って無視されます。特殊なケースは ln のそれらと同等です。

`log10()`

log10(v instant-vector) は、v 内のすべての浮動小数点サンプルの常用対数を計算します。入力ベクトル内のヒストグラムサンプルは黙って無視されます。特殊なケースは ln のそれらと同等です。

`minute()`

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

`month()`

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

`predict_linear()`

predict_linear(v range-vector, t scalar) は、レンジベクトル v に基づいて、単純線形回帰を使用して、現在から t 秒後の時系列の値を予測します。計算を実行するには、レンジベクトルに少なくとも2つの浮動小数点サンプルが必要です。レンジベクトルに +Inf または -Inf が見つかった場合、予測値は NaN になります。

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

`rate()`

rate(v range-vector) は、レンジベクトル内の時系列の1秒あたりの平均増加率を計算します。単調性の破綻（ターゲットの再起動によるカウンタのリセットなど）は自動的に調整されます。また、この計算は時間範囲の端まで外挿され、スクレイピングの欠落やスクレイピングサイクルと範囲の時間期間の不完全な整合を許容します。

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

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

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

rate はカウンタ（浮動小数点とヒストグラムの両方）にのみ使用すべきです。アラートや低速に変化するカウンタのグラフ化に最も適しています。

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

`resets()`

各入力時系列について、resets(v range-vector) は、指定された時間範囲内のカウンタのリセット数をインスタントベクトルとして返します。連続する2つの浮動小数点サンプルの値の減少は、カウンタのリセットとして解釈されます。ネイティブヒストグラムでのリセットはより複雑な方法で検出されます。ゼロバケットを含む任意のバケット、または観測数の減少はカウンタのリセットとみなされますが、以前に値があったバケットの消失、ゼロバケットの幅の減少、または互換性のない解像度減少ではないスキーマの変更もリセットとみなされます。

resets は、カウンタ（浮動小数点とヒストグラムの両方）のみに使用すべきです。

浮動小数点サンプルにヒストグラムサンプルが続く場合、またはその逆の場合、リセットとしてカウントされます。カウンタヒストグラムサンプルにゲージヒストグラムサンプルが続く場合、またはその逆の場合もリセットとしてカウントされます（ただし、そもそも resets はゲージに使用すべきではないことに注意してください。上記を参照）。

`round()`

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

`scalar()`

浮動小数点サンプルを含む1つの要素のみを含む入力ベクトルが与えられた場合、scalar(v instant-vector) はその浮動小数点サンプルのサンプル値をスカラーとして返します。入力ベクトルが浮動小数点サンプルを含む要素を厳密に1つ持たない場合、scalar は NaN を返します。入力ベクトル内のヒストグラムサンプルは黙って無視されます。

`sgn()`

sgn(v instant-vector) は、すべての浮動小数点サンプル値がその符号に変換されたベクトルを返します。符号は次のように定義されます。v が正の場合 1、v が負の場合 -1、v がゼロの場合 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 内のすべての浮動小数点サンプルの平方根を計算します。入力ベクトル内のヒストグラムサンプルは黙って無視されます。

`time()`

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

`timestamp()`

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

`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): 指定された間隔内の最後のサンプルのタイムスタンプ。

指定された間隔内のすべての値は、値が間隔全体にわたって等間隔で配置されていなくても、集計において同じ重みを持つことに注意してください。

これらの関数はヒストグラムに対して次のように動作します。

count_over_time、last_over_time、および present_over_time() は、浮動小数点サンプルとヒストグラムサンプルに対して同じように動作します。
avg_over_time() と sum_over_time() は、それぞれの集約演算子に対応する方法でヒストグラムサンプルに作用します。ある系列が範囲内に浮動小数点サンプルとヒストグラムサンプルの両方を含む場合、対応する結果は出力ベクトルから完全に削除されます。このような削除は警告レベルのアノテーションでフラグが付けられます。
その他すべての関数は、ヒストグラムサンプルを次のように無視します。ヒストグラムサンプルのみを含む入力範囲は、出力から黙って削除されます。ヒストグラムサンプルと浮動小数点サンプルが混在する範囲の場合、浮動小数点サンプルのみが処理され、ヒストグラムサンプルの省略は情報レベルのアノテーションでフラグが付けられます。

三角関数

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

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(): 円周率を返します。
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()

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