Протоколы Prometheus и PromQL

Настройте выделенный порт, если серверу Prometheus требуется собирать собственные метрики ClickHouse:

<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
    <histograms>true</histograms>
    <dimensional_metrics>true</dimensional_metrics>
</prometheus>

Раздел <prometheus.handlers> можно использовать для создания более расширенных обработчиков на том же порту. Этот раздел похож на <http_handlers>, но работает для протоколов prometheus:

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

Настройки:

Проверьте конечную точку:

curl http://127.0.0.1:9363/metrics

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

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

SET allow_experimental_time_series_table = 1;

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

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

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

Настройте один обработчик с маршрутизацией по префиксу на основном 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-запросов. Указанный выше префикс предоставляет доступ к этим конечным точкам через один обработчик:

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

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

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

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

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

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 на определённый момент времени:

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"

Список функций и операторов агрегации, поддерживаемых HTTP API, диалектом promql и табличными функциями, см. в разделе Поддерживаемые возможности PromQL.

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

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

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:

Целевая таблица 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>