Elasticsearch Native Prometheus APIサポート

Prometheusと互換性のある任意のクライアントをElasticsearchに向け、既存のメトリックに対してPromQLを直接実行します。Elasticsearchは、Prometheusのリモート書き込み、OpenTelemetry、またはBulk APIを通じて取り込まれたメトリックで動作するネイティブのPrometheusクエリ、検出、およびメタデータのエンドポイントをテクニカルプレビューとして追加しています。APIはElasticsearchの時系列データストリーム（TSDS）上で動作するので、Prometheus固有のストレージレイヤーを個別に運用する必要はありません。

この記事では、クエリ、検出、メタデータのエンドポイントが、以前の取り込みとクエリの作業に基づいてどのように構築され、APIサーフェスを形成するのかを説明します。関連記事では、個々のトピックについてさらに詳しく掘り下げています。

ES|QLのネイティブPromQLサポートでは、PromQLクエリがES|QL実行プランに変換される仕組みについて説明します。
Prometheus MetricsをRemote WriteでElasticsearchに送信する手順では、取り込み設定について説明します。
ElasticsearchにおけるPrometheus Remote Writeインジェストの仕組みでは、リモート書き込みの内部構造を説明しています。

これはまだ開発途中の機能です。以下のセクションでは、現在サポートされている機能と、まだ開発中の部分について記載しています。

APIサーフェス

現在、Prometheus互換APIサーフェスは3つのグループに分かれます。

クエリエンドポイント

クエリエンドポイントを使用すると、Prometheus互換クライアントはPromQL式を評価できます。

GET /_prometheus/api/v1/query_range は時間ウィンドウ内でPromQL式を評価します（マトリクス結果）。
GET /_prometheus/api/v1/query は単一の時点で評価します（ベクトル結果）。現在は、最後のサンプルを返す短範囲クエリとして実装されています。

現在、クエリエンドポイントでサポートされているのはGETのみです。一部のクライアントはデフォルトでPOSTを使用するため、GETを使用するように設定する必要があります。PrometheusのPOST規約ではapplication/x-www-form-urlencoded本文を使用しますが、ElasticsearchのHTTPレイヤーは、リクエストがハンドラーに到達する前にCSRF対策として拒否します。

PromQLの完全なカバレッジ状況については、ES|QLにおけるPromQLに関する関連記事をご覧ください。

メタデータエンドポイント

メタデータエンドポイントは、クライアントがオートコンプリート、変数のドロップダウン、およびメトリックのブラウジングに必要な検出情報を提供します。

シリーズ、ラベル、およびラベル値のエンドポイントはすべて match[] セレクターと時間範囲 (start/end) を受け入れます。match[]パラメーターはhttp_requests_total{job="api"}のようなPrometheusシリーズセレクターを取り、一致する時系列に対応を制限します。これにより、多数のメトリクスを持つクラスター上で対応を迅速かつ関連性の高いものに保ちます。例：

最初の関数は、 http_requests_totalかつjob="api"であるすべての系列を、完全なラベルセットとともに返します。2番目は、 http_requests_totalシリーズに存在するラベル名のみを返します。3番目の結果は、マッチングするシリーズに現れる instance 値のみを返します。

GET /_prometheus/api/v1/metadata は異なります。各メトリックのタイプと単位を返し、オプションでmetricパラメーターを使用して名前でフィルタリングできます。

match[]セレクターや時間範囲は受け付けません。Prometheusでは、メタデータはアクティブなスクレイピングターゲット（それらが公開するHELP、 TYPE、 UNIT行）から収集されるため、応答にはデータスキャンは含まれません。Elasticsearchにはそのような専用のメタデータストアがないため、現在の実装では過去24時間の時系列データを参照することでメトリックメタデータを検出しています。これにより、インデックス全体のスキャンを必要とせずにクエリの高速性を維持できます。その24時間遡及は現在本日に固定されています。PrometheusメタデータAPIは、Elasticsearchがユーザー調整可能にするために使用できるstartまたはendパラメーターを公開していません。

