Установка компонентов

Компоненты StatsHouse нужно устанавливать в следующем порядке (1 → 5):

Локальная установка StatsHouse выглядит почти так же. Отличие заключается в том, что скрипт локальной установки размещает базу данных ClickHouse и агрегатор на разных виртуальных машинах. При полномасштабном развёртывании StatsHouse устанавливайте базу данных ClickHouse и агрегатор на одну и ту же машину.

Узнайте больше о компонентах StatsHouse.

База данных (ClickHouse)

Общую информацию о базе данных можно найти в обзоре компонентов StatsHouse.

Убедитесь, что ваши машины соответствуют требованиям для установки ClickHouse. Мы рекомендуем использовать быстрые SSD-накопители для хранения посекундных данных, чтобы StatsHouse мог предоставлять информацию в режиме реального времени. Узнайте больше о конфигурации (политиках хранения) ClickHouse.

Схема кластера

В кластере ClickHouse на каждый шард должно приходиться по три реплики. Шардов может быть сколько угодно (один или несколько).

Используйте эту схему для создания таблиц ClickHouse.

Конфигурация кластера (политики хранения)

Пример конфигурации кластера ClickHouse:

<storage_configuration>
<disks>
  <clickhouse_fast>
    <path>/var/lib/clickhouse-fast/</path>
  </clickhouse_fast>
</disks>
<policies>
  <ssd_then_hdd>
    <volumes>
      <ssd>
        <disk>clickhouse_fast</disk>
      </ssd>
      <hdd>
        <disk>default</disk>
      </hdd>
    </volumes>
  </ssd_then_hdd>
</policies>
</storage_configuration>

Такая политика подразумевает, что база ClickHouse вначале поместит данные на быстрые SSD, а затем переместит их на более медленные жёсткие диски.

Конфигурация применяется к созданной таблице: см. приведённую выше схему.

Сервис метаданных

Как только вы создали таблицы ClickHouse, можно устанавливать сервис метаданных.

Общую информацию о сервисе метаданных можно найти в обзоре компонентов StatsHouse.

Сервис метаданных можно установить на любой машине. Устанавливается один экземпляр сервиса.

На случай возможных сбоев создавайте резервную копию сервиса. Например, можно копировать бинлог базы данных сервиса раз в день, используя cron. Так сервис метаданных можно будет перезапустить при необходимости.

info

Сейчас мы разрабатываем собственный механизм консенсуса, чтобы сделать сервис метаданных распределённым.

Сервису метаданных нужны следующие параметры:

• --db-path — место хранения данных,
• --binlog-prefix — место хранения бинлога.

Пример скрипта для установки сервиса метаданных:

statshouse-metadata --db-path=/var/lib/statshouse/metadata/db --binlog-prefix=/var/lib/statshouse/metadata/binlog/bl

Агрегатору, API/UI-компоненту и агентам нужен адрес сервиса метаданных. Агенты получают эту информацию от агрегаторов.

В сервисе метаданных установлен свой агент.

Что происходит при отказе сервиса метаданных

Если сервис метаданных не работает, StatsHouse не сможет создавать новые метрики и теги, а также использовать информацию о тегах (читайте подробнее о маппинге).

У каждого компонента StatsHouse есть копия метаданных, так что компонент продолжит работать, даже если сервис метаданных недоступен. Если компонент тоже выйдет из строя, восстановить его при неработающем сервисе метаданных будет невозможно.

important

В случае отказа агрегатора как можно скорее восстановите сервис метаданных с тем же IP-адресом.

Агрегаторы

Общую информацию об агрегаторах можно найти в обзоре компонентов StatsHouse.

Агрегатору необходимо знать, где найти кластер. Укажите следующие параметры:

• --cluster — имя кластера;
• --kh — адрес базы данных (в базе может содержаться много кластеров);
• --agg-addr — порт для приёма данных;
• --aes-pwd-файл — директория, в которой хранится ключ шифрования (этот параметр обязателен для запуска: /etc/engine/pass — значение по умолчанию);
• --cache-dir — директория, где будут храниться данные, если возникнут проблемы со вставкой в базу;
• -u, -g — группа и пользователь (обязательные параметры).

На каждой реплике ClickHouse установите агрегатор StatsHouse. Пример скрипта для установки агрегатора:

statshouse aggregator --cluster=test_shard_localhost --agg-addr=':13336' --aes-pwd-file=/etc/engine/pass \
--kh=XXX.X.X.X:XXXX --cache-dir=/var/lib/statshouse/cache/aggregator -u=root -g=root

Когда агрегатор получает адрес кластера ClickHouse, он узнаёт, на каком шарде и какой реплике он установлен.

Агентам нужны адреса всех агрегаторов. Каждый агент последовательно сканирует эти адреса и пытается получить необходимую конфигурацию с первого доступного агрегатора. Агент отправляет данные агрегаторам в псевдослучайном порядке.

Агрегатор запускается с параметром --aes-pwd-file. Он указывает на директорию, в которой содержится ключ для расшифровки входящего трафика. Подробнее о параметре --aes-pwd-file и ключах шифрования читайте в разделе о безопасности подключений.

Размера директории --cache-dir должно быть достаточно для хранения данных, полученных за шесть часов работы агрегатора.

Агенты

important

Убедитесь, что агент установлен на каждой машине, которая отправляет метрики в StatsHouse:

• на машинах ClickHouse/агрегаторов,
• на машине сервиса метаданных,
• на машине API/UI-компонента.

Агент открывает локальный порт (13337 по умолчанию) и получает данные от приложения. Затем он отправляет данные в агрегаторы.

Общую информацию об агентах можно найти в обзоре компонентов StatsHouse.

Агенты доступны в виде RPM- или DEB-пакетов, например:

statshouse-2024.05.1-1.almalinux9.x86_64.rpm или statshouse_2024.05.1-focal_amd64.deb.

Агенту необходимы следующие параметры:

• --agg-addr — адреса агрегаторов (или прокси);
• --aes-pwd-файл — директория, в которой хранится ключ шифрования (шифрует данные, которые агент отправляет в агрегатор или прокси);
• --cache-dir — директория, где будут храниться данные в случае недоступности агрегатора;
• --env-file-path — файл, в котором можно настроить теги для хостовых (аппаратных) метрик (необязательный параметр).

Пример скрипта для установки агента:

statshouse agent --agg-addr=XX.XXX.XXX.XXX:XXXX,YY.YYY.YYY.YYY:YYYY,ZZ.ZZZ.ZZZ.ZZZ:ZZZZ \ 
--aes-pwd-file=/etc/engine/pass --cache-dir=/var/lib/statshouse/

Размера директории --cache-dir должно быть достаточно для хранения данных, полученных за шесть часов работы агента. Если агрегаторы недоступны более шести часов, старые данные удаляются с диска.

Подробнее о параметре --aes-pwd-file и ключах шифрования читайте в разделе о безопасном подключении.

Читайте также о том, как использовать теги для метрик хостов и параметр --env-file-path.

Как следить за состоянием агентов

1. Откройте служебную метрику __heartbeat_version, которая показывает количество запущенных компонентов.
2. Для тега component выберите значение agent.
3. Для тега host выберите нужное имя хоста.
4. Проверьте, отображается ли контрольный сигнал от хоста.

Также проверьте, может ли агент отправлять реальные данные: попробуйте отправить тестовые данные.

API/UI

Пользовательский интерфейс (UI) StatsHouse входит в состав API-компонента. Сразу после установки API/UI можно просматривать служебные метрики — они отражают состояние StatsHouse.

API-компонент можно установить на любой машине.

API-компоненту требуются следующие параметры:

• --clickhouse-v2-addrs — адрес кластера ClickHouse,
• --listen-addr — порт для приёма данных,
• --disk-cache — место для хранения кэшированных метаданных (маппинга string↔int32),
• --static-dir — место, где хранятся статические файлы UI.

Пример скрипта для установки API/UI:

statshouse-api --clickhouse-v2-addrs=XXX.X.X.X:XXXX \
--listen-addr=:YYYYY --disk-cache=/var/lib/statshouse/cache/api/mapping_cache.sqlite3 \
--static-dir=/usr/lib/statshouse-api/statshouse-ui/

Аутентификация

Подключите свой механизм аутентификации. Например, можно установить сервер nginx, использующий JSON Web Tokens (JWT).

Чтобы обращаться к API без аутентификации, включите режим --insecure-mode.

Прокси

Информацию о прокси можно найти в обзоре компонентов StatsHouse. Узнайте, как обеспечить безопасность подключений с помощью прокси и криптоключей.