Prometheus logo

Prometheus

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

Ctrl + K

GitHub Logo

オペレーター

PromQL は、単項、二項、集計演算子をサポートします。

単項演算子

PromQL の単項演算子は `-` (単項マイナス) のみです。これは、スカラーまたはインスタントベクターに適用できます。前者では、符号を反転させたスカラーを返します。後者では、各要素の符号を反転させたインスタントベクターを返します。ヒストグラムサンプルの符号は、すべてのバケットの数、観測の数、および観測の合計の符号を反転させることで反転します。結果のヒストグラムサンプルは常にゲージヒストグラムと見なされます。

二項演算子

二項演算子は、基本的な論理演算と算術演算をカバーします。2 つのインスタントベクター間の演算では、マッチング動作を変更できます。

算術二項演算子

PromQL には次の算術二項演算子があります。

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

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

2 つのスカラー間では、動作は単純です。演算子を両方のスカラーオペランドに適用した結果である別のスカラーになります。

インスタントベクターとスカラー間では、演算子はベクター内の各データサンプルの値に適用されます。

データサンプルが浮動小数点数の場合、その浮動小数点数とスカラーの間で演算が実行されます。たとえば、浮動小数点数サンプルのインスタントベクターに 2 を掛けると、元のベクターの各サンプル値に 2 を掛けた浮動小数点数サンプルの別のベクターの結果になります。

ヒストグラムサンプルであるベクター要素の場合、動作は次のようになります。

  • *の場合、すべてのバケットの数、観測の数、および観測の合計がスカラーで乗算されます。スカラーが負の場合、結果のヒストグラムはゲージヒストグラムと見なされます。それ以外の場合、入力ヒストグラムサンプルのカウンター対ゲージのフレイバーが維持されます。

  • /の場合、ヒストグラムサンプルは左辺 (LHS) に、スカラーは右辺 (RHS) にある必要があります。すべてのバケットの数、観測の数、および観測の合計がスカラーで除算されます。ゼロ除算の結果は、通常のバケットがないヒストグラムになり、ゼロバケットの数、観測の数、および観測の合計は、入力ヒストグラムの値に応じてすべて +Inf、-Inf、または NaN に設定されます (それぞれ、正、負、またはゼロ/NaN)。スカラーが負の場合、結果のヒストグラムはゲージヒストグラムと見なされます。それ以外の場合、入力ヒストグラムサンプルのカウンター対ゲージのフレイバーが維持されます。

  • スカラーが LHS、ヒストグラムサンプルが RHS にある / の場合、およびスカラーとヒストグラムサンプルの任意の組み合わせの他のすべての算術二項演算子の場合と同様に、結果はなく、対応する要素は結果ベクターから削除されます。このような削除は、情報レベルのアノテーションでフラグ付けされます。

2 つのインスタントベクター間では、算術二項演算子が LHS ベクターの各エントリと、RHS ベクターのマッチングエントリに適用されます。結果は、グループ化ラベルが出力ラベルセットになるように、結果ベクターに伝播されます。マッチングする右側ベクターのエントリが見つからないエントリは、結果に含まれません。

2 つの浮動小数点数サンプルが一致した場合、算術演算子は 2 つの入力値に適用されます。

浮動小数点数サンプルがヒストグラムサンプルと一致した場合、動作はスカラーとヒストグラムサンプルの場合と同様のロジックに従います (上記参照)。つまり、* と / (後者はヒストグラムサンプルが LHS にある場合) は有効な操作ですが、それ以外はすべて、対応する要素が結果ベクターから削除されます。

2 つのヒストグラムサンプルが一致した場合、+ と - のみ有効な操作であり、それぞれすべてのマッチングするバケットの数、観測の数、および観測の合計を加算または減算します。他のすべての操作は、対応する要素が出力ベクターから削除され、情報レベルのアノテーションでフラグ付けされます。+ と `-` の操作は、通常、ゲージヒストグラムにのみ適用されるべきですが、PromQL はカウンターヒストグラムでも、問題のあるカウンターリセットを回避するために特別な注意が必要な特定のユースケースをカバーするために許可します。(カウンターリセットの特定の非互換性は PromQL によって検出され、警告レベルのアノテーションでフラグ付けされます。) 2 つのカウンターヒストグラムを加算すると、カウンターヒストグラムになります。オペランドのその他のすべての組み合わせおよびすべての減算は、ゲージヒストグラムになります。

