Prometheus HTTP API と PromQL

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 設定を有効にします。

SET enable_time_series_table = 1;

HTTP APIリクエストの場合は、APIユーザーのプロファイルでenable_time_series_tableを有効にします。

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

ClickHouse のメイン HTTP ポートで、プレフィックスルーティングされたハンドラーを 1 つ設定します。

<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>

<defaults/> は、/ping などのエンドポイントや SQL リクエスト用の組み込みハンドラーを維持します。上記のプレフィックスにより、これらのエンドポイントを 1 つのハンドラー経由で公開します。

エンドポイント	用途
`/prometheus/api/v1/write`	Prometheus リモート書き込み
`/prometheus/api/v1/read`	Prometheus リモート読み取り
`/prometheus/api/v1/query`	インスタント PromQL クエリ
`/prometheus/api/v1/query_range`	範囲 PromQL クエリ
`/prometheus/api/v1/format_query`	PromQL 式のフォーマット
`/prometheus/api/v1/series`	シリーズのメタデータ
`/prometheus/api/v1/metadata`	メトリクスファミリーのメタデータ

この例では、ハンドラーに database と table を指定していません。各リクエストで table クエリパラメータを指定する必要があります (/format_query は指定された PromQL 式をパースするだけなので、テーブルは不要です) 。また、database を指定する、prometheus.metrics のような完全修飾テーブル名を使用する、またはデータベースを省略して default を使用することもできます。これにより、1 つのハンドラーで複数の TimeSeries テーブルを処理できます。すべてのリクエストで 1 つの固定テーブルを使用するには、ハンドラーで設定します。

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

ハンドラーで設定されたテーブルは、リクエストパラメータで上書きできません。ルーティングとハンドラーの設定:

名前	デフォルト	説明
`url_prefix`	none	設定されたプレフィックスで始まるすべてのリクエストパスに一致するルールフィルター。
`table`	none	`TimeSeries` テーブル名。省略した場合、リクエストで `table` クエリパラメータを指定する必要があります。設定する名前にはデータベースを含めることができます。
`database`	none	テーブルを含むデータベース。リクエストでクエリパラメータとして指定できます。省略した場合、ClickHouse は完全修飾された `table` 値に含まれるデータベースを使用し、指定がなければ `default` を使用します。

TimeSeriesテーブルを作成する

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

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

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

ClickHouse は Prometheus リモート書き込みプロトコルをサポートしています。Prometheus がハンドラーに書き込むように設定します。

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Prometheus はサンプルを prometheus.metrics テーブルに送信します。多数の同時実行リモート書き込みリクエストからのデータを少ないパーツにまとめるには、URL に async_insert 設定を追加する (またはユーザープロファイルで有効にする) ことで、非同期挿入を有効にします。

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

ClickHouse は、wait_for_async_insert 設定にかかわらず、データが TimeSeries テーブルのすべての内部テーブルにフラッシュされた後にのみ、非同期リモート書き込みリクエストを受理します。リモート書き込みプロトコルでは、受理された書き込みは永続化済みとして扱われます。フラッシュに失敗した場合、リクエストはエラーを返し、Prometheus は再試行します。

PromQL でクエリを実行する

instant-query エンドポイントを使用して、特定の時点における PromQL 式を評価します。

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

range-query エンドポイントを使用して、指定した時間範囲で式を評価します。

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

クエリエンドポイントは、フォームボディでのパラメータ受け渡しにも対応しています。--get を指定しない場合、curl はパラメータを application/x-www-form-urlencoded として POST で送信します。

curl --user default:<password> \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

フォーマット-query エンドポイントを使用して、PromQL 式を評価せずにパースおよびフォーマットします。

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"

式はパース済みクエリからシリアライズされて返され、空白は正規化され、コメントは削除され、冗長な括弧は除去され、期間は秒数に変換されます: sum by (job) (http_requests_total{code="200"}) / 2。このエンドポイントは式を評価しないため、database および table パラメータは不要です。 HTTP API、promql 方言、およびテーブル関数で使用される関数と集約演算子の一覧については、サポートされている PromQL 機能を参照してください。

Grafana

ベース URL が /api/v1 の直前までとなるように、Prometheus データソースを設定します。

apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

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 を直接実行します。

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

テーブル関数を使用して、SQLクエリ内にPromQLを埋め込みます。

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

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

/prometheus/api/v1/metadata エンドポイントは、TimeSeries テーブルの Metrics ターゲットテーブルに格納されているメトリクスのメタデータ (各メトリクスファミリーの型、ヘルプテキスト、単位) を返します。URL のクエリ文字列では、次の Prometheus パラメータをサポートしています。

パラメータ	説明
`metric`	指定したメトリクスファミリーのメタデータのみを返します。
`limit`	返されるメトリクスファミリーの数を制限します。負の値は無制限を意味し、ゼロの場合はメトリクスファミリーを返しません。
`limit_per_metric`	各メトリクスファミリーについて返されるメタデータオブジェクトの数を制限します。ゼロおよび負の値は無制限を意味します。

デフォルトの Metrics ターゲットテーブルは、メトリクスファミリー名で順序付けられた ReplacingMergeTree です。各メトリクスファミリーについて、最後に書き込まれたメタデータエントリを保持します。ファミリーごとに複数のエントリが返されるのは、ターゲットテーブルにそれらが保持されている場合のみです。つまり、パーツがマージされる前、またはそれらを保持するエンジンでテーブルが定義されている場合です。

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

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

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

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

基礎

ClickHouseの基本概念

ベストプラクティス

前提条件

ClickHouse Cloud

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

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

TimeSeriesテーブルを作成する

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

PromQL でクエリを実行する

Grafana

SQL エントリポイント

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

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

​前提条件

​ClickHouse Cloud

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

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

​TimeSeriesテーブルを作成する

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

​PromQL でクエリを実行する

​Grafana

​SQL エントリポイント

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

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

前提条件

ClickHouse Cloud

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

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

TimeSeriesテーブルを作成する

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

PromQL でクエリを実行する

Grafana

SQL エントリポイント

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

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