chtune — ClickHouse System Tuner

TUI-утилита в стиле MS-DOS / Norton Commander для аудита и тюнинга параметров Linux-хоста под ClickHouse, диагностики проблем гипервизора из гостевой ВМ и управления профилями tuned.

 ▌ chtune ▐   ClickHouse System Tuner  v1.12               mode: ROOT
═══ ▶ ТЮНИНГ ◀ ═══ Диагностика ═══ Снимки ═══ tuned ═══════════════════
╔══════════════════════════════════════════════════════════════════════╗
║                       Параметры системы                              ║
╠══════════════════════════════════════════════════════════════════════╣
║   SEL  PARAMETER                       CURRENT         TARGET STATUS ║
╠══════════════════════════════════════════════════════════════════════╣
║   [■] vm.swappiness                    60              1      [WARN] ║
║   [■] vm.max_map_count                 65530           1048576[CRIT] ║
║   [ ] vm.overcommit_memory             0               0      [ OK ] ║
║   [■] net.core.netdev_max_backlog      1000            10000  [CRIT] ║
║   ...                                                                ║
╚══════════════════════════════════════════════════════════════════════╝
 F1 Помощь  F2 Скан  F3 Детали  F4 Отчёт  F5 Применить  F11 Откат  Tab

Что делает

Четыре экрана, переключаемых клавишей Tab:

Тюнинг — проверяет 25 параметров ОС против рекомендаций для ClickHouse, позволяет выбрать что менять (вручную либо через 7 пресетов сценариев нагрузки), задать пользовательские или дефолтные значения и применить их через генерируемый bash-скрипт (sysctl.d, udev rules, systemd drop-in, отдельный oneshot-сервис для THP).

Диагностика — 17 индикаторов состояния гипервизора, видимых из гостевой ВМ: steal time, CPU-флаги, ballooning, clocksource, NUMA-топология, распределение IRQ, IO latency и т.п. Только просмотр, ничего не меняет.

Снимки — управление сохранёнными состояниями. Перед каждым применением параметров автоматически сохраняется JSON-снимок. Список, детали, откат, удаление, чистка старых.

tuned — управление профилями tuned: просмотр, копирование, удаление, кастомизация, объединение нескольких профилей в один, импорт upstream- профилей с GitHub. Если tuned не установлен — встроенная установка через пакетный менеджер дистрибутива.

Зависимости

Обязательно:

• Linux (любой современный дистрибутив с ядром 4.x+)
• Python 3.7+ с модулем curses

Опционально (если установлены — диагностика покажет больше):

• ethtool — определение драйвера и multiqueue для NIC
• numactl — расширенная NUMA-информация
• tuned — отображение и управление tuned-профилями (см. вкладка tuned)
• dmesg / journalctl — детекция нестабильного TSC
• systemctl — управление сервисом tuned и clickhouse-server
• lsmod — определение balloon-драйверов

Установка Python curses по дистрибутивам

ALT Linux:

sudo apt-get install python3-modules-curses

RHEL / Rocky / Alma / Oracle Linux:

sudo dnf install python3 ncurses

Debian / Ubuntu / Astra Linux (обычно уже включено):

sudo apt install python3

Alpine:

sudo apk add python3

Проверка:

python3 -c "import curses; print('OK')"

Установка и запуск

Один файл, никаких зависимостей сверх стандартной библиотеки:

chmod +x chtune.py
./chtune.py           # аудит без прав
sudo ./chtune.py      # с возможностью применять изменения

Утилита не требует установленного ClickHouse — параметры проверяются независимо. Если clickhouse-server есть в systemd, дополнительно проверяется его LimitNOFILE.

Минимальный размер терминала: 90×22.

Управление: общее

Клавиша	Действие
Tab	Переключение между экранами (Тюнинг → Диагностика → Снимки → tuned)
↑ ↓ j k	Перемещение
PgUp PgDn Home End	Быстрая навигация
F1	Помощь
F2	Пересканировать текущий экран
F3 / Enter	Подробности выделенного элемента
F4	Сохранить отчёт
F10 / Esc / q	Выход

