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
Включите настройкуenable_time_series_table для пользователя, создающего таблицу и работающего с ней:
enable_time_series_table в профиле пользователя API.
Самоуправляемый вариант: настройка конечных точек API Prometheus
Настройте один обработчик с маршрутизацией по префиксу на основном HTTP-порту ClickHouse:<defaults/> сохраняет встроенные обработчики для таких конечных точек, как /ping, а также для SQL-запросов. Указанный выше префикс предоставляет доступ к этим конечным точкам через один обработчик:
В примере в обработчике не указаны
database и table. В каждом запросе необходимо передавать параметр запроса table (кроме /format_query, который только разбирает переданное выражение PromQL и не требует таблицы). Также можно передать database, использовать полное имя таблицы, например prometheus.metrics, или не указывать базу данных, чтобы использовать default. Это позволяет одному обработчику обслуживать несколько таблиц TimeSeries.
Чтобы использовать одну фиксированную таблицу для всех запросов, настройте её в обработчике:
Создание таблицы TimeSeries
Создайте базу данных и таблицуTimeSeries:
Приём метрик через удалённую запись
ClickHouse поддерживает протокол удалённой записи Prometheus. Настройте Prometheus на запись в обработчик:prometheus.metrics.
Чтобы объединять данные из множества одновременных запросов удалённой записи в меньшее число частей, ClickHouse использует асинхронные вставки. По умолчанию они включены; включить или отключить их можно с помощью настройки async_insert в URL (или в профиле пользователя).
ClickHouse подтверждает асинхронный запрос удалённой записи только после сброса данных на диск во все внутренние таблицы таблицы TimeSeries, независимо от настройки wait_for_async_insert: согласно протоколу удалённой записи подтверждённая запись считается надёжно сохранённой. Если сброс на диск завершается ошибкой, запрос возвращает ошибку, и Prometheus повторяет попытку.
Поскольку каждый запрос ожидает сброса своих данных на диск, асинхронные вставки ограничивают скорость записи одного отправителя. Prometheus отправляет по одному запросу за раз на каждый сегмент удалённой записи. Когда несколько сегментов отправляют данные одновременно, адаптивный тайм-аут сброса на диск увеличивается до async_insert_busy_timeout_max_ms, если только объём ожидающих запросов раньше не достигнет async_insert_max_data_size. Запрос ожидает, пока его пакет не будет сброшен на диск, а это происходит не позднее чем через указанный интервал после начала формирования пакета. Поэтому при устойчивой нагрузке каждый сегмент записывает примерно samples per request / async_insert_busy_timeout_max_ms, причём по умолчанию Prometheus отправляет до 2 000 образцов за запрос. Чтобы увеличить эту скорость:
- Увеличьте
max_shards(по умолчанию 50) илиmax_samples_per_sendвqueue_configразделаremote_write. При отставании Prometheus самостоятельно добавляет сегменты, вплоть доmax_shards. - Уменьшите
async_insert_busy_timeout_max_msв URL или в профиле пользователя, например&async_insert_busy_timeout_max_ms=50. Сбросы на диск будут происходить чаще, и каждый сброс будет создавать новые части во внутренних таблицах. - Отключите асинхронные вставки с помощью
async_insert=0. В этом случае каждый запрос будет создавать собственные части во внутренних таблицах.
Запрос с PromQL
Используйте конечную точку мгновенного запроса, чтобы вычислить выражение PromQL на определённый момент времени:--get curl отправляет параметры в формате application/x-www-form-urlencoded методом POST:
sum by (job) (http_requests_total{code="200"}) / 2. Длительность сохраняет свои единицы измерения, а не преобразуется в число секунд: rate(x[5m]) возвращается как rate(x[5m]). Если длительность нельзя выразить целым числом в одной единице измерения, она записывается с использованием всех необходимых единиц: rate(x[90s]) возвращается как rate(x[1m30s]). Эта конечная точка не вычисляет выражение, поэтому ей не нужны параметры database и table.
Список функций и операторов агрегации, поддерживаемых HTTP API, диалектом promql и табличными функциями, см. в разделе Поддерживаемые возможности PromQL.
Grafana
Настройте источник данных Prometheus, указав базовый URL без/api/v1 в конце:
/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:
Запрос метаданных метрик
Конечная точка/prometheus/api/v1/metadata возвращает метаданные метрик, хранящиеся в целевой таблице Metrics таблицы TimeSeries: тип, текст справки и единицу измерения каждого семейства метрик. Она поддерживает следующие параметры Prometheus в строке запроса URL:
Целевая таблица
Metrics по умолчанию — это ReplacingMergeTree, упорядоченная по имени семейства метрик: в ней сохраняется последняя записанная запись метаданных для каждого семейства метрик. Несколько записей для одного семейства возвращаются только до тех пор, пока они хранятся в целевой таблице: до слияния её частей или если таблица определена с движком, который их сохраняет.
Чтение метрик через удалённое чтение
ClickHouse поддерживает протокол Prometheus удалённого чтения по адресу/prometheus/api/v1/read.
Настройте сервер Prometheus для чтения из той же таблицы TimeSeries:
Правила записи (recording rules)
ClickHouse не обрабатывает файлы правил Prometheus. Роль правила записи может выполнять refreshable materialized view: оно по расписанию вычисляет PromQL-выражение и добавляет результат в конец таблицыTimeSeries. Следующее представление каждую минуту записывает sum by (job) (rate(http_requests_total[5m])) как job:http_requests:rate5m:
mapUpdate, а для каждой серии результата в конец добавляется один образец. В тот же Map можно добавить дополнительные метки, например map('__name__', 'job:http_requests:rate5m', 'team', 'web'). Записанную серию можно запрашивать так же, как и любую другую метрику:
system.view_refreshes.
Представление отличается от правила записи (recording rule) Prometheus в следующем:
- Время вычисления — это значение
now()на момент выполнения обновления. Помимо обновлений по расписанию, представление обновляется сразу после создания (если оно не создано сEMPTY), после перезапуска сервера, если его обновления не координируются (представление вне базы данных Replicated или Shared, а также представление сall_replicas = 1не запоминает своё последнее обновление), а также когдаSYSTEM START VIEWвозобновляет его после пропущенного запланированного обновления. Округляйтеnow()вниз до интервала, как в примере, чтобы такие обновления не добавляли образцы между запланированными. При этом дополнительное обновление всё же может записать второй образец с той же округлённой временной меткой. Для пятиминутного правила используйтеtoStartOfInterval(now(), INTERVAL 5 MINUTE). - Пропущенные вычисления не наверстываются. После простоя сервера или остановки представления оно вычисляет только текущий интервал, а предшествующие интервалы остаются пустыми. То же самое происходит, если обновление длится дольше интервала.
- Для серии, выпавшей из результата, маркер устаревания не создаётся, поэтому запросы продолжают возвращать её последнее записанное значение в течение периода ретроспективы (lookback) — по умолчанию 5 минут.
- Файла правил нет: каждое правило — это отдельное представление. Через
/api/v1/rulesправила не выводятся.