refactor(smoke): цели проверки по назначению — смоук, ClickHouse, службы

- Зачем:
  - смоук перестал быть быстрым: 42 секунды из 48 съедали шесть проверок,
    которые ждут службу — запуск DAG, вход в Superset, Kafka с машины.
  - имена целей врали: смоуком звались и глубокая проверка кластера, и
    интеграционные проверки; префикс достался им от общего происхождения.
  - нигде не было записано, зачем в репозитории каждая цель и куда класть
    новую проверку, — без записи скрипт дорастёт снова.
- Что:
  - ось деления — кого спрашивают, а не сколько стоит: make smoke (стенд
    собран), make check-clickhouse (спрашивают у ClickHouse), новая
    make check-services (службы работают).
  - шесть тяжёлых проверок переехали в scripts/stand-services.sh; общее —
    счёт, обращение к Compose, зависимости машины и check_containers_survived
    — вынесено в scripts/stand-common.sh, копипасты нет.
  - smoke-cluster переименована в check-clickhouse; имя файла скрипта не
    тронуто (в него встраивается проверка договора со схемой), расхождение
    названо в карте.
  - смоук и check-services печатают своё время в строке ИТОГ; порога по
    времени нет — по доводу ADR 0004.
  - docs/architecture/testing.md: карта всех семи целей, правило быстрого
    смоука словами, лесенка по частоте и правило про краснеющую проверку,
    переехавшее из README; указатель из AGENTS.md.
  - README: описания целей сокращены, карта не дублируется; быстрый старт
    показывает работающий стенд, а не только собранный.
  - планка приёмки этапа в спеке названа поимённо: три цели вместо
    «smoke-проверки».
- Проверка:
  - make config-test, make smoke (19 проверок, 6 с), make check-clickhouse
    (8 проверок, 7 с), make check-services (7 проверок, 44 с) — зелёные.
  - 19 + 7 = 25 разных проверок, как и до деления: check_containers_survived
    считается дважды намеренно.
  - краснеют обе разделённые цели: со снятым prometheus смоук дал три ошибки,
    с подменённым UUID подключения Superset покраснел check-services.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-06 14:34:02 +03:00
