Prometheus on() vs ignoring(): ベクトルマッチングの二つの顔 🎭

10月 3, 2026

—

こんにちは！今日は、Prometheusクエリ言語（PromQL）において非常に重要でありながら、混同しやすい2つのキーワード、on()とignoring()について詳しく見ていきましょう。これらは、ベクトル間の演算を実行する際に、どのラベルを基準にマッチングするかを決定する役割を果たします。正確なクエリを作成するためには、これら2つの違いを明確に理解することが不可欠です！

🎯 on(): 「このラベルだけを見てマッチングして！」

on()は、指定したラベルリストが正確に一致する時系列データ同士で演算を実行するよう指示するキーワードです。on()に明示されていない他のすべてのラベルは、マッチングプロセスで完全に無視されます。

on()の動作方法

明示的な指定: マッチングに使用するラベルを直接、明確に指定します。
ホワイトリスト方式: 「このリストにあるラベルだけを許可し、残りは気にしないで」という方式です。

例の状況 📝

次のような2つのメトリックがあると仮定してみましょう。

http_requests_total{method=”GET”, path=”/api/users”, instance=”app-1″}
http_requests_in_progress{method=”GET”, path=”/api/users”, instance=”app-1″}

ここで、私たちはmethodとpathを基準に進行中のリクエストの割合を計算したいと考えています。instanceラベルは考慮したくありません。このような場合にon()を使用します。

http_requests_in_progress
  / on(method, path)
http_requests_total

このクエリは、methodとpathのラベル値が正確に一致するデータ同士で除算演算を実行します。instanceラベルは異なっていても無視されるため、私たちが望む結果を得ることができます。

🙈 ignoring(): 「このラベルだけを除外してマッチングして！」

ignoring()はon()とは正反対の概念です。指定したラベルリストを除外した残りのすべてのラベルが一致する時系列データ同士で演算を実行するよう指示します。

ignoring()の動作方法

例外指定: マッチングで無視するラベルを直接指定します。
ブラックリスト方式: 「このリストにあるラベルは無視し、残りのラベルはすべて一致しなければならない」という方式です。

例の状況 📝

上記と同じ状況でignoring()を使ってみましょう。instanceラベルだけを無視し、残り（method、path）はすべて一致させる必要があります。

http_requests_in_progress
  / ignoring(instance)
http_requests_total

このクエリは、instanceラベルを除外した残りのすべてのラベル（method、path）が一致するデータを見つけて演算を実行します。結果として、on(method, path)を使用したのと同じ結果が得られます。

🤔 on() vs ignoring()、いつ何を使うべきか？


区分	on()	ignoring()
概念	明示されたラベルのみマッチング (ホワイトリスト)	明示されたラベルのみ無視してマッチング (ブラックリスト)
長所	クエリの意図が明確で簡潔	新しいラベルが追加されてもクエリ修正が少なくて済む場合がある
推奨状況	少数の特定のラベルを基準にグループ化または演算する場合	instance、podなど環境によって変わる特定のラベルのみを除外したい場合

通常、instanceやpodのように個々のインスタンスを区別する固有のラベルを無視し、サービスロジックに関連するラベル（method、path、status_codeなど）を基準に演算することが多いです。このような場合には、ignoring(instance, pod)のように使用する方がより柔軟で便利です。

逆に、多数のラベルの中からわずか2、3の特定のラベル（job、handler）だけでグループ化したい場合は、on(job, handler)の方がはるかに直感的で明確な選択となるでしょう。

結論 ✨

on()とignoring()は、PromQLでベクトルマッチングを制御する強力なツールです。

on()は含めるラベルを明示します。🎯
ignoring()は除外するラベルを明示します。🙈

これら2つのキーワードの違いを正確に理解し、状況に応じたキーワードを選択することで、より正確で柔軟なモニタリングクエリを作成してみてください！