メインコンテンツへスキップ
ClickHouse は TimeSeries テーブルを介して Prometheus HTTP API を実装しています。単一のハンドラーが、リモート書き込み、リモート読み取り、インスタント PromQL クエリ、範囲 PromQL クエリを処理します。 Prometheus サーバーがスクレイプできるように ClickHouse 自身のメトリクスを公開する方法については、Prometheus メトリクスエンドポイントを参照してください。

前提条件

セットアップ手順は ClickHouse Cloud とセルフマネージドの ClickHouse で異なります。ご利用のデプロイメントに該当するセクションに従ってください。

ClickHouse Cloud

ClickHouse Cloud における PromQL のサポートはプライベートプレビューです。プライベートプレビューの対象となっているサービスでは、enable_time_series_table 設定と Prometheus API エンドポイントがすでに構成済みです。それ以外の ClickHouse Cloud サービスにはこの構成がなく、ユーザー自身でこの機能を有効化することはできません。以降のセクションで説明する SET enable_time_series_table ステートメントおよび http_handlers の構成は、セルフマネージドのデプロイメントに適用されるものです。
プライベートプレビューの対象となっているサービスでは、TimeSeries テーブルを作成するに進んでください。対象サービスでは、エンドポイント一覧に記載されたエンドポイントパスが利用できます。

セルフマネージド: TimeSeries設定を有効にする

テーブルを作成しアクセスするユーザーに対して、enable_time_series_table 設定を有効にします。
HTTP APIリクエストの場合は、APIユーザーのプロファイルでenable_time_series_tableを有効にします。

セルフマネージド: Prometheus API エンドポイントを設定する

ClickHouse のメイン HTTP ポートで、プレフィックスルーティングされたハンドラーを 1 つ設定します。
<defaults/> は、/ping などのエンドポイントや SQL リクエスト用の組み込みハンドラーを維持します。上記のプレフィックスにより、これらのエンドポイントを 1 つのハンドラー経由で公開します。 この例では、ハンドラーに database と table を指定していません。各リクエストで table クエリパラメータを指定する必要があります (/format_query は指定された PromQL 式をパースするだけなので、テーブルは不要です) 。また、database を指定する、prometheus.metrics のような完全修飾テーブル名を使用する、またはデータベースを省略して default を使用することもできます。これにより、1 つのハンドラーで複数の TimeSeries テーブルを処理できます。 すべてのリクエストで 1 つの固定テーブルを使用するには、ハンドラーで設定します。
ハンドラーで設定されたテーブルは、リクエストパラメータで上書きできません。 ルーティングとハンドラーの設定:

TimeSeriesテーブルを作成する

データベースと TimeSeries テーブルを作成します。

リモート書き込み を使用してメトリクスを取り込む

ClickHouse は Prometheus リモート書き込み プロトコルをサポートしています。Prometheus がハンドラーに書き込むように設定します。
Prometheus はサンプルを prometheus.metrics テーブルに送信します。 多数の同時実行 リモート書き込み リクエストからのデータを少ないパーツにまとめるために、ClickHouse は非同期挿入を使用します。非同期挿入はデフォルトで有効になっており、URL (またはユーザープロファイル) の async_insert 設定で有効・無効を切り替えられます。 ClickHouse は、wait_for_async_insert 設定にかかわらず、データが TimeSeries テーブルのすべての内部テーブルにフラッシュされた後にのみ、非同期 リモート書き込み リクエストを受理します。リモート書き込み プロトコルでは、受理された書き込みは永続化済みとして扱われます。フラッシュに失敗した場合、リクエストはエラーを返し、Prometheus は再試行します。 各リクエストは自身のフラッシュを待機するため、非同期挿入を使用すると、1 つの送信元が書き込める速度に上限が生じます。Prometheus は、リモート書き込みのシャードごとに一度に 1 つのリクエストしか送信しません。複数のシャードが同時に送信すると、保留中のリクエストが先に async_insert_max_data_size に達しない限り、アダプティブなフラッシュのタイムアウトは async_insert_busy_timeout_max_ms まで延びます。リクエストは自身のバッチがフラッシュされるまで待機し、そのフラッシュはバッチ開始から最大でこの時間が経過した時点で行われます。そのため、負荷が継続する状況では、各シャードの書き込み速度はおおよそ samples per request / async_insert_busy_timeout_max_ms になります。なお、Prometheus はデフォルトで 1 リクエストあたり最大 2,000 サンプルを送信します。この速度を上げるには、次のいずれかを行います。
  • remote_write の queue_config で max_shards (デフォルトは 50) または max_samples_per_send を引き上げます。Prometheus は処理が追いつかなくなると、max_shards を上限として自動的にシャードを追加します。
  • URL またはユーザープロファイルで async_insert_busy_timeout_max_ms を引き下げます (例: &async_insert_busy_timeout_max_ms=50)。これによりフラッシュの頻度が上がりますが、フラッシュのたびに内部テーブルに新しいパーツが作成されます。
  • async_insert=0 で非同期挿入を無効化します。この場合、リクエストごとに内部テーブルに個別のパーツが作成されます。