メタデータエンドポイントがどのように機能するかについては、TS_INFO と METRICS_INFO コマンドを含め、以下で説明します。

インデックスの事前フィルタリング

すべてのクエリとメタデータエンドポイントは、/_prometheus/ の後にオプションの {index} パスセグメントを受け入れます。

これは、式の評価を開始する前に、どのElasticsearchインデックスに対してクエリを実行するかを制限します。複数のチームや環境にわたる多くのデータストリームを持つクラスターでは、無関係なインデックスのスキャンを避けることで、クエリのレイテンシを大幅に削減できます。チームごとに独自のメトリクスへのスコープ付きアクセスを提供するために、インデックスパターンごとに個別のデータソースを設定できます。

リモート書き込みに関する注意事項

インジェストのために、Elasticsearchは標準のPrometheus Remote Writeエンドポイントを公開しています。

POST /_prometheus/api/v1/write Prometheus Remote Write v1プロトコルを介して時系列データを取り込みます。v2はまだサポートされていません。

Remote Writeは、Prometheus専用のストレージレイヤーではなく、Elasticsearchの既存の時系列データストリーム（TSDS）に書き込みます。PrometheusのラベルはTSDSディメンションになり、メトリック名はインデックスマッピングのフィールドになります。リモート書き込みアーキテクチャの記事では、メトリックタイプがどのように推論され、ラベルがlabels.プレフィックスでどのように格納されるかを含む、マッピングの詳細を網羅しています。

プログラム概要

内部的には、すべてのエンドポイントは同じように動作します。受信したHTTPパラメーターを解析し、ES|QLクエリプランを作成し、時系列データストリームに対してそれを実行し、列形式の結果をPrometheusクライアントが期待するJSON形式に変換します。

TS_INFOとMETRICS_INFO

メタデータエンドポイントは、すべてのデータポイントをスキャンすることなく、数百万もの時系列データに対して、「どのようなラベルが存在するか？」や「どのようなメトリックタイプが定義されているか？」といった質問に答える必要があります。

内部的には、Prometheusのメタデータエンドポイントは、2つの新しい処理コマンドMETRICS_INFOとTS_INFOを中心にES|QLプランを構築することで、これらの質問に答えます。Prometheus APIを使用するためにこれらのコマンドを直接使用する必要はありませんが、これらはメタデータ応答の背後にあるコアとなる実行プリミティブです。どちらも、すべてのサンプルをスキャンするのではなく、時系列ごとに1つの文書にのみアクセスしてメタデータを抽出します。これは、コストがデータポイントの数ではなく、個別の時系列の数に応じてスケールすることを意味します。

METRICS_INFO 1行ごとに、その名前、タイプ、単位、および関連するディメンションフィールドを持つ固有のメトリックを返します。TS_INFOはより詳細な情報を提供します。メトリック、時系列の組み合わせごとに1行が含まれ、実際のディメンション値がJSONオブジェクトとして含まれます。

TS_INFOとMETRICS_INFOに関する専用のブログ記事がまもなく公開されます。二段階実行モデル、それらのスケール方法、そしてPrometheus APIを超えてES|QLクエリで直接使用する方法について詳しく解説します。

メタデータエンドポイントがこれらを使用する方法

各メタデータエンドポイントは、これらのコマンドのいずれかをコアとしてES|QLプランを構築します。

/api/v1/labels また、/api/v1/seriesはTS_INFOを使用します。これは、時系列ごとの詳細情報（どのラベルが存在するか、どのディメンション値が各系列を識別するか）が必要なためです。/api/v1/metadataと/api/v1/label/__name__/valuesは、メトリクス名、型、単位などの各メトリクス情報のみを必要とするため、METRICS_INFOを使用します。

