Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Prometheus プロトコルと PromQL

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickHouse サーバーメトリクスを公開する

Prometheus サーバーが ClickHouse 独自のメトリクスをスクレイピングする必要がある場合は、専用ポートを設定します：

<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
    <histograms>true</histograms>
    <dimensional_metrics>true</dimensional_metrics>
</prometheus>

<prometheus.handlers> セクションを使用すると、同じポート上でより拡張されたハンドラーを作成できます。 This section is similar to <http_handlers> but works for prometheus プロトコル:

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

設定:

Name Default Description
port none ClickHouse メトリクスを提供するポートです。
endpoint /metrics メトリクスをスクレイピングするための HTTP エンドポイントです。/ で始まります。<handlers> セクションと併用しないでください。
url / headers / method none リクエストに一致するハンドラーを見つけるためのフィルターです。<http_handlers> セクションの同名のフィールドと同様です。
info true サーバー ID ラベル (name、version、version_describe、version_major、version_minor、version_patch) を含む ClickHouse_Info Gauge を公開します。
metrics true system.metrics のメトリクスを公開します。
asynchronous_metrics true system.asynchronous_metrics のメトリクスを公開します。
events true system.events のメトリクスを公開します。
errors true system.errors のエラー数を公開します。
histograms true system.histogram_metrics のメトリクスを公開します。
dimensional_metrics true system.dimensional_metrics のメトリクスを公開します。
labels none 公開されるすべてのメトリクスに追加される定数ラベルです。各子要素は 1 つのラベルを定義します。要素名はラベル名 ([a-zA-Z_][a-zA-Z0-9_]* に一致する必要があります) であり、要素値はラベル値です。ラベル値では、from_env 属性などの標準的な設定の置換をサポートします。ラベル名が __ (Prometheus により予約済み) で始まる場合、またはこのエンドポイントが有効なセクションのいずれかですでに書き込むラベルと競合する場合、そのラベル名は拒否されます。したがって、予約済みの集合はエンドポイントの有効な公開対象に従います。histograms が有効な場合は le、info が有効な場合は ClickHouse_Info のラベル (name、version、version_describe、version_major、version_minor、version_patch) 、histograms または dimensional_metrics が有効な場合は公開されるヒストグラムまたは次元メトリクスファミリーで使用されるラベル (例: group、direction、operation_type) です。エンドポイントが実際に公開する内容に依存するため、あるエンドポイントでは有効な名前でも、別のエンドポイントでは拒否される場合があります。

エンドポイントを確認します：

curl http://127.0.0.1:9363/metrics
ClickHouse Cloud ではサポートされていません

Prometheus HTTP API と PromQL

ClickHouse は TimeSeries テーブルを介して Prometheus HTTP API を実装しています。単一のハンドラーが、リモート書き込み、リモート読み取り、インスタント PromQL クエリ、範囲 PromQL クエリを処理します。

前提条件

テーブルを作成しアクセスするユーザーに対して、allow_experimental_time_series_table 設定を有効にします。

SET allow_experimental_time_series_table = 1;

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

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

HTTP APIリクエストの場合は、APIユーザーのprofileでallow_experimental_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/series シリーズのメタデータ
/prometheus/api/v1/metadata メトリクスファミリーのメタデータ

この例では、ハンドラーに database と table を指定していません。各リクエストで table クエリパラメータを指定する必要があります。また、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 を使用します。

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

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"

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: GET
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

Grafana は、このベース URL に /api/v1/query または /api/v1/query_range を付加し、各リクエストに customQueryParameters を追加します。

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>
Navigation