Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

Эта возможность поддерживает интеграцию с 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

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

Имя Расположение Тип
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
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

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

Раскрывающийся список в обозревателе метрик Grafana

Диаграмма в обозревателе метрик Grafana

Grafana Cloud с Alloy

Если вы используете Grafana Cloud, Alloy можно установить, открыв меню Alloy в Grafana и следуя инструкциям на экране:

Grafana Alloy

В результате 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:

Обозреватель метрик Grafana

Обратите внимание: для корректного заполнения метки 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

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