Prometheus logo

Prometheus

ドキュメントダウンロードコミュニティサポート＆トレーニングブログ

Ctrl + K

GitHub Logo

演算子

二項演算子

Prometheusのクエリ言語は、基本的な論理演算子と算術演算子をサポートしています。2つの即時ベクトル間の操作では、マッチング動作を変更できます。

算術二項演算子

Prometheusには以下の二項算術演算子があります。

  • + (加算)
  • - (減算)
  • * (乗算)
  • / (除算)
  • % (剰余)
  • ^ (べき乗)

二項算術演算子は、スカラー/スカラー、ベクトル/スカラー、およびベクトル/ベクトル値のペア間で定義されます。これらは、NaN、+Inf、-Infなどの特殊値の処理を含め、通常のIEEE 754浮動小数点演算に従います。

2つのスカラー間では、動作は明らかです。演算子が両方のスカラーオペランドに適用された結果である別のスカラーに評価されます。

即時ベクトルとスカラー間では、演算子はベクトルの各データサンプルの値に適用されます。データサンプルが浮動小数点数の場合、データサンプルに対して実行される演算は再び明らかです。たとえば、浮動小数点数サンプルの即時ベクトルが2で乗算された場合、結果は、元のベクトルの各サンプル値が2で乗算された浮動小数点数サンプルの別のベクトルになります。ヒストグラムサンプルであるベクトル要素の場合、動作は次のとおりです。*の場合、すべてのバケットの人口と観測のカウントおよび合計がスカラーで乗算されます。/の場合、ヒストグラムサンプルは左側（LHS）にあり、次にスカラーが右側（RHS）に続く必要があります。すべてのバケットの人口と観測のカウントおよび合計は、スカラーで除算されます。ゼロによる除算は、通常のバケットがなく、ゼロバケットの人口と観測のカウントおよび合計がすべて+Inf、-Inf、またはNaNに設定されたヒストグラムになります（入力ヒストグラムの値を基準に、それぞれ正、負、またはゼロ/NaN）。LHSにスカラー、RHSにヒストグラムサンプルがある/の場合、および同様にスカラーとヒストグラムサンプルの任意の組み合わせにおける他のすべての算術二項演算子の場合、結果はなく、対応する要素は結果ベクトルから削除されます。このような削除は、情報レベルのアノテーションによってフラグされます。

2つの即時ベクトル間では、二項算術演算子はLHSベクトルの各エントリとそのRHSベクトル内のマッチング要素に適用されます。結果は、グループ化ラベルが出力ラベルセットになるように結果ベクトルに伝播されます。右辺ベクトルにマッチングするエントリが見つからないエントリは、結果の一部にはなりません。2つの浮動小数点数サンプルがマッチングされた場合、動作は明らかです。浮動小数点数サンプルがヒストグラムサンプルとマッチングされた場合、動作はスカラーとヒストグラムサンプルの間（上記参照）と同じロジックに従います。つまり、*と/（後者はヒストグラムサンプルがLHSにある場合）は有効な操作ですが、他のすべての操作は対応する要素を結果ベクトルから削除します。2つのヒストグラムサンプルがマッチングされた場合、+と-のみが有効な操作であり、それぞれすべてのマッチングするバケットの人口と観測のカウントおよび合計を加算または減算します。他のすべての操作は、情報レベルのアノテーションによってフラグされ、出力ベクトルから対応する要素を削除します。

ベクトルを含む任意の算術二項演算では、メトリック名は削除されます。

三角関数二項演算子

Prometheusには、ラジアンで機能する以下の三角関数二項演算子があります。

三角関数演算子を使用すると、通常の関数では利用できないベクトルマッチングを使用して、2つのベクトルに対して三角関数を実行できます。これらは算術演算子と同じように動作します。これらは浮動小数点数サンプルのみで動作します。ヒストグラムサンプルを含む操作は、情報レベルのアノテーションによってフラグされ、対応するベクトル要素を出力ベクトルから削除します。

比較二項演算子

Prometheusには以下の二項比較演算子があります。

  • == (等しい)
  • != (等しくない)
  • > (より大きい)
  • < (より小さい)
  • >= (以上)
  • <= (以下)