ベクターを含む任意の算術二項演算では、メトリック名は削除されます。これは、__name__ が on で明示的に指定されている場合でも発生します (詳細については、https://github.com/prometheus/prometheus/issues/16631を参照)。

三角二項演算子

Prometheus には、ラジアンで動作する次の三角二項演算子があります。

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

比較二項演算子

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

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

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

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

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

2 つのインスタントベクター間では、これらの演算子はデフォルトでフィルタリングとして動作し、マッチングするエントリに適用されます。式が true でない、または式の反対側でマッチが見つからないベクター要素は結果からドロップされ、その他はグループ化ラベルが出力ラベルセットになる結果ベクターに伝播されます。

2 つの浮動小数点数サンプル間のマッチングは通常どおり機能します。

浮動小数点数サンプルとヒストグラムサンプルの間のマッチングは無効であり、対応する要素は結果ベクターから削除され、情報レベルのアノテーションでフラグ付けされます。

2 つのヒストグラムサンプルの間では、== と != は期待どおりに機能しますが、他のすべての比較二項演算子は無効になります。

ベクターを含む任意の比較二項演算では、bool 修飾子を指定すると、動作は次のように変更されます。

  • 式の反対側でマッチが見つかるが、式が false であるベクター要素は、代わりに値 0 を持ち、マッチが見つかり、式が true であるベクター要素は値 1 を持ちます。(マッチがない場合や、ヒストグラムサンプルを含む無効な操作は、依然として値 0 ではなく、結果がないことに注意してください。)
  • メトリック名は削除されます。

bool 修飾子が指定されていない場合、左側のメトリック名が保持されます。ただし、例外があります。

  • on が使用されている場合、メトリック名は削除されます。
  • group_right が使用されている場合、衝突を回避するために、右側のメトリック名が保持されます。

論理/セット二項演算子

これらの論理/セット二項演算子は、インスタントベクター間でのみ定義されます。

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

vector1 and vector2 は、vector2 に完全に一致するラベルセットを持つ要素が vector1 に存在する要素で構成されるベクターを返します。その他の要素はドロップされます。メトリック名と値は左辺のベクターから引き継がれます。

vector1 or vector2 は、vector1 のすべての元の要素 (ラベルセット + 値) と、さらに vector1 にマッチするラベルセットを持たない vector2 のすべての要素を含むベクターを返します。

vector1 unless vector2 は、vector2 に完全に一致するラベルセットを持つ要素が vector1 に存在しない要素で構成されるベクターを返します。両方のベクターのマッチングする要素はすべてドロップされます。

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

ベクターマッチング

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

ベクターマッチングキーワード

これらのベクターマッチングキーワードにより、異なるラベルセットを持つシリーズ間でマッチングが可能になります。

  • on
  • ignoring

マッチングキーワードに提供されるラベルリストは、シリーズをどのように組み合わせるかを決定します。例は、1 対 1 のベクターマッチと多対 1 および 1 対多のベクターマッチにあります。

グループ修飾子

これらのグループ修飾子は、多対 1/1 対多のベクターマッチングを有効にします。

  • group_left
  • group_right

グループ修飾子に提供されるラベルリストには、結果メトリックに含める「1」側のラベルを含めることができます。

多対 1 および 1 対多のマッチングは、慎重に検討すべき高度なユースケースです。多くの場合、ignoring(<labels>) を適切に使用すると、望ましい結果が得られます。

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

1 対 1 のベクターマッチ

1 対 1 は、操作の各辺から一意のペアのエントリを見つけます。デフォルトでは、これは 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

多対 1 および 1 対多のベクターマッチ

多対 1 および 1 対多のマッチングは、各ベクター要素が「1」側で複数の要素「多」側とマッチできる場合を指します。これは、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>

group 修飾子と共に提供されるラベルリストには、「1」側の追加ラベルが含まれ、結果メトリックに含められます。on の場合、ラベルは 1 つのリストにのみ表示できます。結果ベクターの各時系列は一意に識別可能である必要があります。

クエリ例

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(v) (次元全体の合計を計算)

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

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

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

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

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

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

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

  • group(v) (結果ベクターのすべての値は 1)

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

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

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

  • stdvar(v) (次元全体の母分散を計算)

  • quantile(φ, v) (次元全体の φ 量化子 (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 句にリストされていないラベルをドロップします。たとえベクターのすべての要素間でラベル値が同じであってもです。

詳細な説明

sum

sum(v) は、2 つの値間の + 二項演算子と同様に、v のサンプル値を合計します。

単一の結果ベクター要素に集計されるすべてのサンプル値は、浮動小数点数サンプルまたはヒストグラムサンプルのいずれかである必要があります。両方の混在の集計は無効であり、対応するベクター要素が結果ベクターから削除され、警告レベルのアノテーションでフラグ付けされます。

例

メトリック memory_consumption_bytes に、application、instance、および group ラベルでファンアウトする時系列があった場合、アプリケーションおよびグループごとの総メモリ使用量をすべてのインスタンスにわたって計算できます。

sum without (instance) (memory_consumption_bytes)

これは以下と同等です。

sum by (application, group) (memory_consumption_bytes)

すべてのアプリケーションの総メモリ使用量にのみ関心がある場合は、次のように簡単に記述できます。

sum(memory_consumption_bytes)

avg

avg(v) は、/ 二項演算子と同様に、v の合計を集計されたサンプルの数で割ります。

単一の結果ベクター要素に集計されるすべてのサンプル値は、浮動小数点数サンプルまたはヒストグラムサンプルのいずれかである必要があります。両方の混在の集計は無効であり、対応するベクター要素が結果ベクターから削除され、警告レベルのアノテーションでフラグ付けされます。

min と max

min(v) と max(v) は、それぞれ v の最小値または最大値を返します。

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

topk と bottomk

topk(k, v) および bottomk(k, v) は、他の集計演算子とは異なり、元のラベルを含む k 個の値のサブセットを結果ベクターに返します。

by と without は、入力ベクターをバケット化するためにのみ使用されます。

min および max と同様に、これらは浮動小数点数サンプルのみを操作し、NaN 値をそれぞれトップまたはボトムから最も遠いと見なします。入力ベクターのヒストグラムサンプルは無視され、情報レベルのアノテーションでフラグ付けされます。

インスタントクエリで使用する場合、topk および bottomk は、それぞれ降順または昇順で値によってソートされたシリーズを返します。by または without と一緒に使用する場合、各バケット内のシリーズは値でソートされ、同じバケット内のシリーズは連続して返されますが、バケットが特定の順序で返される保証はありません。

範囲クエリにはソートは適用されません。

例

すべてのインスタンスにわたってメモリ使用量が最も多い 5 つのインスタンスを取得するには、次のように記述できます。

topk(5, memory_consumption_bytes)

limitk と limit_ratio

limitk(k, v) は、元のラベルを含む k 個の入力サンプルのサブセットを結果ベクターに返します。

サブセットは、決定的擬似ランダムな方法で選択されます。これはサンプルタイプに関係なく発生します。したがって、浮動小数点数サンプルとヒストグラムサンプルの両方で機能します。

例

10 個の時系列をサンプリングするには、次のように記述できます。

limitk(10, memory_consumption_bytes)

limit_ratio

limit_ratio(r, v) は、元のラベルを含む入力サンプルのサブセットを結果ベクターに返します。

サブセットは、決定的擬似ランダムな方法で選択されます。これはサンプルタイプに関係なく発生します。したがって、浮動小数点数サンプルとヒストグラムサンプルの両方で機能します。

r は +1 から -1 の間で指定できます。r の絶対値は選択比率として使用されますが、選択順序は負の r では反転し、補集合を選択するために使用できます。たとえば、limit_ratio(0.1, ...) は、入力サンプルの約 10% の決定的セットを返しますが、limit_ratio(-0.9, ...) は、limit_ratio(0.1, ...) によって返されない残りの約 90% の入力サンプルを正確に返します。

group

group(v) は、そのタイムスタンプで値を含む各グループに対して 1 を返します。

値は浮動小数点数サンプルまたはヒストグラムサンプルである場合があります。

count

count(v) は、そのタイムスタンプにおける値の数を返します。タイムスタンプに値が存在しない場合は、何も返しません。

値は浮動小数点数サンプルまたはヒストグラムサンプルである場合があります。

count_values

count_values(l, v) は、v 内のユニークなサンプル値ごとに 1 つの時系列を出力します。各時系列には l で与えられる追加のラベルがあり、ラベルの値はそのユニークなサンプル値になります。各時系列の値は、そのサンプル値が存在した回数です。

count_values は、float サンプルとヒストグラムサンプルの両方で機能します。後者の場合、ヒストグラムサンプル値のコンパクトな文字列表現がラベル値として使用されます。

例

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

count_values("version", build_version)

stddev

stddev(v) は v の標準偏差を返します。

stddev は、IEEE 754 浮動小数点演算に従って、float サンプルでのみ機能します。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルの注釈でフラグが付けられます。

stdvar

stdvar(v) は v の標準偏差を返します。

stdvar は、IEEE 754 浮動小数点演算に従って、float サンプルでのみ機能します。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルの注釈でフラグが付けられます。

quantile

quantile(φ, v) は、φ-分位数、つまり集計された N 個のメトリック値の中で φ*N 番目の順位を持つ値を計算します。

quantile は、float サンプルでのみ機能します。入力ベクトル内のヒストグラムサンプルは無視され、情報レベルの注釈でフラグが付けられます。

NaN は、最も小さい値として扱われます。

たとえば、quantile(0.5, ...) は中央値を計算し、quantile(0.95, ...) は 95 パーセンタイルを計算します。

特殊なケース

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

二項演算子の優先順位

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

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

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

このページの内容