PromQL でクエリを実行する

instant-query エンドポイントを使用して、特定の時点における PromQL 式を評価します。
range-query エンドポイントを使用して、指定した時間範囲で式を評価します。
クエリエンドポイントは、フォームボディでのパラメータ受け渡しにも対応しています。--get を指定しない場合、curl はパラメータを application/x-www-form-urlencoded として POST で送信します。
フォーマット-query エンドポイントを使用して、PromQL 式を評価せずにパースおよびフォーマットします。
式はパース済みクエリからシリアライズされて返され、空白は正規化され、コメントは削除され、冗長な括弧は除去され、期間はパーサーが受け付ける単位で出力されます: sum by (job) (http_requests_total{code="200"}) / 2。期間は秒数に変換されず単位が保持されるため、rate(x[5m]) は rate(x[5m]) のまま返されます。また、単一の単位の整数倍で表せない期間は、必要な単位を組み合わせて表記されます。たとえば rate(x[90s]) は rate(x[1m30s]) として返されます。このエンドポイントは式を評価しないため、database および table パラメータは不要です。 HTTP API、promql 方言、およびテーブル関数で使用される関数と集約演算子の一覧については、サポートされている PromQL 機能を参照してください。

Grafana

ベース URL が /api/v1 の直前までとなるように、Prometheus データソースを設定します。
Grafana は、このベース URL に /api/v1/query または /api/v1/query_range を付加し、各リクエストに customQueryParameters を追加します。 httpMethod: POST の場合、Grafana はクエリパラメータをリクエストボディで送信します。ClickHouse はリクエストボディと URL のクエリ文字列の両方を読み取るため、customQueryParameters は引き続き適用されます。URL には長さの制限があるため、長い PromQL 式には POST を使用してください。
実装されているのは、クエリエンドポイント /api/v1/query、/api/v1/query_range、/api/v1/format_query、およびメタデータエンドポイント /api/v1/series、/api/v1/labels、/api/v1/label/<name>/values、/api/v1/metadata のみです。/api/v1/series には少なくとも 1 つの match[] シリーズセレクターが必要で、任意の start、end、limit パラメータをサポートし、各セレクターに一致するシリーズのユニオンを返します。/api/v1/labels は同じパラメータを受け付けますが、match[] は任意であり、一致するシリーズのソート済みラベル名を返します (セレクターが指定されていない場合はすべてのシリーズのラベル名を返します) 。/api/v1/label/<name>/values は /api/v1/labels と同じパラメータを受け付け、1 つのラベルのソート済みの値を返します。<name> には、[a-zA-Z0-9_] 以外の文字を含むラベル名に対して Prometheus の U__... エスケープを任意で使用できます。これらのエンドポイントは、Grafana の Prometheus データソースがラベルの参照、Template 変数、クエリビルダーでの自動補完に使用する機能をカバーします。

