Версия: Пульт 2.3.0

ClickHouse

ClickHouse — опциональное внешнее колонночное хранилище для исторических данных, метрик, трендов и больших объёмов мониторинга. Его подключают, когда нужно отдельное хранилище для быстрого анализа истории; без ClickHouse Пульт продолжает работать с PostgreSQL. Инструкция ниже — для сценариев с большими объёмами исторических данных.

Сервер Пульта может писать историю в ClickHouse в режиме HTTP или Native (см. Коннектор истории).

Установка ClickHouse

Произвести установку сервера Clickhouse на выделенном сервере согласно официальной документации в соответствии с выбранной ОС.

Произвести конфигурацию сервера Clickhouse:

sudo nano /etc/clickhouse-server/config.d/listen_host.xml

<clickhouse>
    <logger>
        <level>information</level>
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
        <size>10M</size>
        <count>7</count>
    </logger>
    <display_name>clickhouse</display_name>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <interserver_http_port>9009</interserver_http_port>
</clickhouse>

Произвести настройку пользователей в Clickhouse. Для этого создать конфигурационный файл со следующим содержимым, указав в теге <password></password> пароль для администратора pult:

sudo nano /etc/clickhouse-server/users.d/pult.xml

<clickhouse>
    <users>
        <default>     
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
            <show_named_collections>1</show_named_collections>
            <show_named_collections_secrets>1</show_named_collections_secrets>
        </default>
        <!-- Создание нового пользователя pult в качестве администратора БД -->
        <pult>
            <password>changeme</password>
            <grants>
                <query>GRANT admin</query>
            </grants>
        </pult>
    </users>
    <!-- Создание роли admin -->
    <roles>
    <admin>
        <grants>
            <query>GRANT ALL ON pult.* WITH GRANT OPTION;</query>
        </grants>
    </admin>
    </roles>
    <!-- Настройка стандартного профиля default для корректного форматирования данных в JSON (необходимо для интеграции с Grafana) -->
    <profiles>
        <default>
            <input_format_json_try_infer_numbers_from_strings>1</input_format_json_try_infer_numbers_from_strings>
            <output_format_json_quote_64bit_floats>1</output_format_json_quote_64bit_floats>
        </default>
    </profiles>
</clickhouse>

Перезапустить службу Clickhouse:

sudo systemctl restart clickhouse-server

Создать БД pult в Clickhouse через консоль с помощью клиента clickhouse-client, указав пользователя и заданный пароль для подключения к Clickhouse:

clickhouse-client --user pult --password changeme --multiquery "CREATE DATABASE IF NOT EXISTS pult; \
CREATE TABLE IF NOT EXISTS pult.history (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), value Float64) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH; \
CREATE TABLE IF NOT EXISTS pult.history_str (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), value String) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH; \
CREATE TABLE IF NOT EXISTS pult.history_uint (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), value UInt64) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH; \
CREATE TABLE IF NOT EXISTS pult.history_text (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), value String) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH; \
CREATE TABLE IF NOT EXISTS pult.history_log (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), timestamp UInt64 CODEC(Delta, LZ4), logeventid UInt64, source String, severity UInt8, value String) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH; \
CREATE MATERIALIZED VIEW IF NOT EXISTS pult.trends (itemid UInt64, clock DateTime('Europe/Moscow'), num AggregateFunction(count), value_min AggregateFunction(min, Float64), value_avg AggregateFunction(avg, Float64), value_max AggregateFunction(max, Float64)) ENGINE = AggregatingMergeTree PARTITION BY toYYYYMM(clock) ORDER BY (itemid, toStartOfHour(toDateTime(clock), 'Europe/Moscow')) SETTINGS index_granularity = 8192 AS SELECT itemid, toStartOfHour(toDateTime(clock), 'Europe/Moscow') AS clock, countState(*) AS num, minState(value) AS value_min, avgState(value) AS value_avg, maxState(value) AS value_max FROM pult.history GROUP BY itemid, clock; \
CREATE MATERIALIZED VIEW IF NOT EXISTS pult.trends_uint (itemid UInt64, clock DateTime('Europe/Moscow'), num AggregateFunction(count), value_min AggregateFunction(min, UInt64), value_avg AggregateFunction(avg, UInt64), value_max AggregateFunction(max, UInt64)) ENGINE = AggregatingMergeTree PARTITION BY toYYYYMM(clock) ORDER BY (itemid, toStartOfInterval(toDateTime(clock, 'Europe/Moscow'), toIntervalHour(1))) TTL toStartOfInterval(toDateTime(clock, 'Europe/Moscow'), toIntervalHour(1)) + toIntervalMonth(12) SETTINGS index_granularity = 8192 AS SELECT itemid, toStartOfInterval(toDateTime(clock, 'Europe/Moscow'), toIntervalHour(1)) AS clock, countState(*) AS num, minState(value) AS value_min, avgState(value) AS value_avg, maxState(value) AS value_max FROM pult.history_uint GROUP BY itemid, clock; \ 
CREATE TABLE IF NOT EXISTS pult.history_bin (itemid UInt64, clock UInt64 CODEC(Delta, LZ4), ns UInt64 CODEC(T64, LZ4), value String) ENGINE = MergeTree() PARTITION BY toYYYYMM(CAST(clock as date)) ORDER BY (itemid, clock) TTL (CAST(clock as date)) + INTERVAL 6 MONTH;"