Экран 1 — Тюнинг

Клавиша	Действие
Space	Отметить параметр
F5	Применить отмеченные параметры (создаст снимок)
F6	Пользовательское значение для текущего параметра
F7	Рекомендованное значение
F8	Снять все отметки
F9	Отметить все WARN/CRIT
F11	Быстрый откат (выбор снимка)
p	Выбрать пресет нагрузки (7 сценариев)

Пресеты нагрузки

Клавиша p открывает picker сценариев. Каждый пресет автоматически отмечает релевантные параметры и проставляет значения именно под этот тип нагрузки. После выбора в верхнем баре отображается preset: <id>, а в подвале — рекомендуемый tuned-профиль.

Пресет	Окружение	Рекомендуемый tuned
Single-node OLAP	bare-metal	throughput-performance
VM Single-node OLAP	в ВМ	virtual-guest
Distributed Cluster	bare-metal	network-throughput
VM Distributed	в ВМ	merge virtual-guest + network-throughput
Low-latency Coordinator	любое	network-latency
S3-tiered / Object Storage	любое	network-throughput
Maximum Performance	bare-metal NVMe	accelerator-performance

Пресет — это отправная точка: после применения можно точечно менять custom-значения через F6, снимать отметки Space, или сбрасывать всё через F8. Карточка параметра (F3/Enter) показывает таблицу «значение по сценариям» — видно сразу, какой preset что предлагает.

Список из 25 проверяемых параметров

Память / VM

• vm.swappiness — минимизация свопа (везде = 1)
• vm.max_map_count — mmap для тысяч партов MergeTree (1048576)
• vm.overcommit_memory — CH сам считает память (0)
• vm.dirty_background_ratio — фоновый сброс грязных страниц (5; low-latency: 3)
• vm.dirty_ratio — блокирующий сброс (10; low-latency: 5)
• kernel.numa_balancing — выключить в ВМ (0)
• vm.zone_reclaim_mode — не возвращать память в NUMA-узел (0)

io_uring / async IO

• kernel.io_uring_disabled — разрешить io_uring (0; Ubuntu 23.10+ ставит 2!)
• fs.aio-max-nr — лимит async IO (1048576; s3-tiered: 2097152)
• fs.file-max — глобальный лимит файловых дескрипторов
• kernel.threads-max — лимит потоков (для distributed/s3/max-perf)

Сеть

• net.core.rmem_max / wmem_max — TCP буферы (16M; distributed: 64M; s3/max-perf: 128M)
• net.core.somaxconn — очередь listen() (4096)
• net.core.netdev_max_backlog — очередь NIC (10000)
• net.ipv4.tcp_max_syn_backlog — полуоткрытые соединения (30000, не для single-node)
• net.ipv4.ip_local_port_range — диапазон портов (1024-65535, не для single-node)
• net.ipv4.tcp_tw_reuse — переиспользование TIME_WAIT (1, не для single-node)
• net.ipv4.tcp_fin_timeout — таймаут закрытия TCP (15; low-latency: 10)
• net.ipv4.tcp_congestion_control — BBR

Память больших страниц / CPU / IO

• Transparent Huge Pages — madvise
• CPU governor — performance
• IO scheduler — mq-deadline/none (зависит от диска и preset)
• read_ahead_kb — readahead (single-olap: 8192, low-lat: 2048, max-perf: 16384)

Лимиты процесса

• LimitNOFILE для clickhouse-server — 500000

Что происходит при F5 (Применить)

Перед любыми изменениями автоматически сохраняется JSON-снимок текущих значений в ./chtune-snapshots/snapshot-YYYYMMDD-HHMMSS.json.

Затем генерируется /tmp/chtune-apply.sh — bash-скрипт, который:

1. Создаёт /etc/sysctl.d/99-chtune.conf с выбранными sysctl-параметрами
2. Создаёт /etc/udev/rules.d/99-chtune.rules для scheduler и read_ahead
3. Создаёт /etc/systemd/system/disable-thp.service — oneshot, выставляющий THP до старта clickhouse-server
4. Создаёт clickhouse-server.service.d/99-chtune.conf с LimitNOFILE
5. Применяет транзиентно через sysctl -w и echo > /sys/...
6. Подгружает модуль tcp_bbr, если выбран

Под root — предлагает запустить сразу. Иначе — путь для ручного sudo bash /tmp/chtune-apply.sh.

Экран 2 — Диагностика

Только просмотр индикаторов, видимых из гостевой ВМ. Каждый со светофором (OK/WARN/CRIT/INFO) и советом в подвале, что попросить у админа хоста.

Индикатор	Что значит проблема
Hypervisor vendor	Тип виртуализации
CPU model	qemu64/common kvm = нет host-passthrough
SIMD flags	Без avx2 + bmi2 CH идёт на скалярные пути
TSC flags	Без constant_tsc + nonstop_tsc дорогой clock_gettime()
Steal time	>5% = хост перегружен или vCPU оверсубскрибнуты
Clocksource	hpet/acpi_pm вместо kvm-clock/tsc = деградация
NUMA topology	Плоская против реальной топологии хоста
Memory balloon driver	Активный балун в БД = непредсказуемые тормоза
NIC driver	e1000/rtl8139 = эмуляция, 1 Гбит потолок
NIC queues	Single-queue virtio = горлышко между шардами
IRQ distribution	Все на cpu0 = нет RPS/RSS
IO latency	>10 мс = бэкенд занят
Discard support	no = thin без TRIM, фрагментация со временем
dmesg TSC status	«Marking TSC unstable» = миграция vCPU без invariant
THP boot cmdline	transparent_hugepage=always в kernel cmdline
tuned active profile	Какой профиль сейчас активен

Экран 3 — Снимки

Табличный список (новые сверху): дата, число параметров, hostname, версия chtune, размер. Под списком — preview-полоска с парами «было → станет» и именами создаваемых файлов.

Клавиша	Действие
F3 / Enter	Полная карточка снимка
F5	Откат к выбранному (с подтверждением)
F8	Удалить выбранный снимок
F9	Чистка снимков старше N дней (по умолчанию 30)

F11 в любом режиме — быстрый picker без перехода на экран.

Скрипт отката

/tmp/chtune-rollback.sh восстанавливает значения и удаляет файлы, созданные этим применением:

1. Удаляет 99-chtune.conf, udev rules, drop-in, systemd-сервис THP
2. Восстанавливает каждое значение через sysctl -w / echo > /sys/...
3. Перезагружает udev, systemd, sysctl
4. Для LimitNOFILE — напоминает перезапустить clickhouse-server

Где сохраняются снимки

./chtune-snapshots/ относительно того каталога, откуда запускается chtune. Запускайте из одного каталога на одном хосте, иначе старые снимки не будут видны.

Утилита также читает (но не пишет) две легаси-локации, чтобы старые снимки от предыдущих версий не потерялись:

• /var/lib/chtune/snapshots/
• /tmp/chtune-snapshots/

Снимки не удаляются автоматически. Чистка — F9 или вручную:

find ./chtune-snapshots -name 'snapshot-*.json' -mtime +30 -delete

Экран 4 — tuned

Управление профилями tuned. 4-зонный layout:

┌── Профили (6) ────────┬── As-is: throughput-performance ──────────────────┐
│ ▶ throughput-perf...  │  [sysctl]                                          │
│   balanced            │    vm.swappiness   = 10  runtime: 1                │
│   virtual-guest       │    vm.dirty_ratio  = 40                            │
│   network-latency     │  [cpu]                                             │
│   chtune-olap [c]     │    governor        = performance                   │
│                       ├── To-be: virtual-guest ────────────────────────────┤
│                       │  [sysctl]                                          │
│                       │    vm.swappiness   = 30   ★ было: 30               │
│                       │    vm.dirty_background_ratio = 10                  │
└───────────────────────┴────────────────────────────────────────────────────┘

