Prometheus のリラベリング入門:ターゲットとサンプルを選ぶ
Prometheus のリラベリングでスクレイプ対象を選び、ラベルを調整する方法を解説します。Kubernetes のアノテーション、シャード分割、保存前のサンプル除外も扱います。
Kubernetes の Pod が /metrics を公開しています。Prometheus から到達できても、明示的に許可した Pod だけを収集し、あるメトリクスは保存から外したいことがあります。前者は HTTP リクエストを送る前、後者は応答を受け取った後の判断です。
Prometheus のリラベリングは、処理段階ごとにラベルを書き換えたり、対象を除外したりする仕組みです。 サービスディスカバリー、ローカル保存、転送先のどこから何を除くかを先に決めると、設定箇所を選びやすくなります。
設定の適用段階を選ぶ
| 設定 | 適用タイミング | 変えられること |
|---|---|---|
スクレイプジョブの relabel_configs |
ディスカバリー後、スクレイプ前 | 対象の選別、アクセス先の変更、発見時のメタデータの引き継ぎ |
metric_relabel_configs |
スクレイプ後、取り込み直前 | 取得したサンプルの選別とラベルの変更 |
write_relabel_configs |
外部ラベルの付与後、特定の Remote Write 転送先へ送る前 | ローカルへの取り込みはそのままに、転送対象を調整 |
alert_relabel_configs |
外部ラベルの付与後、Alertmanager への送信前 | アラートの選別やラベルの調整 |
metric_relabel_configs でサンプルを捨てても、HTTP リクエストと応答の解析は行われます。up など Prometheus が自動生成する時系列も、この設定の対象外です。up が 1 でも、探しているメトリクスが保存されたとは限りません。Prometheus の設定リファレンス(英語)
一つのターゲットのラベルを追う
ルールは記述順に適用されます。Kubernetes の Pod を発見するジョブでは、__address__ がアクセス先、__scheme__ と __metrics_path__ がプロトコルとパスです。__meta_kubernetes_namespace などはディスカバリーから渡されます。クエリで使う値は通常のラベルにコピーしておきます。ターゲットのリラベリング後、ディスカバリーのメタデータは除去されます。アクセス先などの内部フィールド __* は公開ターゲットラベルに含まれません。__tmp は途中結果の保持に使えます。instance を設定しなければ、最終的な __address__ が使われます。サンプル側では __name__ からメトリクス名を参照できます。
relabel_configs:
- source_labels: [__meta_kubernetes_namespace]
separator: ';'
regex: '(production|staging)'
replacement: '$1'
target_label: env
action: replace
この replace は、名前空間が production または staging と完全に一致したときだけ env に値を書き込みます。ほかのターゲットはそのままです。正規表現は RE2 で、入力の先頭から末尾までを照合します。存在しないラベルの値は空文字列で、複数の値は既定でセミコロンでつなぎます。既定のアクションは replace、正規表現は (.*)、置換値は $1 です。リラベリングの仕様(英語)
条件に合わせてアクションを選ぶ
| アクション | 動作 |
|---|---|
keep / drop |
連結したラベル値を正規表現と照合し、keep は不一致、drop は一致を除外する。 |
replace |
正規表現に一致した場合に置換結果を対象ラベルへ書く。 |
labelkeep / labeldrop |
ラベル名を照合し、一致した名前だけを残す、または一致した名前を削除する。 |
labelmap |
一致した名前のラベル値を別名にコピーする。コピー元はその段階では残る。 |
hashmod |
連結した値のハッシュを正の数で割り、その余りを対象ラベルへ書く。 |
keepequal / dropequal |
source_labels の連結値を target_label の現在値と比較し、完全一致で残す、または除外する。 |
lowercase / uppercase |
連結した値を小文字または大文字に変換し、対象ラベルへ書く。 |
production だけをスクレイプするなら、次のルールを使います。このルールでラベル値は変わりません。
- source_labels: [__meta_kubernetes_namespace]
regex: 'production'
action: keep
Pod 名をクエリで使うなら、pod に保存します。同じ Pod に複数のメトリクス用エンドポイントがあるときに instance を Pod 名へ統一すると、区別できなくなることがあります。
- source_labels: [__meta_kubernetes_pod_name]
target_label: pod
regex: '(.*)'
replacement: '$1'
action: replace
Kubernetes のラベルは、必要な名前に絞ってコピーします。
- regex: '__meta_kubernetes_pod_label_(app|team)'
replacement: '$1'
action: labelmap
これで発見時の内部ラベルが除去された後も、app と team を使えます。広い正規表現は、変化の多いビルド識別子まで取り込んだり、既存のラベルを上書きしたりします。次のルールを使う場合は、削除後もメトリクス名とラベルの組み合わせで別々の時系列を識別できるか確認します。
- regex: 'build_sha|request_id'
action: labeldrop
スクレイプ対象を二つのシャードに分ける
同じターゲット候補を法 2 で分ける場合、一方は余り 0、もう一方は 1 を残します。各ターゲットはどちらか一方に入ります。件数が均等になるとは限りません。
- source_labels: [__address__]
modulus: 2
target_label: __tmp_hash
action: hashmod
- source_labels: [__tmp_hash]
regex: '0'
action: keep
両シャードで前段のルールをそろえ、同じキーをハッシュします。同じ余りを選ぶレプリカは同じ対象を収集します。高可用性のために重ねる場合と、負荷分散のために分ける場合とで設定を区別します。
アノテーションで対象とポートを指定する
Kubernetes の Pod ディスカバリーを使うジョブに、次のルールを入れます。最初のルールは許可された Pod を残します。次のルールはポートの値が数字で、発見したアドレスがホスト名、IPv4、または角括弧付き IPv6 の想定形式の場合にポートを置き換えます。一致しなければ元のアドレスが残ります。
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
regex: 'true'
action: keep
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port, __address__]
regex: '([0-9]+);(\[[^]]+\]|[^:]+)(:[0-9]+)?'
replacement: '${2}:${1}'
target_label: __address__
Guance にも指標を送る場合は、DataKit の KubernetesPrometheus コレクター(英語)を別に設定します。アノテーションによる検出を使うなら有効化し、指定方法や対象の選択条件を確認します。
サンプルを除外し、結果を確かめる
保存から外してよいメトリクスを特定し、その名前を指定します。この例は http_request_debug_total のサンプルを除外します。
metric_relabel_configs:
- source_labels: [__name__]
regex: 'http_request_debug_total'
action: drop
再読み込みの前に構成を検査します。二つ目のコマンドは指定したジョブのディスカバリーを実行するため、発見元へアクセスできる環境で、実際のジョブ名を指定します。promtool リファレンス(英語)
promtool check config prometheus.yml
promtool check service-discovery prometheus.yml kubernetes-pods
Prometheus の Service Discovery と Targets を比較します。対象があり up が 1 なら、残す指標と除外する指標をそれぞれ検索します。設定は SIGHUP、またはライフサイクル API を有効にしたサーバーの HTTP POST /-/reload で再読み込みできます。
よくある質問
正規表現が一致しないのはなぜですか? 連結後の実際の値を確認します。部分一致が必要なら、該当箇所の前後に明示的に .* を置きます。
$1 で値が出ないのはなぜですか? 正規表現に対応するキャプチャグループがあるか確認します。直後に文字を続ける場合は ${1}、ドル記号そのものを入れる場合は $$ を使います。
保存済みのデータも変わりますか? 保存済みの時系列のラベルは変わりません。変更後に新しいラベルの組み合わせで時系列が作られ、変更前後をまたぐクエリには両方が現れることがあります。
関連記事 · Helm で Kubernetes に Prometheus を導入する · Prometheus 監視ガイド
