HTTP API Prometheus и PromQL

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

Предварительные требования

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

ClickHouse Cloud

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

Если ваш сервис участвует в закрытой предварительной версии, переходите к разделу Создание таблицы TimeSeries. Такой сервис обслуживает пути конечных точек, перечисленные в таблице конечных точек.

Самоуправляемый вариант: включение настройки TimeSeries

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

SET enable_time_series_table = 1;

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

Самоуправляемый вариант: настройка конечных точек API Prometheus

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

<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. Чтобы использовать одну фиксированную таблицу для всех запросов, настройте её в обработчике:

<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`.

Создание таблицы TimeSeries

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

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

Приём метрик через удалённую запись

ClickHouse поддерживает протокол удалённой записи Prometheus. Настройте Prometheus на запись в обработчик:

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. Чтобы объединять данные из множества одновременных запросов удалённой записи в меньшее число частей, включите асинхронные вставки, добавив настройку async_insert в URL (или включив её в профиле пользователя):

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: согласно протоколу удалённой записи подтверждённая запись считается надёжно сохранённой. Если сброс на диск завершается ошибкой, запрос возвращает ошибку, и Prometheus повторяет попытку.

Запрос с PromQL

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

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-запроса, чтобы вычислить выражение за указанный период:

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:

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 без его вычисления:

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.

Grafana

Настройте источник данных Prometheus, указав базовый URL без /api/v1 в конце:

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 ограничена.

Реализованы только конечные точки запросов /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 использует для просмотра меток, переменных шаблона и автодополнения в конструкторе запросов.

Точки входа SQL

ClickHouse использует один и тот же конвертер PromQL для HTTP API, диалекта promql, а также табличных функций prometheusQuery и prometheusQueryRange. Выполните PromQL напрямую с помощью clickhouse-client:

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

Используйте табличные функции для встраивания PromQL в SQL-запрос:

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, упорядоченная по имени семейства метрик: в ней сохраняется последняя записанная запись метаданных для каждого семейства метрик. Несколько записей для одного семейства возвращаются только до тех пор, пока они хранятся в целевой таблице: до слияния её частей или если таблица определена с движком, который их сохраняет.

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"

Чтение метрик через удалённое чтение

ClickHouse поддерживает протокол Prometheus удалённого чтения по адресу /prometheus/api/v1/read. Настройте сервер Prometheus для чтения из той же таблицы TimeSeries:

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Основы

Основные понятия ClickHouse

Рекомендации

Предварительные требования

ClickHouse Cloud

Самоуправляемый вариант: включение настройки TimeSeries

Самоуправляемый вариант: настройка конечных точек API Prometheus

Создание таблицы TimeSeries

Приём метрик через удалённую запись

Запрос с PromQL

Grafana

Точки входа SQL

Запрос метаданных метрик

Чтение метрик через удалённое чтение

​Предварительные требования

​ClickHouse Cloud

​Самоуправляемый вариант: включение настройки TimeSeries

​Самоуправляемый вариант: настройка конечных точек API Prometheus

​Создание таблицы TimeSeries

​Приём метрик через удалённую запись

​Запрос с PromQL

​Grafana

​Точки входа SQL

​Запрос метаданных метрик

​Чтение метрик через удалённое чтение

Предварительные требования

ClickHouse Cloud

Самоуправляемый вариант: включение настройки TimeSeries

Самоуправляемый вариант: настройка конечных точек API Prometheus

Создание таблицы TimeSeries

Приём метрик через удалённую запись

Запрос с PromQL

Grafana

Точки входа SQL

Запрос метаданных метрик

Чтение метрик через удалённое чтение