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

> Поддержка HTTP API Prometheus в ClickHouse: удалённая запись, удалённое чтение и запросы PromQL поверх таблицы TimeSeries.

# HTTP API Prometheus и PromQL

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Закрытая предварительная версия'}
        </div>;
};

<PrivatePreviewBadge />

ClickHouse реализует HTTP API Prometheus поверх таблицы [`TimeSeries`](/ru/reference/engines/table-engines/integrations/time-series). Один обработчик поддерживает удалённую запись, удалённое чтение, мгновенные запросы PromQL и запросы PromQL по диапазону.

Чтобы предоставить собственные метрики ClickHouse для сбора сервером Prometheus, см. [конечную точку метрик Prometheus](/ru/concepts/features/interfaces/prometheus-metrics).

<h2 id="prerequisites">
  Предварительные требования
</h2>

Шаги настройки различаются для ClickHouse Cloud и самоуправляемого ClickHouse. Следуйте разделу, соответствующему вашему развертыванию.

<h3 id="prerequisites-cloud">
  ClickHouse Cloud
</h3>

<Note>
  Поддержка PromQL в ClickHouse Cloud доступна в режиме закрытой предварительной версии. В сервисах, участвующих в закрытой предварительной версии, параметр `enable_time_series_table` и конечные точки Prometheus API уже настроены. В остальных сервисах ClickHouse Cloud такой конфигурации нет, и включить эту возможность самостоятельно в подобном сервисе невозможно. Оператор `SET enable_time_series_table` и конфигурация `http_handlers`, описанные в следующих разделах, относятся к самоуправляемым развертываниям.
</Note>