co-authored by Claude Opus 5
parent f84f8c416f
commit bbbe17cfb0
9 changed files with 638 additions and 412 deletions
+30 -38
View File
@@ -23,7 +23,7 @@ Prometheus, Grafana и общая база Postgres для метаданных.
пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не
хватает, стенд одинаково хорошо живёт на недорогом VPS.
Полная проверка также использует `curl`, `jq`, `awk`,
Проверкам на поднятом стенде также нужны `curl`, `jq`, `awk`,
`grep`, `sed`, `tail`, `sleep` и `timeout`. По умолчанию должны быть свободны
порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
и `29092`. Проверкам без стенда — `make config-test`, `make lint`,
@@ -34,8 +34,15 @@ Prometheus, Grafana и общая база Postgres для метаданных.
```bash
make up
make smoke
make check-clickhouse
make check-services
```
Первому знакомству нужны все три проверки на стенде: `make smoke` говорит, что
стенд собран, `make check-clickhouse` — что кластер работает кластером, а
`make check-services` — что Airflow запускает DAG, а Superset ходит в базу.
Дальше, в рабочей петле, обычно хватает `make smoke`.
Чтобы изменить образы, порты или учебные учётные данные, скопируйте образец:
```bash
@@ -62,17 +69,12 @@ make smoke
подготавливает администратора и подключение к `clickhouse-01`. Второй обновляет
Superset, создаёт администратора и импортирует подключение к `clickhouse-02`.
`make smoke` проверяет зависимости машины, здоровье контейнеров, устройство
keeper, Kafka через порт машины, три цели Prometheus, источник Grafana,
компоненты Airflow, ручной запуск пробников `test_clickhouse` и `test_kafka`,
метаданные и подключение Superset. Первый пробник создаёт
таблицы на обеих нодах и читает через `Distributed` на ноде 2 строку из
локальной таблицы ноды 1. Второй пишет в Kafka и читает свой маркер. В конце
`make smoke` за секунды спрашивает, собран ли стенд: зависимости машины,
здоровье контейнеров, устройство keeper, три цели Prometheus, источник Grafana,
компоненты Airflow и подготовленное подключение к `clickhouse-01`. В конце
проверка спрашивает у Docker, не убивало ли ядро что-нибудь в долгоживущих
контейнерах за нехватку памяти и не включалась ли политика перезапуска: убитый
контейнер Docker поднимает сам, и проверка состояния об этом промолчит.
Временный топик проверки с машины и запуски DAG удаляются;
постоянный топик пробника сохраняется, а старые записи чистит Kafka.
Одиннадцать проверок здоровья сразу после `make up --wait` повторяют то, чего
Compose уже дождался: у каждой долгоживущей службы есть своя `healthcheck`.
@@ -83,37 +85,25 @@ Compose уже дождался: у каждой долгоживущей слу
выглядит и без этого, поэтому смоук спрашивает у живого контейнера, дошли ли
объявленные настройки до процесса.
`make smoke-cluster` запускает отдельную глубокую проверку ClickHouse: описание
кластера, макросы, связь с keeper, `ReplicatedMergeTree`, `Distributed`, очередь
распределённых DDL и очистку временных таблиц.
`make check-services` проверяет то, ради чего приходится ждать службу: Kafka
через порт машины, ручной запуск пробников `test_clickhouse` и `test_kafka`,
вход в Superset, его метаданные и подключение к `clickhouse-02`. Первый пробник
создаёт таблицы на обеих нодах и читает через `Distributed` на ноде 2 строку из
локальной таблицы ноды 1. Второй пишет в Kafka и читает свой маркер. Временный
топик проверки с машины и запуски DAG удаляются; постоянный топик пробника
сохраняется, а старые записи чистит Kafka.
`make check-clickhouse` запускает отдельную глубокую проверку ClickHouse:
описание кластера, макросы, связь с keeper, `ReplicatedMergeTree`,
`Distributed`, очередь распределённых DDL и очистку временных таблиц.
`make config-test` проверяет Compose, синтаксис Bash и Python и пробельные
ошибки в diff без запуска стенда.
Правило, которое стоит держать в голове, правя любую из этих проверок:
**проверка, которая не умеет краснеть, бесполезна.** Проверка, никогда не
видевшая своей поломки, доказывает только то, что она умеет печатать «ЗЕЛЁНО».
Убедиться дешевле всего руками: сломайте то, что она стережёт — остановите
`prometheus`, удалите служебную таблицу пробника на второй ноде, — и посмотрите,
покраснеет ли прогон и назовёт ли виновника. Не покраснел — проверка не
работает, и чинить надо её, а не стенд.
### Какую проверку когда запускать
Проверки выстроены лесенкой: чем дороже прогон, тем больше связей он трогает.
- `make config-test` — секунды, стенд поднимать не нужно. Видит только то, что
есть в файлах, и о работоспособности не говорит ничего. Дёшево настолько, что
можно гонять перед каждым коммитом.
- `make lint` и `make test` — тоже секунды и тоже без стенда, но про другой
код: ruff и тесты генератора в `generator/`. Тесты сторожат контракт схемы
события и свежесть собранного из него описания выгрузки.
- `make smoke` — минута-две на поднятом стенде. Дороже, но проверяет связи
между службами, а не отдельные файлы: это интеграционная проверка.
- `make smoke-cluster` — около минуты. Одна связь, зато до дна: межнодовое
устройство ClickHouse.
Обычный рабочий цикл — `make config-test` и `make smoke`.
Обычный рабочий цикл — `make config-test` и `make smoke`; остальные цели гоняют
тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей
поднятый стенд, сколько стоит прогон и куда класть новую — в
[карте проверок](docs/architecture/testing.md).
Остановить контейнеры без удаления данных можно командой `make down`. Для
полного сброса с удалением всех именованных томов используйте `make clean`.
@@ -218,8 +208,10 @@ Superset закреплён на 6.1.0; драйвер `clickhouse-connect`, ф
- [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми
вариантами: почему сделано так, а не иначе.
- [docs/architecture/](docs/architecture/) — рабочие справочники по зонам
ответственности; сейчас это [хранилище](docs/architecture/storage.md):
конвенции имён, раскладка по шардам, приём событий, карта таблиц.
ответственности: [хранилище](docs/architecture/storage.md) — конвенции имён,
раскладка по шардам, приём событий, карта таблиц;
[проверки](docs/architecture/testing.md) — что утверждает каждая цель `make`
и куда класть новую проверку.
- [docs/research/](docs/research/) — исследования; сейчас это формат
кликстрима Яндекса, по которому строится модель события.
- [docs/formats/](docs/formats/) — описания форматов источников: по ним