> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

Эта возможность поддерживает интеграцию с [Prometheus](https://prometheus.io/) для мониторинга сервисов ClickHouse Cloud. Доступ к метрикам Prometheus предоставляется через конечную точку [ClickHouse Cloud API](/ru/products/cloud/features/admin-features/api/api-overview), которая позволяет безопасно подключаться и экспортировать метрики в ваш сборщик метрик Prometheus. Эти метрики можно интегрировать с панелями мониторинга, например Grafana и Datadog, для визуализации.

Чтобы начать, [создайте ключ API](/ru/products/cloud/features/admin-features/api/openapi).

Если вам нужна аналогичная конечная точка для сервисов [Managed Postgres](/ru/products/managed-postgres/overview), см. раздел [Managed Postgres конечная точка Prometheus](/ru/products/managed-postgres/monitoring/prometheus).

<div id="prometheus-endpoint-api-to-retrieve-clickhouse-cloud-metrics">
  ## API конечной точки Prometheus для получения метрик из ClickHouse Cloud
</div>

<div id="api-reference">
  ### Справочник по API
</div>

| Метод | Путь                                                                                                                            | Описание                                         |
| ----- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 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 (необязательно) |

<div id="authentication">
  ### Аутентификация
</div>

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

```bash theme={null}
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
```

<div id="sample-response">
  ### Пример ответа
</div>

```response theme={null}
# 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
```

<div id="metric-labels">
  ### Метки метрик
</div>

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

| Метка                     | Описание         |
| ------------------------- | ---------------- |
| clickhouse\_org           | ID организации   |
| clickhouse\_service       | ID сервиса       |
| clickhouse\_service\_name | Название сервиса |

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

| Метка             | Описание                |
| ----------------- | ----------------------- |
| clickpipe\_id     | ID ClickPipe            |
| clickpipe\_name   | Название ClickPipe      |
| clickpipe\_source | Тип источника ClickPipe |

<div id="information-metrics">
  ### Информационные метрики
</div>

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 | Текущее состояние пайпа |

<div id="configuring-prometheus">
  ### Настройка Prometheus
</div>

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

```yaml theme={null}
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`, однако это значение следует задавать в соответствии с предпочтениями пользователя.

<div id="integrating-with-grafana">
  ## Интеграция с Grafana
</div>

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

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

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

<div id="grafana-cloud-with-metrics-endpoint">
  ### Grafana Cloud с конечной точкой метрик
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-grafana-metrics-endpoint.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=7aa1e32cfa3aa0de87b90e719830b760" size="md" alt="Настройка конечной точки метрик в Grafana" border width="1784" height="1048" data-path="images/integrations/prometheus-grafana-metrics-endpoint.png" />

<br />

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-grafana-dropdown.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=74a3f08b76c9737fb2d15051638bbbd8" size="md" alt="Раскрывающийся список в обозревателе метрик Grafana" border width="1238" height="876" data-path="images/integrations/prometheus-grafana-dropdown.png" />

<br />

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-grafana-chart.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=1d969d86f0e38838f852cf975c374330" size="md" alt="Диаграмма в обозревателе метрик Grafana" border width="2236" height="628" data-path="images/integrations/prometheus-grafana-chart.png" />

<div id="grafana-cloud-with-alloy">
  ### Grafana Cloud с Alloy
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-grafana-alloy.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=49860578a7fd7fb16760c45a6e77badc" size="md" alt="Grafana Alloy" border width="1208" height="1118" data-path="images/integrations/prometheus-grafana-alloy.png" />

<br />

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

```yaml theme={null}
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`.

<div id="grafana-self-managed-with-alloy">
  ### Самоуправляемая Grafana с Alloy
</div>

Пользователи самоуправляемой версии Grafana могут найти инструкции по установке агента Alloy [здесь](https://grafana.com/docs/alloy/latest/get-started/install/). Мы исходим из того, что Alloy уже настроен на отправку метрик Prometheus в нужный пункт назначения. Приведённый ниже компонент `prometheus.scrape` заставляет Alloy опрашивать конечную точку ClickHouse Cloud. Мы также предполагаем, что `prometheus.remote_write` принимает собранные метрики. Если `forward_to key` отсутствует, укажите в нём целевой пункт назначения.

```yaml theme={null}
// Компонент 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:

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-grafana-metrics-explorer.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=f30612b1f17054b19a830960e2f28364" size="md" alt="Обозреватель метрик Grafana" border width="2232" height="1146" data-path="images/integrations/prometheus-grafana-metrics-explorer.png" />

<br />

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

<div id="integrating-with-datadog">
  ## Интеграция с Datadog
</div>

Вы можете использовать [агент Datadog](https://docs.datadoghq.com/agent/?tab=Linux) и [интеграцию OpenMetrics](https://docs.datadoghq.com/integrations/openmetrics/) для сбора метрик с конечной точки ClickHouse Cloud. Ниже приведен простой пример конфигурации для этого агента и интеграции. Однако обратите внимание: возможно, стоит выбрать только те метрики, которые для вас наиболее важны. Приведенный ниже универсальный пример будет экспортировать многие тысячи комбинаций метрик и экземпляров, которые Datadog будет считать пользовательскими метриками.

```yaml theme={null}
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
```

<br />

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/amY-JDMREAaO7mx6/images/integrations/prometheus-datadog.png?fit=max&auto=format&n=amY-JDMREAaO7mx6&q=85&s=75024746ebe10e2d1c8106ca8aa9b0ca" size="md" alt="Интеграция Prometheus с Datadog" width="1452" height="762" data-path="images/integrations/prometheus-datadog.png" />

<div id="related">
  ## Похожие страницы
</div>

* [Обзор мониторинга](/ru/products/cloud/features/monitoring/overview) — Сравните все подходы к мониторингу в ClickHouse Cloud
* [Мониторинг в Cloud Console](/ru/products/cloud/features/monitoring/cloud-console) — Встроенные панели мониторинга без необходимости использовать внешние инструменты
* [Интеграции с сообществом и партнёрами](/ru/products/cloud/features/monitoring/integrations) — Интеграция с агентом Datadog и решения от сообщества
* [Запросы к системным таблицам](/ru/products/cloud/features/monitoring/system-tables) — Прямой доступ к системным метрикам через SQL
* [Managed Postgres конечная точка Prometheus](/ru/products/managed-postgres/monitoring/prometheus) — Собирайте метрики из сервисов Managed Postgres