Prometheus インテグレーション

この機能は、Prometheus との統合により、ClickHouse Cloud サービスを監視できるようにします。Prometheus メトリクスへのアクセスは、ClickHouse Cloud API のエンドポイント経由で提供されており、安全に接続して Prometheus メトリクス collector にメトリクスをエクスポートできます。これらのメトリクスは、Grafana や Datadog などのダッシュボードに統合して可視化できます。

サービスにアタッチされた ClickPipes のメトリクスは、そのサービスの ClickHouse メトリクスとともに含まれます。

利用を開始するには、API キーを生成してください。

ClickHouse Managed Postgres サービスに対応するエンドポイントをお探しの場合は、ClickHouse Managed Postgres Prometheus エンドポイントを参照してください。

ClickHouse Cloud のメトリクスを取得する Prometheus エンドポイント API

APIリファレンス

メソッド	パス	説明
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true \| false]`	特定のサービスのメトリクスを返します
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true \| false]`	非推奨。組織内の全サービスのメトリクスを返します
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus/discovery?filtered_metrics=[true \| false]`	組織内のすべてのサービスのPrometheusスクレイプターゲットを、HTTP service discoveryフォーマットで返します

リクエストパラメータ

名前	場所	型
組織 ID	エンドポイントアドレス	uuid
サービス ID	エンドポイントアドレス	uuid (任意)
filtered_metrics	クエリパラメータ	boolean (任意)

これらのエンドポイントの完全なリクエストおよびレスポンススキーマは、Cloud API リファレンスで確認できます。

認証

基本認証には、ClickHouse Cloud API キーを使用します。

Username: <KEY_ID>
Password: <KEY_SECRET>
Example request
export KEY_SECRET=<key_secret>
export KEY_ID=<key_id>
export ORG_ID=<org_id>

# $ORG_ID 内のすべてのサービスに対して
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# 単一サービスのみに対して
export SERVICE_ID=<service_id>
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/prometheus?filtered_metrics=true

レスポンス例

# HELP ClickHouse_ServiceInfo クラスターステータスおよびClickHouseバージョンを含む、サービスに関する情報
# TYPE ClickHouse_ServiceInfo untyped
ClickHouse_ServiceInfo{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",clickhouse_cluster_status="running",clickhouse_version="24.5",scrape="full"} 1

# HELP ClickHouseProfileEvents_Query 解釈され、実行される可能性のあるクエリの数。パースに失敗したクエリ、またはASTサイズ制限・クォータ制限・同時実行クエリ数の制限により拒否されたクエリは含まれない。ClickHouse自身が開始した内部クエリが含まれる場合がある。サブクエリはカウントしない。
# TYPE ClickHouseProfileEvents_Query counter
ClickHouseProfileEvents_Query{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 6

# HELP ClickHouseProfileEvents_QueriesWithSubqueries すべてのサブクエリを含むクエリ数
# TYPE ClickHouseProfileEvents_QueriesWithSubqueries counter
ClickHouseProfileEvents_QueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 230

# HELP ClickHouseProfileEvents_SelectQueriesWithSubqueries すべてのサブクエリを含むSELECTクエリ数
# TYPE ClickHouseProfileEvents_SelectQueriesWithSubqueries counter
ClickHouseProfileEvents_SelectQueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 224

# HELP ClickHouseProfileEvents_FileOpen オープンされたファイルの数。
# TYPE ClickHouseProfileEvents_FileOpen counter
ClickHouseProfileEvents_FileOpen{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 4157

# HELP ClickHouseProfileEvents_Seek 'lseek'関数が呼び出された回数。
# TYPE ClickHouseProfileEvents_Seek counter
ClickHouseProfileEvents_Seek{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 1840

# HELP ClickPipes_Info 常に1。ラベル"clickpipe_state"にはパイプの現在の状態が含まれる: Stopped/Provisioning/Running/Paused/Failed
# TYPE ClickPipes_Info gauge
ClickPipes_Info{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent",clickpipe_status="Running"} 1

# HELP ClickPipes_SentEvents_Total ClickHouseに送信されたレコードの総数
# TYPE ClickPipes_SentEvents_Total counter
ClickPipes_SentEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5534250

# HELP ClickPipes_SentBytesCompressed_Total ClickHouseに送信された圧縮バイトの総数。
# TYPE ClickPipes_SentBytesCompressed_Total counter
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name
="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 380837520
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name

# HELP ClickPipes_FetchedBytes_Total ソースから取得した非圧縮バイトの総数。
# TYPE ClickPipes_FetchedBytes_Total counter
ClickPipes_FetchedBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_Errors_Total データ取り込み時のエラーの総数。
# TYPE ClickPipes_Errors_Total counter
ClickPipes_Errors_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 0

# HELP ClickPipes_SentBytes_Total ClickHouseに送信された非圧縮バイトの総数。
# TYPE ClickPipes_SentBytes_Total counter
ClickPipes_SentBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 477187967

# HELP ClickPipes_FetchedBytesCompressed_Total ソースから取得した圧縮バイトの総数。ソースのデータが非圧縮の場合、この値はClickPipes_FetchedBytes_Totalと等しくなる。
# TYPE ClickPipes_FetchedBytesCompressed_Total counter
ClickPipes_FetchedBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_FetchedEvents_Total ソースから取得したレコードの総数。
# TYPE ClickPipes_FetchedEvents_Total counter
ClickPipes_FetchedEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5535376

メトリクスラベル

すべてのメトリクスには、以下のラベルが含まれます。

Label	Description
clickhouse_org	組織 ID
clickhouse_service	サービス ID
clickhouse_service_name	サービス名

ClickPipes のメトリクスには、以下のラベルも含まれます。

Label	Description
clickpipe_id	ClickPipe ID
clickpipe_name	ClickPipe 名
clickpipe_source	ClickPipe ソースタイプ

情報メトリクス

ClickHouse Cloud は、値が常に 1 の特別な Gauge メトリクス ClickHouse_ServiceInfo を提供します。このメトリクスには、すべての Metric Labels に加えて、次のラベルが含まれます。

Label	Description
clickhouse_cluster_status	サービスのステータス。次のいずれかです: [`awaking`
clickhouse_version	サービスで稼働している ClickHouse server のバージョン
scrape	直近のスクレイプのステータスを示します。`full` または `partial` のいずれかです
full	直近のメトリクスのスクレイプ中にエラーがなかったことを示します
partial	直近のメトリクスのスクレイプ中に一部エラーが発生し、`ClickHouse_ServiceInfo` メトリクスのみが返されたことを示します。

メトリクス取得のリクエストでは、idled 状態のサービスは再開されません。サービスが idle 状態の場合、ClickHouse_ServiceInfo メトリクスのみが返されます。

ClickPipes にも同様に Gauge メトリクス ClickPipes_Info があり、Metric Labels に加えて次のラベルが含まれます。

Label	Description
clickpipe_state	パイプの現在の状態

Prometheus の設定

Prometheus サーバーは、設定されたターゲットから指定した間隔でメトリクスを収集します。以下は、Prometheus サーバーで ClickHouse Cloud の Prometheus エンドポイントを使用するための設定例です。

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
    - targets: ["localhost:9090"]
  - job_name: "clickhouse"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    scheme: https
    params:
      filtered_metrics: ["true"]
    metrics_path: "/v1/organizations/<ORG_ID>/prometheus"
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

honor_labels のconfiguration parameterは、インスタンスラベルが正しく設定されるよう true に設定する必要がある点に注意してください。さらに、上記の例では filtered_metrics も true に設定されていますが、これはユーザーの好みに応じて設定してください。

サービスの自動検出

ベータ機能

ディスカバリーエンドポイントは、組織内のサービスごとに1つのスクレイプターゲットを、Prometheus の HTTP service discovery (http_sd) フォーマットで返します。Prometheus はディスカバリーのポーリングごとにターゲットリストを更新し、検出された各ターゲットをスクレイプするため、新たに作成されたサービスは自動的に追加され、削除されたサービスはターゲットリストから除外されます。API キーに閲覧権限のあるサービスのみが含まれ、削除中または削除済みのサービスは含まれません。

使用するには、http_sd_configs job でディスカバリーエンドポイントを指定します。

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "clickhouse"
    http_sd_configs:
      - url: https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/prometheus/discovery
        refresh_interval: 60s
        basic_auth:
          username: <KEY_ID>
          password: <KEY_SECRET>
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

両方の箇所で basic_auth を設定します。http_sd_configs 配下のブロックではディスカバリーのポーリングを認証し、スクレイプジョブのブロックではサービスごとのメトリクススクレイプを認証します。静的設定と同様に、インスタンスラベルが適切に設定されるよう honor_labels: true を設定します。

ディスカバリー応答のサンプル:

[
  {
    "targets": ["api.clickhouse.cloud"],
    "labels": {
      "__scheme__": "https",
      "__metrics_path__": "/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/prometheus",
      "__param_filtered_metrics": "true",
      "clickhouse_org_id": "<ORG_ID>",
      "clickhouse_service_id": "<SERVICE_ID>",
      "clickhouse_discovery_service_name": "my service"
    }
  }
]

検出されたターゲットは、filtered_metrics=true を指定してスクレイプされます。すべてのメトリクスセットをスクレイプするターゲットを検出するには、検出 URL に ?filtered_metrics=false を追加します。エンドポイントの完全な仕様については、Cloud API リファレンスを参照してください。

Grafana との統合

Grafana と統合する主な方法は 2 つあります。

Metrics Endpoint – この方法の利点は、追加のコンポーネントやインフラストラクチャが不要なことです。この機能は Grafana Cloud でのみ利用でき、必要なのは ClickHouse Cloud Prometheus エンドポイント URL と認証情報だけです。
Grafana Alloy - Grafana Alloy は、Grafana Agent に代わる、ベンダー中立の OpenTelemetry (OTel) collector ディストリビューションです。スクレーパーとして使用でき、自社のインフラストラクチャにデプロイ可能で、あらゆる Prometheus エンドポイントと互換性があります。

以下では、これらのオプションの使用方法を説明します。特に ClickHouse Cloud Prometheus エンドポイントに固有の詳細に焦点を当てます。

Metrics Endpoint を使用した Grafana Cloud

Grafana Cloud アカウントにログインします
Metrics Endpoint を選択して、新しい接続を追加します
Scrape URL が Prometheus エンドポイントを指すように設定し、ベーシック認証を使用して API キー/シークレットで接続を構成します
接続テストを実行し、接続できることを確認します

設定が完了すると、ダッシュボードを構成する際に選択できるドロップダウンにメトリクスが表示されます。

Grafana Cloud で Alloy を使用する

Grafana Cloud を使用している場合は、Grafana の Alloy メニューに移動し、画面上の指示に従って Alloy をインストールできます。

これにより、認証トークンを使用して Grafana Cloud のエンドポイントにデータを送信するための prometheus.remote_write コンポーネントを含むように Alloy が設定されます。あとは、Alloy の設定 (Linux では /etc/alloy/config.alloy) を変更し、ClickHouse Cloud Prometheus エンドポイント用のスクレーパーを追加するだけです。

以下は、ClickHouse Cloud エンドポイントからメトリクスをスクレイプするための prometheus.scrape コンポーネントと、自動的に設定される prometheus.remote_write コンポーネントを含む Alloy の設定例です。basic_auth 設定コンポーネントには、それぞれユーザー名とパスワードとして Cloud API キーの ID とシークレットが含まれている点に注意してください。

prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<clickhouse_org_id>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels    = true
  scrape_interval = "30s"
  scrape_timeout  = "25s"

  basic_auth {
  username = "<clickhouse_api_key_id>"
  password = "<clickhouse_api_key_secret>"
  }

  forward_to = [prometheus.remote_write.grafana_cloud.receiver]
}

  prometheus.remote_write "grafana_cloud" {
  endpoint {
  url = "https://<grafana_prometheus_url>/api/prom/push"

  basic_auth {
  username = "<grafana_username>"
  password = "<grafana_api_token>"
  }
  }
}

インスタンスラベルが正しく設定されるよう、honor_labels 設定パラメータを true に設定する必要がある点に注意してください。

Alloy を使用する Grafana のセルフマネージド環境

Grafana をセルフマネージドで利用している場合、Alloy エージェントのインストール手順はこちらで確認できます。ここでは、Alloy が Prometheus メトリクスを任意の宛先に送信するよう設定済みであることを前提としています。以下の prometheus.scrape コンポーネントにより、Alloy は ClickHouse Cloud エンドポイントをスクレイプします。スクレイプしたメトリクスは prometheus.remote_write が受け取る想定です。これが存在しない場合は、forward_to key を対象の宛先に合わせて調整してください。

// prometheus.scrape component causes Alloy to scrape the ClickHouse Cloud Prometheus endpoint.
  // Adjust the forward_to key to match your remote_write receiver if it differs.
  prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<organizationId>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels = true

  basic_auth {
  username = "<KEY_ID>"
  password = "<KEY_SECRET>"
  }

  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

設定が完了すると、メトリクスエクスプローラーに ClickHouse 関連のメトリクスが表示されるようになります。

インスタンスラベルが正しく設定されるようにするには、honor_labels 構成パラメータを true に設定する必要がある点に注意してください。

Datadog とのインテグレーション

Datadog の Agent と OpenMetrics インテグレーションを使用すると、ClickHouse Cloud エンドポイントからメトリクスを収集できます。以下に、この Agent とインテグレーションのシンプルな設定例を示します。ただし、実際には本当に必要なメトリクスだけを選択することをおすすめします。以下の包括的な例では、数千にも及ぶメトリクスとインスタンスの組み合わせがエクスポートされ、Datadog ではそれらがカスタムメトリクスとして扱われますので注意してください。

init_config:

instances:
   - openmetrics_endpoint: 'https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/prometheus?filtered_metrics=true'
     namespace: 'clickhouse'
     metrics:
         - '^ClickHouse.*'
     username: username
     password: password

監視の概要 — ClickHouse Cloud のすべての監視方法を比較
Cloud Console の監視 — 外部ツール不要の組み込みダッシュボード
コミュニティおよびパートナーのインテグレーション — Datadog agent のインテグレーションとコミュニティ提供のソリューション
システムテーブルのクエリ — システムメトリクスに SQL で直接アクセス
ClickHouse Managed Postgres Prometheus エンドポイント — ClickHouse Managed Postgres サービスのメトリクスをスクレイプ