Если ваш сервис участвует в закрытой предварительной версии, переходите к разделу [Создание таблицы TimeSeries](#create-a-timeseries-table). Такой сервис обслуживает пути конечных точек, перечисленные в [таблице конечных точек](#configure-prometheus-api).

<h3 id="enable-the-timeseries-setting">
  Самоуправляемый вариант: включение настройки TimeSeries
</h3>

Включите настройку `enable_time_series_table` для пользователя, создающего таблицу и работающего с ней:

```sql theme={null}
SET enable_time_series_table = 1;
```

Для HTTP-запросов к API включите `enable_time_series_table` в профиле пользователя API.

<h3 id="configure-prometheus-api">
  Самоуправляемый вариант: настройка конечных точек API Prometheus
</h3>

Настройте один обработчик с маршрутизацией по префиксу на основном HTTP-порту ClickHouse:

```xml theme={null}
<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>
```

`<defaults/>` сохраняет встроенные обработчики для таких конечных точек, как `/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/format_query` | форматирование выражений PromQL |
| `/prometheus/api/v1/series` | Метаданные серии |
| `/prometheus/api/v1/metadata` | Метаданные семейства метрик |

В примере в обработчике не указаны `database` и `table`. В каждом запросе необходимо передавать параметр запроса `table` (кроме `/format_query`, который только разбирает переданное выражение PromQL и не требует таблицы). Также можно передать `database`, использовать полное имя таблицы, например `prometheus.metrics`, или не указывать базу данных, чтобы использовать `default`. Это позволяет одному обработчику обслуживать несколько таблиц `TimeSeries`.

Чтобы использовать одну фиксированную таблицу для всех запросов, настройте её в обработчике:

```xml theme={null}
<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>
```

Таблицу, заданную в обработчике, нельзя переопределить параметрами запроса.

Настройки маршрутизации и обработчика:

| Имя | По умолчанию | Описание |
| - | - | - |
| `url_prefix` | none | Фильтр правила, соответствующий всем путям запросов, начинающимся с заданного префикса. |
| `table` | none | Имя таблицы `TimeSeries`. Если не указано, запрос должен содержать параметр запроса `table`. Указанное имя может включать имя базы данных. |
| `database` | none | База данных, содержащая таблицу. Запрос может передать её в параметре запроса. Если не указано, ClickHouse использует базу данных из полного имени `table` или базу данных `default`. |

<h3 id="create-a-timeseries-table">
  Создание таблицы TimeSeries
</h3>

Создайте базу данных и таблицу `TimeSeries`:

```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```

<h2 id="remote-write">
  Приём метрик через удалённую запись
</h2>

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: <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 повторяет попытку.

<h2 id="promql-query-support">
  Запрос с PromQL
</h2>

Используйте конечную точку мгновенного запроса, чтобы вычислить выражение PromQL на определённый момент времени:

```bash theme={null}
curl --user default:<password> --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:<password> --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"
```

Конечные точки запросов также принимают параметры в теле формы. Без `--get` curl отправляет параметры в формате `application/x-www-form-urlencoded` методом `POST`:

```bash theme={null}
curl --user default:<password> \
  "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"
```

Используйте конечную точку format-запроса, чтобы разобрать и отформатировать выражение PromQL без его вычисления:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"
```

Выражение возвращается сериализованным из разобранного запроса: пробельные символы нормализованы, комментарии удалены, избыточные скобки убраны, а длительности преобразованы в число секунд: `sum by (job) (http_requests_total{code="200"}) / 2`. Эта конечная точка не вычисляет выражение, поэтому ей не нужны параметры `database` и `table`.

Список функций и операторов агрегации, поддерживаемых HTTP API, диалектом `promql` и табличными функциями, см. в разделе [Поддерживаемые возможности PromQL](/ru/reference/functions/table-functions/prometheusQueryRange#supported-promql-features).

<h3 id="grafana">
  Grafana
</h3>

Настройте источник данных 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: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>
```

Grafana добавляет `/api/v1/query` или `/api/v1/query_range` к этому базовому URL, а также `customQueryParameters` к каждому запросу.

При `httpMethod: POST` Grafana передаёт параметры запроса в теле запроса. ClickHouse читает как тело запроса, так и строку запроса URL, поэтому `customQueryParameters` по-прежнему применяется. Используйте `POST` для длинных выражений PromQL, поскольку длина URL ограничена.

<Note>
  Реализованы только конечные точки запросов `/api/v1/query`, `/api/v1/query_range` и `/api/v1/format_query`, а также конечные точки метаданных `/api/v1/series`, `/api/v1/labels`, `/api/v1/label/<name>/values` и `/api/v1/metadata`. Для `/api/v1/series` требуется как минимум один селектор серий `match[]`; она поддерживает необязательные параметры `start`, `end` и `limit` и возвращает объединение серий, соответствующих каждому селектору. `/api/v1/labels` принимает те же параметры, при этом `match[]` необязателен, и возвращает отсортированные имена меток соответствующих серий (или всех серий, если селекторы не указаны). `/api/v1/label/<name>/values` принимает те же параметры, что и `/api/v1/labels`, и возвращает отсортированные значения одной метки, причём в `<name>` может использоваться принятое в Prometheus экранирование `U__...` для имён меток, содержащих символы вне `[a-zA-Z0-9_]`. Этих конечных точек достаточно для всего, что источник данных Prometheus в Grafana использует для просмотра меток, переменных шаблона и автодополнения в конструкторе запросов.
</Note>

<h3 id="sql-entry-points">
  Точки входа SQL
</h3>

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()
);
```

<h2 id="metadata">
  Запрос метаданных метрик
</h2>

Конечная точка `/prometheus/api/v1/metadata` возвращает метаданные метрик, хранящиеся в целевой таблице `Metrics` таблицы `TimeSeries`: тип, текст справки и единицу измерения каждого семейства метрик. Она поддерживает следующие параметры Prometheus в строке запроса URL:

| Параметр | Описание |
| - | - |
| `metric` | Возвращает метаданные только для указанного семейства метрик. |
| `limit` | Ограничивает число возвращаемых семейств метрик. Отрицательное значение означает отсутствие ограничения; при нулевом значении семейства метрик не возвращаются. |
| `limit_per_metric` | Ограничивает число объектов метаданных, возвращаемых для каждого семейства метрик. Нулевые и отрицательные значения означают отсутствие ограничения. |

Целевая таблица `Metrics` по умолчанию — это `ReplacingMergeTree`, упорядоченная по имени семейства метрик: в ней сохраняется последняя записанная запись метаданных для каждого семейства метрик. Несколько записей для одного семейства возвращаются только до тех пор, пока они хранятся в целевой таблице: до слияния её частей или если таблица определена с движком, который их сохраняет.

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

<h2 id="remote-read">
  Чтение метрик через удалённое чтение
</h2>

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: <password>
```