Интеграция с Prometheus

Эта возможность поддерживает интеграцию с Prometheus для мониторинга сервисов ClickHouse Cloud. Доступ к метрикам Prometheus предоставляется через конечную точку ClickHouse Cloud API, которая позволяет безопасно подключаться и экспортировать метрики в ваш сборщик метрик Prometheus. Эти метрики можно интегрировать с панелями мониторинга, например Grafana и Datadog, для визуализации. Метрики ClickPipes, подключённых к сервису, включаются вместе с метриками ClickHouse этого сервиса. Чтобы начать, создайте ключ API. Если вам нужна аналогичная конечная точка для сервисов ClickHouse Managed Postgres, см. раздел ClickHouse Managed Postgres конечная точка Prometheus.

API конечной точки Prometheus для получения метрик из ClickHouse Cloud

Справочник по 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

Конечная точка метрик для всей организации (GET /v1/organizations/{organizationId}/prometheus) устарела в пользу автоматического обнаружения сервисов. Существующие организации могут продолжать её использовать; вновь созданные организации вместо неё используют конечную точку обнаружения. Если вам нужен доступ к этой конечной точке, обратитесь в службу поддержки ClickHouse.

Параметры запроса

Имя	Расположение	Тип
ID организации	Конечная точка	uuid
ID сервиса	Конечная точка	uuid (необязательно)
filtered_metrics	Параметр запроса	boolean (необязательно)

Полные схемы запросов и ответов для этих конечных точек доступны в справочнике Cloud API.

Аутентификация

Используйте API-ключ ClickHouse Cloud для базовой аутентификации:

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

Метки метрик

Все метрики содержат следующие метки:

Метка	Описание
clickhouse_org	ID организации
clickhouse_service	ID сервиса
clickhouse_service_name	Название сервиса

Для ClickPipes метрики также содержат следующие метки:

Метка	Описание
clickpipe_id	ID ClickPipe
clickpipe_name	Название ClickPipe
clickpipe_source	Тип источника ClickPipe

Информационные метрики

ClickHouse Cloud предоставляет специальную метрику ClickHouse_ServiceInfo — это gauge, который всегда имеет значение 1. Эта метрика содержит все метки метрик, а также следующие метки:

Label	Description
clickhouse_cluster_status	Статус сервиса. Может принимать одно из следующих значений: [`awaking`	`running`	`degraded`	`idle`	`stopped`]
clickhouse_version	Версия ClickHouse server, на которой работает сервис
scrape	Указывает статус последнего сбора метрик. Может быть `full` или `partial`
full	Указывает, что при последнем сборе метрик ошибок не было
partial	Указывает, что при последнем сборе метрик возникли ошибки и была возвращена только метрика `ClickHouse_ServiceInfo`.

Запросы на получение метрик не выводят сервис из состояния бездействия. Если сервис находится в состоянии idle, будет возвращена только метрика ClickHouse_ServiceInfo. Для ClickPipes есть аналогичная метрика ClickPipes_Info типа gauge, которая, помимо меток метрик, содержит следующие метки:

Label	Description
clickpipe_state	Текущее состояние пайпа

Настройка Prometheus

Сервер Prometheus собирает метрики с настроенных целей с заданной периодичностью. Ниже приведен пример конфигурации, в которой сервер Prometheus использует конечную точку Prometheus ClickHouse Cloud:

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 должен быть установлен в true, чтобы метка instance заполнялась корректно. Кроме того, в приведённом выше примере параметр filtered_metrics установлен в true, однако это значение следует задавать в соответствии с предпочтениями пользователя.

Автоматическое обнаружение сервисов

Конечная точка обнаружения возвращает по одной цели сбора метрик для каждого сервиса в вашей организации в формате Prometheus обнаружение сервисов по HTTP (http_sd). Prometheus обновляет список целей при каждом опросе обнаружения и собирает метрики с каждой обнаруженной цели, поэтому вновь созданные сервисы добавляются автоматически, а удалённые исключаются из списка целей. Включаются только сервисы, для просмотра которых авторизован ваш ключ API; сервисы, находящиеся в процессе удаления или уже удалённые, не включаются. Чтобы использовать её, укажите конечную точку обнаружения для задачи http_sd_configs:

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 аутентифицирует запросы обнаружения, а блок в задаче scrape — сбор метрик для каждого сервиса. Как и при статической конфигурации, укажите honor_labels: true, чтобы метка instance заполнялась корректно. Пример ответа обнаружения:

[
  {
    "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. Чтобы обнаружить цели, собирающие полный набор метрик, добавьте ?filtered_metrics=false к URL обнаружения. Полная спецификация конечной точки доступна в справочнике Cloud API.

Интеграция с Grafana

У пользователей есть два основных способа интеграции с Grafana:

Конечная точка метрик – Преимущество этого подхода в том, что он не требует никаких дополнительных компонентов или инфраструктуры. Этот вариант доступен только в Grafana Cloud и требует лишь URL конечной точки Prometheus ClickHouse Cloud и учетные данные.
Grafana Alloy - Grafana Alloy — это независимый от вендора дистрибутив OpenTelemetry (OTel) Collector, пришедший на смену Grafana Agent. Его можно использовать для сбора метрик, развернуть в собственной инфраструктуре, и он совместим с любой конечной точкой Prometheus.

Ниже приведены инструкции по использованию этих вариантов с акцентом на детали, относящиеся именно к конечной точке Prometheus ClickHouse Cloud.

Grafana Cloud с конечной точкой метрик

Войдите в свою учетную запись Grafana Cloud
Добавьте новое подключение, выбрав конечную точку метрик
Настройте URL сбора так, чтобы он указывал на конечную точку Prometheus, и используйте базовую аутентификацию для настройки подключения с помощью API key/secret
Проверьте подключение, чтобы убедиться, что соединение устанавливается

После настройки вы увидите метрики в раскрывающемся списке, где их можно выбрать для настройки панелей мониторинга:

Grafana Cloud с Alloy

Если вы используете Grafana Cloud, Alloy можно установить, открыв меню Alloy в Grafana и следуя инструкциям на экране:
В результате Alloy будет настроен с компонентом prometheus.remote_write для отправки данных в конечную точку Grafana Cloud с токеном аутентификации. После этого пользователям останется только изменить конфигурацию Alloy (в Linux она находится в /etc/alloy/config.alloy), добавив скрейпер для конечной точки Prometheus ClickHouse Cloud. Ниже показан пример конфигурации Alloy с компонентом prometheus.scrape для сбора метрик из конечной точки ClickHouse Cloud, а также автоматически настроенным компонентом prometheus.remote_write. Обратите внимание, что компонент конфигурации basic_auth содержит идентификатор и секрет нашего API-ключа Cloud в качестве имени пользователя и пароля соответственно.

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>"
  }
  }
}

Обратите внимание: чтобы метка instance заполнялась корректно, параметр конфигурации honor_labels должен быть установлен в true.

Самоуправляемая Grafana с Alloy

Пользователи самоуправляемой версии 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:
Обратите внимание: для корректного заполнения метки instance параметру конфигурации honor_labels нужно задать значение true.

Интеграция с Datadog

Вы можете использовать агент Datadog и интеграцию OpenMetrics для сбора метрик с конечной точки ClickHouse Cloud. Ниже приведен простой пример конфигурации для этого агента и интеграции. Однако обратите внимание: возможно, стоит выбрать только те метрики, которые для вас наиболее важны. Приведенный ниже универсальный пример будет экспортировать многие тысячи комбинаций метрик и экземпляров, которые 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 и решения сообщества
Запросы к системным таблицам — Прямой доступ к системным метрикам через SQL
ClickHouse Managed Postgres конечная точка Prometheus — Собирайте метрики из сервисов ClickHouse Managed Postgres

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

API конечной точки Prometheus для получения метрик из ClickHouse Cloud

Справочник по API

Аутентификация

Пример ответа

Метки метрик

Информационные метрики

Настройка Prometheus

Автоматическое обнаружение сервисов

Интеграция с Grafana

Grafana Cloud с конечной точкой метрик

Grafana Cloud с Alloy

Самоуправляемая Grafana с Alloy

Интеграция с Datadog

​API конечной точки Prometheus для получения метрик из ClickHouse Cloud

​Справочник по API

​Аутентификация

​Пример ответа

​Метки метрик

​Информационные метрики

​Настройка Prometheus

​Автоматическое обнаружение сервисов

​Интеграция с Grafana

​Grafana Cloud с конечной точкой метрик

​Grafana Cloud с Alloy

​Самоуправляемая Grafana с Alloy

​Интеграция с Datadog

​Связанные страницы

API конечной точки Prometheus для получения метрик из ClickHouse Cloud

Справочник по API

Аутентификация

Пример ответа

Метки метрик

Информационные метрики

Настройка Prometheus

Автоматическое обнаружение сервисов

Интеграция с Grafana

Grafana Cloud с конечной точкой метрик

Grafana Cloud с Alloy

Самоуправляемая Grafana с Alloy

Интеграция с Datadog

Связанные страницы