/api/v1/label/{name}/values 通常のラベル（__name__以外）の場合は、どちらのコマンドも使用しません。通常のラベル job や instance は、インデックス内の実際のディメンションフィールドなので、エンドポイントはグループ分けアグリゲーションで直接クエリできます。match[] 個のセレクターが提供されると、それらは時系列をフィルタリングする WHERE 句に変換され、アグリゲーションが実行される前に適用されます。

__name__ラベルは、ディメンションフィールドとして常に存在するとは限らないため、別の戦略が必要です。Prometheus Remote Writeはlabels.__name__ を保存しますが、他の経路（OpenTelemetry、Bulk API）で取り込まれたメトリクスには保存されません。メトリック名はフィールド名自体にエンコードされています（例： metrics.http_requests_total ）。インデックスマッピングを見てフィールド名を列挙することはできますが、マッピングだけではどのメトリックがどのディメンションを持っているかはわかりませんし、 match[]セレクターからのラベル値でフィルタリングすることもできません。METRICS_INFOは両方を行うことができます。インデックス全体でメトリック名を列挙しながら、上流のWHEREフィルターを尊重します。

すべての場合において、APIレイヤーはPrometheusの規則に戻す変換を処理します。labels.とmetrics.のストレージプレフィックスを除去し、__name__をPrometheus以外のメトリクスに対して合成します。

まとめ

その結果、Prometheusと互換性のあるクライアントであれば、すでに理解しているエンドポイントを利用してElasticsearchをクエリし、調査することができます。リモート書き込みメトリック、OpenTelemetryメトリック、およびその他の経路でインデックスされたメトリックはすべて、同じTSDSインデックスによって支えられた同じAPIを通じて表示されます。

ここで紹介したすべてのPrometheus APIは、現在Elasticsearch Serverlessのテクニカルプレビューとして利用可能です。セルフマネージドクラスターおよびElastic Cloud Hostedの導入は、GET /_prometheus/api/v1/metadataを除いて、Elasticsearch 9.4でテクニカルプレビューとして利用可能です。ローカルで実験するにはstart-localを使用します。

よくあるご質問

Prometheus互換のクエリAPIとメタデータAPIは、Remote Writeでインジェストされたデータでのみ動作しますか？

いいえ。Prometheusと互換性のあるAPIは、時系列データストリーム（TSDS）の任意のElasticsearch上で動作します。Prometheus Remote Write、OpenTelemetry、またはBulk APIからのメトリックを保持する同じインデックスが、操作する追加のストレージレイヤーを介さずに、PromQLを介して直接クエリされます。

POSTでクエリエンドポイントを呼び出すと、Prometheusクライアントが失敗するのはなぜですか？

現在、PrometheusのクエリエンドポイントではGETのみがサポートされています。一部のクライアントはデフォルトでapplication/x-www-form-urlencodedを使用してPOSTしますが、ElasticsearchのHTTPレイヤーはリクエストがハンドラーに到達する前にCSRF対策として拒否します。GETを使用するようにクライアントを設定します。

PrometheusクエリをElasticsearch内のインデックスのサブセットにスコープできますか？

はい。すべてのクエリおよびメタデータエンドポイントは、/_prometheus/metrics-prod-*/api/v1/query_rangeのようなオプションの{index}セグメントに対応します。これにより、評価前にクエリをマッチングインデックスに限定し、無関係なデータのスキャンを回避できます。

ネイティブのPrometheus APIは、専用のPrometheusサーバーを運用する場合と比べてどう違うのでしょうか？

ElasticsearchはPrometheus Remote Write、OpenTelemetry、その他のインジェストパスを、TSDSを基盤とする単一のストアに統合し、PromQLまたはES|QLでクエリ可能です。Prometheusクライアントの互換性を維持したまま、長期保存、ILM、同一クラスターに保存されたログやトレースとの相関付けなど、既存のElasticsearch機能を再利用できます。