• Профили — список, активный с ▶, пользовательские с [c]
• As-is — параметры активного профиля + реальное значение в системе (runtime: X) рядом для сравнения
• To-be — параметры выбранного профиля; custom-значения в magenta-bold

Клавиша	Действие
←/→	Фокус между списком профилей и to-be
F5	Применить выбранный профиль (с custom-overrides — через обёртку)
F6	(в to-be) Custom-значение параметра
F7	Сбросить custom
F8	Удалить пользовательский профиль
F9	Скопировать профиль под новым именем
r	Какие профили доступны в подключённых репозиториях
i	Импорт upstream-профилей с GitHub
m	Слияние нескольких профилей в один

Установка tuned из chtune

Если tuned не установлен, открывается экран установки с тремя вариантами:

Клавиша	Что ставится	Где доступно
F5 Базовая	tuned	все 5 дистрибутивов
F6 Расширенная	+ tuned-utils, tuned-profiles-compat	Debian, Ubuntu, Astra
F7 + БД	+ tuned-profiles-mssql, oracle, postgresql, sap, sap-hana, realtime (только реально доступные в репо)	Debian, Ubuntu, Astra
i Импорт	upstream-профили с GitHub	везде, где есть интернет

Поддерживаемые дистрибутивы: Alpine, ALT Linux, Astra Linux, Debian, Ubuntu (и derived через ID_LIKE).

Доступность подпакетов

Перед предложением установки chtune спрашивает пакетный менеджер, какие из подпакетов реально доступны в подключённых репозиториях (apt-cache show pkg или apk info -e pkg). В UI:

• зелёным — ✓ доступно
• жёлтым — ✗ нет в репо

Команда установки содержит только реально существующие пакеты, транзакция не упадёт. Клавиша r показывает полную таблицу установлено/доступно/нет для текущего дистрибутива.

Импорт upstream-профилей (i)

Скачивает https://github.com/redhat-performance/tuned/archive/refs/heads/master.tar.gz, распаковывает только profiles/, показывает мультивыбор:

┌─ Импорт upstream-профилей (скачано: 27) ──────────────┐
│  Выбрано: 3                                             │
│                                                          │
│  [■]  balanced            General non-specialized       │
│  [■]  oracle              Profile for Oracle databases │
│  [ ]  postgresql          Profile for PostgreSQL [SCR]│
│  [■]  sap-hana            Profile for SAP HANA          │
│  ...                                                    │
│           Space — выбрать  Enter — импорт  Esc          │
└──────────────────────────────────────────────────────────┘

Помечает профили со скриптами [SCR]. Копирование скриптов запрашивает отдельным подтверждением (по умолчанию — нет, безопаснее).

Для закрытых контуров без интернета — chtune ищет тарбол локально:

• ./tuned-upstream.tar.gz в текущем каталоге
• /tmp/chtune-upstream.tar.gz
• /tmp/tuned-upstream.tar.gz

Скачайте тарбол на машине с интернетом, перенесите по любому из этих путей, нажмите i — chtune использует локальный файл вместо GitHub.

Слияние профилей (m)

Создаёт плоский (без include=) объединённый профиль из 2+ источников.

1. Multi-select с показом порядка выбора [1] [2] [3] (поздние перекрывают ранние)
2. Preview: какие секции и сколько параметров
3. Ввод имени целевого профиля
4. Запись в /etc/tuned/profiles/<name>/tuned.conf

Результат — самодостаточный файл с комментариями, показывающими источники:

# Merged profile — flattened, no 'include' chain
# Source profiles, in priority order (later overrides earlier):
#   1. throughput-performance
#   2. oracle
#   3. postgresql

[main]
summary=Merged: throughput-performance, oracle, postgresql

[sysctl]
vm.swappiness=10            # из oracle перекрыл throughput-performance
vm.dirty_ratio=40           # из throughput-performance
...

[vm]
transparent_hugepages=never # из oracle

Сценарий «свой профиль для ClickHouse»