比較演算子は、スカラー/スカラー、ベクトル/スカラー、およびベクトル/ベクトル値のペア間で定義されます。デフォルトではフィルタリングを行います。演算子の後にboolを指定することで、動作を変更でき、フィルタリングする代わりに値として0または1を返します。

2つのスカラー間では、bool修飾子を指定する必要があり、これらの演算子は比較結果に応じて0（false）または1（true）の別のスカラーを返します。

即時ベクトルとスカラー間では、これらの演算子はベクトルの各データサンプルの値に適用され、比較結果がfalseであるベクトル要素は結果ベクトルから削除されます。これらの操作は、ベクトルの浮動小数点数サンプルのみで機能します。ヒストグラムサンプルについては、対応する要素が情報レベルのアノテーションによってフラグされ、結果ベクトルから削除されます。

2つの即時ベクトル間では、これらの演算子はデフォルトでフィルターとして動作し、マッチングするエントリに適用されます。式が真でないか、式の反対側でマッチングする要素が見つからないベクトル要素は結果から削除され、他の要素はグループ化ラベルが出力ラベルセットになるように結果ベクトルに伝播されます。2つの浮動小数点数サンプル間のマッチングは通常どおり機能しますが、浮動小数点数サンプルとヒストグラムサンプル間のマッチングは無効です。対応する要素は情報レベルのアノテーションによってフラグされ、結果ベクトルから削除されます。2つのヒストグラムサンプル間では、==と!=は期待どおりに機能しますが、他のすべての比較二項演算は再び無効です。

ベクトルを含む任意の比較二項演算では、bool修飾子を指定すると、動作が次のように変更されます。削除されるベクトル要素は値0を持ち、保持されるベクトル要素は値1を持ちます。さらに、メトリック名は削除されます。（ヒストグラムサンプルを含む無効な操作は、値0を返す代わりに結果を返しません。）

論理/集合二項演算子

これらの論理/集合二項演算子は、即時ベクトル間でのみ定義されます。

  • and (積集合)
  • or (和集合)
  • unless (補集合)

vector1 and vector2は、vector2に正確に一致するラベルセットを持つ要素があるvector1の要素からなるベクトルを生成します。その他の要素は削除されます。メトリック名と値は左辺のベクトルから引き継がれます。

vector1 or vector2は、vector1のすべての元の要素（ラベルセット + 値）と、vector1に一致するラベルセットを持たないvector2のすべての要素を含むベクトルを生成します。

vector1 unless vector2は、vector2に正確に一致するラベルセットを持つ要素がないvector1の要素からなるベクトルを生成します。両方のベクトルで一致するすべての要素は削除されます。

これらの論理/集合二項演算子はサンプル値と相互作用しないため、浮動小数点数サンプルとヒストグラムサンプルで同じように機能します。

ベクトルマッチング

ベクトル間の操作は、左辺の各エントリに対して右辺のベクトルで一致する要素を見つけようとします。マッチング動作には、一対一と多対一/一対多の2つの基本的なタイプがあります。

ベクトルマッチングキーワード

これらのベクトルマッチングキーワードを使用すると、異なるラベルセットを持つ系列間でマッチングを行うことができます。

  • on
  • ignoring

マッチングキーワードに指定されたラベルリストは、ベクトルの結合方法を決定します。例は、一対一ベクトルマッチングと多対一および一対多ベクトルマッチングで参照できます。

グループ修飾子

これらのグループ修飾子は、多対一/一対多のベクトルマッチングを可能にします。

  • group_left
  • group_right

グループ修飾子には、「one」側のラベルを含むラベルリストを指定でき、それらのラベルは結果メトリックに含まれます。

多対一および一対多のマッチングは高度なユースケースであり、慎重に検討する必要があります。多くの場合、ignoring(<labels>)を適切に使用することで、目的の結果が得られます。

グループ化修飾子は、比較および算術操作にのみ使用できます。and、unless、or操作は、デフォルトですべての可能な右ベクトルエントリと一致します。

一対一ベクトルマッチング

