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

Экспорт метрик ClickHouse в Prometheus

Эта возможность поддерживает интеграцию с Prometheus для мониторинга сервисов ClickHouse Cloud. Доступ к метрикам Prometheus предоставляется через конечную точку ClickHouse Cloud API, которая позволяет безопасно подключаться и экспортировать метрики в ваш сборщик метрик Prometheus. Эти метрики можно интегрировать с панелями мониторинга, например Grafana и Datadog, для визуализации.

Чтобы начать, создайте ключ API.

Если вам нужна аналогичная конечная точка для сервисов Managed Postgres, см. раздел 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]	Возвращает метрики для всех сервисов организации

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

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

​

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

Используйте 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, однако это значение следует задавать в соответствии с предпочтениями пользователя.

​

Интеграция с 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 заставляет Alloy собирать метрики с конечной точки Prometheus ClickHouse Cloud.
  // Скорректируйте ключ forward_to в соответствии с вашим приёмником remote_write, если он отличается.
  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
• Managed Postgres конечная точка Prometheus — Собирайте метрики из сервисов Managed Postgres