Коннектор истории

Коннектор ClickHouse отправляет историю Пульта в ClickHouse: числовые метрики, строки, логи и текстовые значения.

Параметры подключения задаются в файле .env (см. общую инструкцию) и в сервисах pult-server и pult-web.

ClickHouse используется как быстрое хранилище истории. Основная база PostgreSQL при этом остаётся нужна для настроек, хостов, пользователей, событий и другой конфигурации.

Режимы

HTTP

Простой режим для старта и проверки. Обычно используется порт 8123.

ZBX_HISTORY_CLICKHOUSE_CONNECTOR=http
ZBX_HISTORY_CLICKHOUSE_STORAGE_URL=http://${CLICKHOUSE_HOST}:8123/?database=${CLICKHOUSE_DB}&user=${CLICKHOUSE_USER}&password=${CLICKHOUSE_PASSWORD}
ZBX_HISTORY_CLICKHOUSE_STORAGE_TYPES=dbl,str,log,uint,text
ZBX_HISTORY_CLICKHOUSE_CHUNK_SIZE=10000
ZBX_HISTORY_CLICKHOUSE_FLUSH_TIMEOUT=3

Native

Более производительный режим для записи больших объёмов истории. Обычно используется порт 9000.

ZBX_HISTORY_CLICKHOUSE_CONNECTOR=native
ZBX_HISTORY_CLICKHOUSE_STORAGE_URL=${CLICKHOUSE_HOST}:9000/${CLICKHOUSE_DB}
ZBX_HISTORY_CLICKHOUSE_STORAGE_TYPES=dbl,str,log,uint,text
ZBX_HISTORY_CLICKHOUSE_CHUNK_SIZE=10000
ZBX_HISTORY_CLICKHOUSE_FLUSH_TIMEOUT=3

С логином и паролем в URL:

ZBX_HISTORY_CLICKHOUSE_STORAGE_URL=user:password@${CLICKHOUSE_HOST}:9000/${CLICKHOUSE_DB}

Типы данных и параметры записи

Типы данных (ZBX_HISTORY_CLICKHOUSE_STORAGE_TYPES):

dbl — дробные числа;
uint — целые числа;
str — строки;
log — логи;
text — текстовые значения.

Параметры записи:

ZBX_HISTORY_CLICKHOUSE_CHUNK_SIZE — сколько записей копить перед отправкой в ClickHouse;
ZBX_HISTORY_CLICKHOUSE_FLUSH_TIMEOUT — через сколько секунд отправлять данные, даже если пачка ещё не набралась.

После изменения параметров перезапустите контейнер pult-server.

Важно для веб-интерфейса

Даже если сервер пишет историю через Native, веб-интерфейсу нужен HTTP-доступ к ClickHouse (порт 8123).

ZBX_HISTORY_CLICKHOUSE_URL=http://${CLICKHOUSE_HOST}:8123/?database=${CLICKHOUSE_DB}
ZBX_HISTORY_CLICKHOUSE_USERNAME=${CLICKHOUSE_USER}
ZBX_HISTORY_CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD}
ZBX_HISTORY_CLICKHOUSE_TYPES=dbl,str,log,uint,text

Как проверить

Проверить HTTP:

curl http://${CLICKHOUSE_HOST}:8123/ping

Ожидаемый ответ:

Ok.

Проверить Native:

clickhouse-client --host ${CLICKHOUSE_HOST} --port 9000 --database ${CLICKHOUSE_DB} --query "SELECT version()"

Проверить, что данные пишутся:

SELECT count() FROM history;
SELECT count() FROM history_uint;
SELECT count() FROM history_str;
SELECT count() FROM history_log;
SELECT count() FROM history_text;

Посмотреть последние значения:

SELECT itemid, clock, ns, value
FROM history
ORDER BY clock DESC
LIMIT 10;

Частые ошибки

Для HTTP указан порт 9000 вместо 8123.
Для Native указан порт 8123 вместо 9000.
Не указана база данных: для HTTP это ?database=pult, для Native это /pult в конце URL.
У пользователя ClickHouse нет прав на SELECT и INSERT.
Таблицы истории не созданы или имеют неправильную структуру.
Веб-интерфейс не видит ClickHouse, потому что ему не задан ZBX_HISTORY_CLICKHOUSE_URL (HTTP).

Установка ClickHouse​

Коннектор истории​

Режимы​

HTTP​

Native​

Типы данных и параметры записи​

Важно для веб-интерфейса​

Как проверить​

Частые ошибки​