SQL エントリポイント

ClickHouse では、HTTP API、promql 方言、および prometheusQuery と prometheusQueryRange のテーブル関数で、同じ PromQL コンバーターを使用します。 clickhouse-client で PromQL を直接実行します。
テーブル関数を使用して、SQLクエリ内にPromQLを埋め込みます。

メトリクスのメタデータをクエリする

/prometheus/api/v1/metadata エンドポイントは、TimeSeries テーブルの Metrics ターゲットテーブルに格納されているメトリクスのメタデータ (各メトリクスファミリーの型、ヘルプテキスト、単位) を返します。URL のクエリ文字列では、次の Prometheus パラメータをサポートしています。 デフォルトの Metrics ターゲットテーブルは、メトリクスファミリー名で順序付けられた ReplacingMergeTree です。各メトリクスファミリーについて、最後に書き込まれたメタデータエントリを保持します。ファミリーごとに複数のエントリが返されるのは、ターゲットテーブルにそれらが保持されている場合のみです。つまり、パーツがマージされる前、またはそれらを保持するエンジンでテーブルが定義されている場合です。

リモート読み取り でメトリクスを読み取る

ClickHouse は、/prometheus/api/v1/read で Prometheus リモート読み取り プロトコルをサポートしています。 同じ TimeSeries テーブルから読み取るように Prometheus サーバーを設定します。

レコーディングルール

ClickHouse は Prometheus のルールファイルを評価しません。代わりに、リフレッシャブルmaterialized view を使用すると、レコーディングルールと同じ役割を果たせます。具体的には、PromQL の式をスケジュールに従って評価し、その結果を TimeSeries テーブルに追記します。次のビューは、sum by (job) (rate(http_requests_total[5m])) を 1 分ごとに job:http_requests:rate5m として記録します。
リフレッシュのたびに、現在の分の開始時刻を基準に式を評価し、mapUpdate でメトリクス名を設定したうえで、結果の系列ごとにサンプルを 1 つ追記します。同じ Map に追加ラベルを含めることもできます (例: map('__name__', 'job:http_requests:rate5m', 'team', 'web')) 。記録された系列は、他のメトリクスと同じようにクエリできます:
最後の評価の時刻とエラーは system.view_refreshes に表示されます。 ビューは、Prometheus のレコーディングルールと以下の点で異なります。
  • 評価時刻は、リフレッシュが実行された時点の now() です。ビューはスケジュールに基づくリフレッシュに加えて、作成直後 (EMPTY 付きで作成された場合を除く) 、リフレッシュが協調されていない場合のサーバー再起動後 (Replicated または Shared データベース外のビュー、または all_replicas = 1 が指定されたビューは、最後のリフレッシュを記憶しません) 、そしてスケジュールされたリフレッシュを逃した後に SYSTEM START VIEW で再開されたときにもリフレッシュされます。これらのリフレッシュによってスケジュールどおりのサンプルの間に余分なサンプルが追加されないよう、例のように now() をインターバル単位で切り捨ててください。ただし、それでも追加のリフレッシュによって、同じ丸められたタイムスタンプに 2 つ目のサンプルが書き込まれる場合があります。5 分間隔のルールには、toStartOfInterval(now(), INTERVAL 5 MINUTE) を使用してください。
  • 実行されなかった評価が後から補完されることはありません。サーバーが停止していた場合やビューが停止されていた場合、ビューは現在のインターバルのみを評価し、それ以前のインターバルは空のままになります。リフレッシュにインターバルより長い時間がかかった場合も同様です。
  • 結果から外れた系列にはデータの有効期間を示すマーカー (staleness marker) が付与されないため、クエリはルックバック期間 (デフォルトでは 5 分) が経過するまで、その系列の最後に記録された値を返し続けます。
  • ルールファイルは存在せず、各ルールはそれぞれ個別のビューです。これらのルールは /api/v1/rules には一覧表示されません。