diff --git a/README.md b/README.md index cf60bac..87610c4 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,27 @@ Superset, создаёт администратора и импортирует останавливает Prometheus с Kafka. Общая проверка должна назвать Prometheus и оба пробника, после чего завершиться с ошибкой. В конце стенд восстанавливается. +### Какую проверку когда запускать + +Проверки выстроены лесенкой: чем дороже прогон, тем больше связей он трогает. + +- `make config-test` — секунды, стенд поднимать не нужно. Видит только то, что + есть в файлах, и о работоспособности не говорит ничего. Дёшево настолько, что + можно гонять перед каждым коммитом. +- `make smoke` — минута-две на поднятом стенде. Дороже, но проверяет связи + между службами, а не отдельные файлы: это интеграционная проверка. +- `make smoke-cluster` — около минуты. Одна связь, зато до дна: межнодовое + устройство ClickHouse. +- `make smoke-guards` — около пяти минут, и отвечает на другой вопрос. Не + «работает ли стенд», а «умеют ли проверки падать»: она намеренно ломает стенд + и смотрит, покраснеет ли `make smoke` и назовёт ли виновника, потом чинит и + убеждается, что стенд снова зелёный. Отсюда и три прогона `make smoke` + внутри — до поломки, во время неё и после починки. + +Обычный рабочий цикл — `make config-test` и `make smoke`. `make smoke-guards` +нужна тому, кто правит сами проверки или пробники: без неё легко завести +проверку, которая зелена всегда. + Остановить контейнеры без удаления данных можно командой `make down`. Для полного сброса с удалением всех именованных томов используйте `make clean`. Повторный `make up` безопасен: одноразовая подготовка приложений идемпотентна. diff --git a/scripts/clickhouse-smoke.sh b/scripts/clickhouse-smoke.sh index 1baa7de..15432b9 100755 --- a/scripts/clickhouse-smoke.sh +++ b/scripts/clickhouse-smoke.sh @@ -10,10 +10,14 @@ compose() { docker compose --project-directory "$ROOT_DIR" "$@" } +# Ввод закрыт намеренно: у запроса INSERT clickhouse-client дочитывает данные +# из стандартного ввода и ждёт его конца. Если проверку запустили не из +# терминала, а из фонового процесса с открытым вводом, конца не наступает +# никогда, и команда висит без сообщений. query() { local service="$1" local sql="$2" - compose exec -T "$service" clickhouse-client --query "$sql" + compose exec -T "$service" clickhouse-client --query "$sql" &2 +fail() { + printf 'ОШИБКА: %s\n' "$1" >&2 exit 1 -elif [[ "$grep_status" -ne 1 ]]; then - printf 'ОШИБКА: не удалось проверить обозначение единицы памяти.\n' >&2 - exit 1 -fi -printf 'ЗЕЛЁНО: отчёт проверки использует русское обозначение ГБ.\n' +} -printf 'ИТОГ: пройдено 6, ошибок 0\n' +# check «утверждение» команда... — запускает команду и считает результат. +# Успех: «ЗЕЛЁНО: утверждение». Провал: «ОШИБКА: не подтвердилось: утверждение» +# и выход с кодом 1. Раньше проверки падали через `set -e` молча: код возврата +# был единственным следом, и какая именно проверка не прошла — не сообщалось. +check() { + local claim="$1" + shift + if "$@"; then + passed=$((passed + 1)) + printf 'ЗЕЛЁНО: %s\n' "$claim" + else + fail "не подтвердилось: $claim" + fi +} + +# Порты обеих нод. Ломается ровно тогда, когда порт поменяли в compose.yaml и +# забыли документацию — самая частая причина расхождения. +ports_documented() { + grep -Eq 'нода 1.*28123.*29000' "$README" && + grep -Eq 'нода 2.*28124.*29001' "$README" +} + +# Совет про сброс томов. Пароли Postgres и Grafana применяются при создании +# тома: без `make clean` смена значений в .env ничего не даёт, и человек +# полчаса ищет, почему его не пускает. +clean_advice_present() { + grep -Eq 'После первого запуска.*`make clean`' "$README" +} + +# Список портов остаётся единым списком. Совпадение точное намеренно: проверка +# стережёт не сам факт (он проверен выше), а то, что строку не выдернули из +# списка в отдельный абзац при правке соседнего текста. +ports_stay_one_list() { + grep -Fxq -- '- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`;' "$README" +} + +# Состав `make config-test`. Разбор пробников добавлен в него отдельной +# проверкой, и README должен называть её: иначе читатель считает, что дешёвая +# ступень трогает только Compose, и гоняет полный стенд ради того, что видно +# без него. Проверка стоит на двух соседних строках — см. ниже про перенос. +probe_checks_documented() { + awk ' + previous == "`make config-test` проверяет Compose, синтаксис Bash и Python, малые проверки" && + $0 == "логики пробников и пробельные ошибки в diff без запуска стенда." { + found = 1 + } + {previous = $0} + END {exit !found} + ' "$README" +} + +# Урок из предшественника: `make up` не трогает уже созданные контейнеры, и +# после правки настройки метрик серверы молча работают со старой +# конфигурацией. README обязан требовать явный перезапуск. Проверка сверяет +# две соседние строки целиком, а не подстроку: так фразу нельзя незаметно +# разорвать переносом или переписать наполовину. +restart_lesson_present() { + awk ' + previous == "После изменения `infra/clickhouse/config.d/prometheus.xml` выполните" && + $0 == "`docker compose restart clickhouse-01 clickhouse-02`: обычный `make up` не" { + found = 1 + } + {previous = $0} + END {exit !found} + ' "$README" +} + +# Единица памяти в отчёте проверки — русская «ГБ», а не латинская «GB» +# (контракт языка из AGENTS.md). Здесь успех — это отсутствие образца, поэтому +# код возврата grep разбирается вручную: 1 — не нашли, и это хорошо; 0 — нашли +# латинское; больше 1 — сам grep не отработал, и молчать об этом нельзя. +smoke_uses_russian_unit() { + local status=0 + grep -q '3,4 GB' "$SMOKE" || status=$? + case "$status" in + 1) return 0 ;; + 0) return 1 ;; + *) fail "не удалось проверить обозначение единицы памяти в $SMOKE" ;; + esac +} + +check 'README перечисляет HTTP- и нативные порты обеих нод' ports_documented +check 'README объясняет сброс томов после смены исходных учётных данных' clean_advice_present +check 'список портов остаётся единым списком' ports_stay_one_list +check 'README перечисляет малые проверки пробников в составе config-test' probe_checks_documented +check 'README требует перезапуск ClickHouse после изменения настройки метрик' restart_lesson_present +check 'отчёт проверки использует русское обозначение ГБ' smoke_uses_russian_unit + +printf 'ИТОГ: пройдено %d, ошибок 0\n' "$passed"