1. На экране install — F7 поставить все доступные в репо
2. i — импортировать недостающие upstream (oracle, postgresql, sap-hana)
3. m — Merge в порядке: throughput-performance → oracle → postgresql
4. Назвать clickhouse-olap
5. F5 — применить (создаст снимок автоматически)
6. F6 — точечная подстройка через custom-значения
7. F11 — откат, если что-то не так

Что создаётся в системе

Путь	Когда
./chtune-snapshots/snapshot-*.json	Перед каждым F5 в Тюнинге
/tmp/chtune-apply.sh	F5 в Тюнинге
/tmp/chtune-rollback.sh	F5/F11 в Снимках
/tmp/chtune-report-*.txt	F4 в любом режиме
/etc/sysctl.d/99-chtune.conf	После apply, если выбраны sysctl
/etc/udev/rules.d/99-chtune.rules	После apply, если выбраны scheduler/read_ahead
/etc/systemd/system/disable-thp.service	После apply, если выбран THP
/etc/systemd/system/clickhouse-server.service.d/99-chtune.conf	После apply, если выбран LimitNOFILE
/etc/modules-load.d/bbr.conf	После apply, если выбран tcp_bbr
/etc/tuned/profiles/<name>/tuned.conf	После m или i в tuned

Безопасность и ограничения

• Не перезапускает clickhouse-server. LimitNOFILE применится только после ручного systemctl restart clickhouse-server — утилита не решает за вас, когда можно ронять прод.
• Не правит kernel cmdline. Изменение GRUB с ребутом — слишком инвазивно. Текущее значение THP в cmdline показывается как INFO в диагностике.
• Не лезет за пределы гостя. Параметры гипервизора только диагностируются.
• Импорт upstream-скриптов опционален. По умолчанию копируются только tuned.conf, без .sh. Скрипты требуют отдельного подтверждения.
• Идемпотентность. Повторный apply безопасен — файлы перезаписываются с тем же содержимым. Повторный merge с тем же именем — ошибка «уже существует».
• Откат. F11 в любом режиме или F5 в Снимках. Снимок до каждого применения создаётся автоматически.

Совместимость

Дистрибутивы: проверено на ALT Linux, RHEL/Rocky, Ubuntu, Debian. Использует только /proc, /sys и стандартные системные утилиты.

Гипервизоры: KVM/QEMU, VMware ESXi, Microsoft Hyper-V, Xen. Контейнеры (LXC/Docker) — частично, в контейнере не все параметры доступны.

Bare-metal: работает; диагностика покажет «bare-metal/none» для hypervisor vendor.

Совет по практике

1. На новой ноде до установки ClickHouse: запустите chtune, F9 (все WARN), F5. Получите чистый baseline.
2. После запуска CH под нагрузкой: Tab в Диагностику, проверьте steal time и IRQ distribution. Что красное — F4 (отчёт) и в тикет админу хоста.
3. Перед обновлением ClickHouse: F4 — снимите baseline. Если после обновления что-то поменялось в окружении, diff отчётов покажет что.
4. Перед экспериментами с tuned: запустите chtune, перейдите на вкладку tuned, нажмите F9 на текущем активном профиле. Создастся копия — на ней можно безопасно экспериментировать, не трогая базу.
5. Регулярно: F9 в Снимках — чистка старше 30 дней.

Файловая структура проекта

chtune.py             — единственный исполняемый файл
README.md             — этот файл
TUNED-PROFILES.md     — памятка по всем профилям tuned с примерами для CH
./chtune-snapshots/   — снимки (создаётся автоматически при первом F5)

Полезные ссылки

• TUNED-PROFILES.md — подробная памятка по всем стандартным и специализированным профилям tuned, дерево наследования, таблица «какой профиль выбрать», подсказки по комбинациям через merge
• redhat-performance/tuned — upstream-репозиторий
• tuned-profiles(7) — манпейдж

Лицензия

Pleasant-day-ware: используйте как угодно, если стало легче — поделитесь хорошим днём с коллегой.