一対一は、操作の各側から一意のペアのエントリを見つけます。デフォルトの場合、それはvector1 <operator> vector2の形式に従う操作です。2つのエントリは、完全に同じラベルセットと対応する値を持つ場合に一致します。ignoringキーワードを使用すると、マッチング時に特定のラベルを無視でき、onキーワードを使用すると、考慮されるラベルのセットを指定されたリストに減らすことができます。

<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

クエリ例

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

これは、過去5分間に測定された各メソッドのステータスコード500のHTTPリクエストの割合を含む結果ベクトルを返します。ignoring(code)がない場合、メトリックが同じラベルセットを共有していないため、マッチングは行われません。メソッドputとdelのエントリはマッチングがなく、結果には表示されません。

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

多対一および一対多ベクトルマッチング

多対一および一対多のマッチングは、「一」側の各ベクトル要素が「多」側の複数の要素と一致するケースを指します。これは、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>

グループ修飾子に指定されたラベルリストには、「一」側の追加のラベルが含まれ、それらは結果メトリックに含まれます。onの場合、ラベルはいずれか一方のリストにのみ表示されます。結果ベクトルの各時系列は一意に識別できる必要があります。

クエリ例

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

この場合、左側のベクトルには、methodラベル値ごとに複数のエントリが含まれています。したがって、group_leftを使用してこれを示します。右側の要素は、左側の同じmethodラベルを持つ複数の要素と一致するようになりました。

