TimeSeries Engine и Prometheus remote write/read

ClickHouse всё чаще используется как long-term storage для Prometheus-метрик: высокая скорость записи, отличное сжатие временных рядов, мощный SQL для аналитики. Существуют два подхода — нативный Prometheus endpoint (GA) для мониторинга самого ClickHouse и экспериментальный TimeSeries engine для хранения внешних метрик.

Нативный Prometheus Endpoint (GA)

ClickHouse имеет встроенную поддержку Prometheus-формата на порту 9363. Это GA-функция, не требующая отдельного exporter-сайдкара.

Конфигурация в prometheus.xml (или в config.xml секция <prometheus>):

<prometheus>
  <port>9363</port>
  <handlers>
    <metrics_handler>
      <url>/metrics</url>
      <handler>
        <type>expose_metrics</type>
      </handler>
    </metrics_handler>
  </handlers>
</prometheus>

После этого Prometheus может скрейпить метрики ClickHouse напрямую:

# prometheus.yml (фрагмент)
scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['clickhouse-host:9363']

TimeSeries Engine (EXPERIMENTAL)

ENGINE = TimeSeries позволяет использовать ClickHouse как backend для Prometheus remote_write / remote_read. Движок автоматически создаёт внутренние таблицы для данных, тегов и метрик.

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

CREATE TABLE metrics_ts ENGINE = TimeSeries;
-- ClickHouse автоматически создаёт внутренние таблицы:
-- metrics_ts_data -- сами данные (timestamp, value)
-- metrics_ts_tags -- теги метрик (label_name, label_value)
-- metrics_ts_metrics -- имена метрик

Конфигурация remote_write и remote_read в prometheus.xml:

<prometheus>
  <port>9363</port>
  <handlers>
    <write_handler>
      <url>/write</url>
      <handler>
        <type>remote_write</type>
        <table>default.metrics_ts</table>
      </handler>
    </write_handler>
    <read_handler>
      <url>/read</url>
      <handler>
        <type>remote_read</type>
        <table>default.metrics_ts</table>
      </handler>
    </read_handler>
    <metrics_handler>
      <url>/metrics</url>
      <handler>
        <type>expose_metrics</type>
      </handler>
    </metrics_handler>
  </handlers>
</prometheus>

Конфигурация Prometheus для remote storage:

# prometheus.yml -- remote storage конфигурация
remote_write:
  - url: "http://clickhouse-host:9363/write"

remote_read:
  - url: "http://clickhouse-host:9363/read"

Архитектура: Prometheus + ClickHouse

PromQL dialect в ClickHouse SQL

При использовании TimeSeries engine ClickHouse поддерживает PromQL-синтаксис запросов напрямую:

-- Включить PromQL dialect
SET dialect = 'promql';
SET promql_table_name = 'metrics_ts';

-- PromQL-запрос напрямую в ClickHouse
rate(http_requests_total[5m])

Это позволяет использовать существующие PromQL-запросы без переписывания на SQL.

MergeTree-альтернатива (production-рекомендация)

Для production long-term storage рекомендуется ручная схема на MergeTree. Это GA, обеспечивает полный контроль над схемой, сжатием и lifecycle.

-- Production-рекомендуемый подход: ручная MergeTree-схема
CREATE TABLE prometheus_metrics (
    metric_name   LowCardinality(String),
    labels        Map(String, String),
    timestamp     DateTime64(3)  CODEC(Delta, ZSTD(1)),
    value         Float64        CODEC(Gorilla, LZ4)
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)
ORDER BY (metric_name, labels, timestamp)
TTL timestamp + INTERVAL 90 DAY;

Преимущества MergeTree-подхода перед TimeSeries engine:

Ключевые выводы

1. Нативный Prometheus endpoint на порту 9363 — GA, рекомендованный подход для мониторинга ClickHouse. Экспортеры-сайдкары не нужны.
2. ENGINE = TimeSeries является экспериментальным в ClickHouse 26.3 LTS. API может измениться, не рекомендуется для production.
3. Конфигурация remote_write/remote_read в prometheus.xml через XML-хендлеры <type>remote_write</type> и <type>remote_read</type> на порту 9363.
4. PromQL dialect: SET dialect = 'promql'; SET promql_table_name = 'ts_table' позволяет запрашивать TimeSeries engine через PromQL.
5. Для production long-term Prometheus storage используйте MergeTree с ручной схемой (GA, полный контроль над codec chains и TTL).