Перейти к основному содержанию
Перейти к основному содержанию

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

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

Для начала работы создайте API-ключ.

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

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

МетодПутьОписание
GEThttps://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true | false]Возвращает метрики для конкретного сервиса
GEThttps://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true | false]Возвращает метрики для всех сервисов в организации

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

ИмяРасположениеТип
Organization IDАдрес endpoint’аUUID
Service IDАдрес endpoint’аUUID (необязательный)
filtered_metricsПараметр строки запросаboolean (необязательный)

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

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

Имя пользователя: <KEY_ID>
Пароль: <KEY_SECRET>
Пример запроса
export KEY_SECRET=<key_secret>
export KEY_ID=<key_id>
export ORG_ID=<org_id>

# Для всех сервисов в $ORG_ID \{#for-all-services-in-org_id}
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# Только для одного сервиса \{#for-a-single-service-only}
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 \{#help-clickhouse_serviceinfo-information-about-service-including-cluster-status-and-clickhouse-version}
# TYPE ClickHouse_ServiceInfo untyped \{#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. Не учитывает подзапросы. \{#help-clickhouseprofileevents_query-number-of-queries-to-be-interpreted-and-potentially-executed-does-not-include-queries-that-failed-to-parse-or-were-rejected-due-to-ast-size-limits-quota-limits-or-limits-on-the-number-of-simultaneously-running-queries-may-include-internal-queries-initiated-by-clickhouse-itself-does-not-count-subqueries}
# TYPE ClickHouseProfileEvents_Query counter \{#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 Подсчёт запросов со всеми подзапросами \{#help-clickhouseprofileevents_querieswithsubqueries-count-queries-with-all-subqueries}
# TYPE ClickHouseProfileEvents_QueriesWithSubqueries counter \{#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-запросов со всеми подзапросами \{#help-clickhouseprofileevents_selectquerieswithsubqueries-count-select-queries-with-all-subqueries}
# TYPE ClickHouseProfileEvents_SelectQueriesWithSubqueries counter \{#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 Количество открытых файлов. \{#help-clickhouseprofileevents_fileopen-number-of-files-opened}
# TYPE ClickHouseProfileEvents_FileOpen counter \{#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'. \{#help-clickhouseprofileevents_seek-number-of-times-the-lseek-function-was-called}
# TYPE ClickHouseProfileEvents_Seek counter \{#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 \{#help-clickpipes_info-always-equal-to-1-label-clickpipe_state-contains-the-current-state-of-the-pipe-stoppedprovisioningrunningpausedfailed}
# TYPE ClickPipes_Info gauge \{#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 \{#help-clickpipes_sentevents_total-total-number-of-records-sent-to-clickhouse}
# TYPE ClickPipes_SentEvents_Total counter \{#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. \{#help-clickpipes_sentbytescompressed_total-total-compressed-bytes-sent-to-clickhouse}
# TYPE ClickPipes_SentBytesCompressed_Total counter \{#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 Общее количество несжатых байтов, полученных из источника. \{#help-clickpipes_fetchedbytes_total-total-uncompressed-bytes-fetched-from-the-source}
# TYPE ClickPipes_FetchedBytes_Total counter \{#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 Общее количество ошибок при приёме данных. \{#help-clickpipes_errors_total-total-errors-ingesting-data}
# TYPE ClickPipes_Errors_Total counter \{#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. \{#help-clickpipes_sentbytes_total-total-uncompressed-bytes-sent-to-clickhouse}
# TYPE ClickPipes_SentBytes_Total counter \{#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 \{#help-clickpipes_fetchedbytescompressed_total-total-compressed-bytes-fetched-from-the-source-if-data-is-uncompressed-at-the-source-this-will-equal-clickpipes_fetchedbytes_total}
# TYPE ClickPipes_FetchedBytesCompressed_Total counter \{#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 Общее количество записей, полученных из источника. \{#help-clickpipes_fetchedevents_total-total-number-of-records-fetched-from-the-source}
# TYPE ClickPipes_FetchedEvents_Total counter \{#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",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Демонстрационный пайплайн Confluent",clickpipe_source="confluent"} 5535376

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

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

МеткаОписание
clickhouse_orgИдентификатор организации
clickhouse_serviceИдентификатор сервиса
clickhouse_service_nameИмя сервиса

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

МеткаОписание
clickpipe_idИдентификатор ClickPipe
clickpipe_nameИмя ClickPipe
clickpipe_sourceТип источника ClickPipe

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

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

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

Запросы на получение метрик не выводят сервис из состояния idle. Если сервис находится в состоянии idle, будет возвращена только метрика ClickHouse_ServiceInfo.

Для ClickPipes существует аналогичная метрика ClickPipes_Info типа gauge, которая помимо Metric Labels содержит следующие метки:

МеткаОписание
clickpipe_stateТекущее состояние конвейера

Настройка Prometheus​

Сервер Prometheus собирает метрики с настроенных таргетов с заданным интервалом. Ниже приведён пример конфигурации сервера Prometheus для использования endpoint'а 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

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

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

Существует два основных способа интеграции с Grafana:

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

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

Grafana Cloud с endpointом метрик​

  • Войдите в учетную запись Grafana Cloud
  • Добавьте новое подключение, выбрав Metrics Endpoint
  • Настройте Scrape URL так, чтобы он указывал на endpoint Prometheus, и используйте базовую аутентификацию (basic auth) с ключом API и секретом для настройки подключения
  • Протестируйте подключение, чтобы убедиться, что оно успешно устанавливается
Настройка Grafana Metrics Endpoint

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

Выпадающий список Grafana Metrics Explorer

График в Grafana Metrics Explorer

Grafana Cloud с Alloy​

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

Grafana Alloy

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

Ниже приведён пример конфигурации Alloy с компонентом prometheus.scrape для сбора метрик с ClickHouse Cloud Endpoint, а также автоматически настроенным компонентом prometheus.remote_write. Обратите внимание, что конфигурационный компонент basic_auth содержит идентификатор и секрет нашего Cloud API-ключа в качестве имени пользователя и пароля соответственно.

prometheus.scrape "clickhouse_cloud" {
  // Сбор метрик с адреса прослушивания по умолчанию.
  targets = [{
        __address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=true",
// например: https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/prometheus?filtered_metrics=true
  }]

  honor_labels = true

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

  forward_to = [prometheus.remote_write.metrics_service.receiver]
  // перенаправить в metrics_service ниже
}

prometheus.remote_write "metrics_service" {
  endpoint {
        url = "https://prometheus-prod-10-prod-us-central-0.grafana.net/api/prom/push"
        basic_auth {
          username = "<Grafana API username>"
          password = "<grafana API token>"
    }
  }
}

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

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

Пользователи, развернувшие Grafana самостоятельно, могут найти инструкции по установке агента Alloy здесь. Мы предполагаем, что Alloy настроен на отправку метрик Prometheus в нужное целевое назначение. Компонент prometheus.scrape ниже настраивает Alloy на опрос конечной точки ClickHouse Cloud Endpoint. Мы предполагаем, что prometheus.remote_write получает собранные метрики. При необходимости измените значение ключа forward_to на нужное целевое назначение.

prometheus.scrape "clickhouse_cloud" {
  // Сбор метрик с адреса прослушивания по умолчанию.
  targets = [{
        __address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=true",
// например: https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/prometheus?filtered_metrics=true
  }]

  honor_labels = true

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

  forward_to = [prometheus.remote_write.metrics_service.receiver]
  // Перенаправление в metrics_service. Измените на нужный получатель
}

После завершения настройки вы должны увидеть метрики, связанные с ClickHouse, в обозревателе метрик:

Grafana Metrics Explorer

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

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

Вы можете использовать агент Datadog Agent и интеграцию OpenMetrics для сбора метрик с endpoint 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