{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

集約演算子

Prometheusは、単一の即時ベクトルの要素を集約して、集約された値を持つより少ない要素の新しいベクトルを生成するために使用できる以下の組み込み集約演算子をサポートしています。

  • sum (次元全体で合計を計算)

  • avg (次元全体で算術平均を計算)

  • min (次元全体で最小値を選択)

  • max (次元全体で最大値を選択)

  • bottomk (サンプル値で最小の_k_個の要素)

  • topk (サンプル値で最大の_k_個の要素)

  • limitk (k個の要素をサンプリング、実験的、--enable-feature=promql-experimental-functionsで有効にする必要があります)

  • limit_ratio (要素の擬似ランダム比率rをサンプリング、実験的、--enable-feature=promql-experimental-functionsで有効にする必要があります)

  • group (結果ベクトルのすべての値は1)

  • count (ベクトル内の要素数をカウント)

  • count_values (同じ値を持つ要素数をカウント)

  • stddev (次元全体で母標準偏差を計算)

  • stdvar (次元全体で母標準分散を計算)

  • quantile (次元全体でφ-クォンタイル (0 ≤ φ ≤ 1) を計算)

これらの演算子は、すべてのラベル次元で集約するためにも、withoutまたはby句を含めることで異なる次元を保持するためにも使用できます。これらの句は、式の前または後に使用できます。

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

または

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

label listは、末尾のカンマを含めることができる引用符なしのラベルのリストです。つまり、(label1, label2)と(label1, label2,)の両方が有効な構文です。

withoutはリストされたラベルを結果ベクトルから削除し、他のすべてのラベルは出力に保持されます。byは反対の動作をし、by句にリストされていないラベルを削除します。たとえそれらのラベル値がベクトル内のすべての要素間で同一であってもです。

parameterは、topk、bottomk、limitk、limit_ratio、quantile、およびcount_valuesにのみ必要です。これは、それぞれk、r、φ、または追加ラベルの名前の値として使用されます。

詳細な説明

sumは、2つの値間の+二項演算子と同じ方法でサンプル値を合計します。同様に、avgは、/二項演算子と同じ方法で合計を集約されたサンプルの数で除算します。したがって、単一の結果ベクトル要素に集約されるすべてのサンプル値は、浮動小数点数サンプルまたはヒストグラムサンプルのいずれかである必要があります。両方が混在する集約は無効であり、結果として出力ベクトルから対応するベクトル要素が削除され、警告レベルのアノテーションによってフラグされます。

minとmaxは浮動小数点数サンプルのみで動作し、IEEE 754浮動小数点演算に従います。これにより、特に、すべての集約された値がNaNである場合にのみ、NaNが最小または最大と見なされます。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルのアノテーションによってフラグされます。

topkとbottomkは他のアグリゲータとは異なり、入力サンプルのサブセット（元のラベルを含む）が結果ベクトルに返されます。byとwithoutは、入力ベクトルをバケット化するためにのみ使用されます。minとmaxと同様に、これらは浮動小数点数サンプルのみで動作し、NaN値をそれぞれトップまたはボトムから最も遠い値と見なします。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルのアノテーションによってフラグされます。

即時クエリで使用される場合、topkとbottomkは、それぞれ降順または昇順の値でソートされた系列を返します。byまたはwithoutと一緒に使用される場合、各バケット内の系列は値でソートされ、同じバケット内の系列は連続して返されますが、系列のバケットが特定の順序で返される保証はありません。範囲クエリにはソートは適用されません。

limitkとlimit_ratioも、入力サンプルのサブセット（結果ベクトル内の元のラベルを含む）を返します。サブセットは、決定論的な擬似ランダムな方法で選択されます。limitkはk個のサンプルを選択し、limit_ratioはサンプル比率rを選択します（それぞれparameterで決定されます）。これはサンプルタイプとは無関係に発生します。したがって、浮動小数点数サンプルとヒストグラムサンプルの両方で機能します。rは+1から-1の間であることができます。rの絶対値が選択比率として使用されますが、負のrの場合、選択順序が反転し、補数をS選択するために使用できます。たとえば、limit_ratio(0.1, ...)は入力サンプルの約10%の決定論的セットを返し、limit_ratio(-0.9, ...)はlimit_ratio(0.1, ...)によって返されない入力サンプルの残りの約90%を正確に返します。

groupとcountはサンプル値と相互作用しないため、浮動小数点数サンプルとヒストグラムサンプルで同じように機能します。

count_valuesは、一意のサンプル値ごとに1つの時系列を出力します。各系列には追加のラベルがあります。そのラベルの名前は集約パラメータで与えられ、ラベル値は一意のサンプル値です。各時系列の値は、そのサンプル値が存在した回数です。count_valuesは浮動小数点数サンプルとヒストグラムサンプルの両方で機能します。後者の場合、ヒストグラムサンプル値のコンパクトな文字列表現がラベル値として使用されます。

stddevとstdvarは浮動小数点数サンプルのみで動作し、IEEE 754浮動小数点演算に従います。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルのアノテーションによってフラグされます。

quantileはφ-クォンタイルを計算します。これは、集約された次元のN個のメトリック値の中で、φ*N番目のランクに位置する値です。φは集約パラメータとして提供されます。たとえば、quantile(0.5, ...)は中央値を計算し、quantile(0.95, ...)は95パーセンタイルを計算します。φ = NaNの場合、NaNが返されます。φ < 0の場合、-Infが返されます。φ > 1の場合、+Infが返されます。

例

メトリックhttp_requests_totalがapplication、instance、およびgroupラベルでファンアウトする時系列を持っていた場合、すべてのインスタンスでアプリケーションとグループごとのHTTPリクエストの総数を計算するには、以下のようにします。

sum without (instance) (http_requests_total)

これは以下と同等です。

 sum by (application, group) (http_requests_total)

すべてのアプリケーションで確認されたHTTPリクエストの合計に関心がある場合は、単に次のように記述できます。

sum(http_requests_total)

各ビルドバージョンで実行されているバイナリの数をカウントするには、次のように記述できます。

count_values("version", build_version)

すべてのインスタンスで5つの最大のHTTPリクエスト数を取得するには、次のように記述できます。

topk(5, http_requests_total)

たとえば、ラベルとその値を調べるために10の時系列をサンプリングするには、次のように記述できます。

limitk(10, http_requests_total)

二項演算子の優先順位

以下のリストは、Prometheusにおける二項演算子の優先順位を高いものから低いものへと示しています。

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

同じ優先順位レベルの演算子は左結合です。たとえば、2 * 3 % 2は(2 * 3) % 2と同等です。ただし、^は右結合なので、2 ^ 3 ^ 2は2 ^ (3 ^ 2)と同等です。

このページの内容