`](/ru/concepts/features/interfaces/http). |
| `info` | true | Публикует Gauge `ClickHouse_Info` с метками идентификации сервера (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`). |
| `metrics` | true | Публикует метрики из [`system.metrics`](/ru/reference/system-tables/metrics). |
| `asynchronous_metrics` | true | Публикует метрики из [`system.asynchronous_metrics`](/ru/reference/system-tables/asynchronous_metrics). |
| `events` | true | Публикует метрики из [`system.events`](/ru/reference/system-tables/events). |
| `errors` | true | Публикует количество ошибок из [`system.errors`](/ru/reference/system-tables/errors). |
| `histograms` | true | Публикует метрики из [`system.histogram_metrics`](/ru/reference/system-tables/histogram_metrics). |
| `dimensional_metrics` | true | Публикует метрики из [`system.dimensional_metrics`](/ru/reference/system-tables/dimensional_metrics). |
| `labels` | none | Постоянные метки, добавляемые к каждой публикуемой метрике. Каждый дочерний элемент определяет одну метку: имя элемента является именем метки (которое должно соответствовать `[a-zA-Z_][a-zA-Z0-9_]*`), а значение элемента — значением метки. Значения меток поддерживают стандартные подстановки конфигурации, такие как атрибут `from_env`. Имя метки отклоняется, если оно начинается с `__` (зарезервировано Prometheus) или конфликтует с меткой, которую эта конечная точка уже записывает для одного из включенных разделов. Таким образом, набор зарезервированных имен определяется активным набором экспортируемых данных конечной точки: `le`, когда включен `histograms`; метки `ClickHouse_Info` (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`), когда включен `info`; а также любая метка, используемая публикуемым семейством метрик-гистограмм или размерных метрик (например, `group`, `direction` или `operation_type`), когда включены `histograms` или `dimensional_metrics`. Поскольку это зависит от того, что фактически публикует конечная точка, имя может быть допустимым для одной конечной точки, но отклоняться для другой. |
Проверьте конечную точку:
```bash theme={null}
curl http://127.0.0.1:9363/metrics
```
## HTTP API Prometheus и PromQL
ClickHouse реализует HTTP API Prometheus поверх таблицы [`TimeSeries`](/ru/reference/engines/table-engines/integrations/time-series). Один обработчик поддерживает удалённую запись, удалённое чтение, мгновенные запросы PromQL и запросы PromQL по диапазону.
### Предварительные требования
Включите настройку [`allow_experimental_time_series_table`](/ru/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) для пользователя, создающего таблицу и работающего с ней:
```sql theme={null}
SET allow_experimental_time_series_table = 1;
```
Создайте базу данных и таблицу `TimeSeries`:
```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```
Для HTTP-запросов к API включите `allow_experimental_time_series_table` в профиле пользователя API.
### Настройка API Prometheus
Настройте один обработчик с маршрутизацией по префиксу на основном HTTP-порту ClickHouse:
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` сохраняет встроенные обработчики для таких конечных точек, как `/ping`, а также для SQL-запросов. Указанный выше префикс предоставляет доступ к этим конечным точкам через один обработчик:
| Конечная точка | Назначение |
| -------------------------------- | --------------------------- |
| `/prometheus/api/v1/write` | удалённая запись Prometheus |
| `/prometheus/api/v1/read` | удалённое чтение Prometheus |
| `/prometheus/api/v1/query` | мгновенные запросы PromQL |
| `/prometheus/api/v1/query_range` | запросы PromQL по диапазону |
| `/prometheus/api/v1/series` | Метаданные серии |
| `/prometheus/api/v1/metadata` | Метаданные семейства метрик |
В примере в обработчике не указаны `database` и `table`. В каждом запросе необходимо передавать параметр запроса `table`. Также можно передать `database`, использовать полное имя таблицы, например `prometheus.metrics`, или не указывать базу данных, чтобы использовать `default`. Это позволяет одному обработчику обслуживать несколько таблиц `TimeSeries`.
Чтобы использовать одну фиксированную таблицу для всех запросов, настройте её в обработчике:
```xml theme={null}
prometheus_api_v1
prometheus
```
Таблицу, заданную в обработчике, нельзя переопределить параметрами запроса.
Настройки маршрутизации и обработчика:
| Имя | По умолчанию | Описание |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url_prefix` | none | Фильтр правила, соответствующий всем путям запросов, начинающимся с заданного префикса. |
| `table` | none | Имя таблицы `TimeSeries`. Если не указано, запрос должен содержать параметр запроса `table`. Указанное имя может включать имя базы данных. |
| `database` | none | База данных, содержащая таблицу. Запрос может передать её в параметре запроса. Если не указано, ClickHouse использует базу данных из полного имени `table` или базу данных `default`. |
### Приём метрик через удалённую запись
ClickHouse поддерживает [протокол удалённой записи Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). Настройте Prometheus на запись в обработчик:
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
basic_auth:
username: default
password:
```
Prometheus отправляет образцы в таблицу `prometheus.metrics`.
Чтобы объединять данные из множества одновременных запросов удалённой записи в меньшее число частей, включите [асинхронные вставки](/ru/reference/settings/session-settings/async-insert#async_insert), добавив настройку `async_insert` в URL (или включив её в профиле пользователя):
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1
```
ClickHouse подтверждает асинхронный запрос удалённой записи только после сброса данных на диск во все внутренние таблицы таблицы `TimeSeries`, независимо от настройки [`wait_for_async_insert`](/ru/reference/settings/session-settings/wait-for#wait_for_async_insert): согласно протоколу удалённой записи подтверждённая запись считается надёжно сохранённой. Если сброс на диск завершается ошибкой, запрос возвращает ошибку, и Prometheus повторяет попытку.
### Запрос с PromQL
Используйте конечную точку мгновенного запроса, чтобы вычислить выражение PromQL на определённый момент времени:
```bash theme={null}
curl --user default: --get \
"https://clickhouse.example.com:8443/prometheus/api/v1/query" \
--data-urlencode "query=rate(http_requests_total[5m])" \
--data-urlencode "database=prometheus" \
--data-urlencode "table=metrics"
```
Используйте конечную точку range-запроса, чтобы вычислить выражение за указанный период:
```bash theme={null}
curl --user default: --get \
"https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
--data-urlencode "query=rate(http_requests_total[5m])" \
--data-urlencode "start=2026-08-15T12:00:00Z" \
--data-urlencode "end=2026-08-15T13:00:00Z" \
--data-urlencode "step=60s" \
--data-urlencode "database=prometheus" \
--data-urlencode "table=metrics"
```
Список функций и операторов агрегации, поддерживаемых HTTP API, диалектом `promql` и табличными функциями, см. в разделе [Поддерживаемые возможности PromQL](/ru/reference/functions/table-functions/prometheusQueryRange#supported-promql-features).
#### Grafana
Настройте источник данных Prometheus, указав базовый URL без `/api/v1` в конце:
```yaml theme={null}
apiVersion: 1
datasources:
- name: ClickHouse Prometheus
type: prometheus
access: proxy
url: https://clickhouse.example.com:8443/prometheus
basicAuth: true
basicAuthUser: default
jsonData:
httpMethod: GET
customQueryParameters: database=prometheus&table=metrics
secureJsonData:
basicAuthPassword:
```
Grafana добавляет `/api/v1/query` или `/api/v1/query_range` к этому базовому URL, а также `customQueryParameters` к каждому запросу.
Реализованы только конечные точки запросов `/api/v1/query` и `/api/v1/query_range`, а также конечные точки метаданных `/api/v1/series`, `/api/v1/labels` и `/api/v1/metadata`. Для `/api/v1/series` требуется как минимум один селектор серий `match[]`; она поддерживает необязательные параметры `start`, `end` и `limit` и возвращает объединение серий, соответствующих каждому селектору. `/api/v1/labels` принимает те же параметры, при этом `match[]` необязателен, и возвращает отсортированные имена меток соответствующих серий (или всех серий, если селекторы не указаны). Конечная точка значений меток (`/api/v1/label//values`), используемая источником данных Prometheus в Grafana для просмотра меток, переменных шаблона и автодополнения в конструкторе запросов, не реализована и возвращает ошибку. Вводите выражения PromQL в режиме кода, а не в конструкторе запросов.
#### Точки входа SQL
ClickHouse использует один и тот же конвертер PromQL для HTTP API, диалекта `promql`, а также табличных функций [`prometheusQuery`](/ru/reference/functions/table-functions/prometheusQuery) и [`prometheusQueryRange`](/ru/reference/functions/table-functions/prometheusQueryRange).
Выполните PromQL напрямую с помощью `clickhouse-client`:
```bash theme={null}
clickhouse-client \
--dialect promql \
--promql_database prometheus \
--promql_table metrics \
--query 'rate(http_requests_total[5m])'
```
Используйте табличные функции для встраивания PromQL в SQL-запрос:
```sql theme={null}
SELECT *
FROM prometheusQuery(
prometheus.metrics,
'rate(http_requests_total[5m])',
now()
);
```
### Запрос метаданных метрик
Конечная точка `/prometheus/api/v1/metadata` возвращает метаданные метрик, хранящиеся в целевой таблице `Metrics` таблицы `TimeSeries`: тип, текст справки и единицу измерения каждого семейства метрик. Она поддерживает следующие параметры Prometheus в строке запроса URL:
| Параметр | Описание |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metric` | Возвращает метаданные только для указанного семейства метрик. |
| `limit` | Ограничивает число возвращаемых семейств метрик. Отрицательное значение означает отсутствие ограничения; при нулевом значении семейства метрик не возвращаются. |
| `limit_per_metric` | Ограничивает число объектов метаданных, возвращаемых для каждого семейства метрик. Нулевые и отрицательные значения означают отсутствие ограничения. |
Целевая таблица `Metrics` по умолчанию — это `ReplacingMergeTree`, упорядоченная по имени семейства метрик: в ней сохраняется последняя записанная запись метаданных для каждого семейства метрик. Несколько записей для одного семейства возвращаются только до тех пор, пока они хранятся в целевой таблице: до слияния её частей или если таблица определена с движком, который их сохраняет.
```bash theme={null}
curl --user default: --get \
"https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
--data-urlencode "metric=http_requests_total" \
--data-urlencode "database=prometheus" \
--data-urlencode "table=metrics"
```
### Чтение метрик через удалённое чтение
ClickHouse поддерживает [протокол Prometheus удалённого чтения](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) по адресу `/prometheus/api/v1/read`.
Настройте сервер Prometheus для чтения из той же таблицы `TimeSeries`:
```yaml theme={null}
remote_read:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
basic_auth:
username: default
password:
```