Files
mtusi2026lab6/Makefile
T
ricoromaandClaude Opus 5.5 509afca89e feat: telemetry cost profile with head sampling, coarse buckets and balanced tail sampling
- [telemetry] trace_sample_ratio (ParentBased(TraceIdRatioBased), 1 keeps
  ParentBased(ALWAYS_ON)) and metric_buckets (default|coarse with SLO bounds),
  export interval <= 30 s; otel.sdk.span.started, span.live dropped; startup
  records name ratio, buckets and interval
- bench: telemetry services on mtusi-bench, TELEMETRY=on switch for uploads
  and queue, make bench_telemetry[_quick] with off/full/full-aa/head/tail/
  metrics/balanced, rare events, lookup from Tempo/Loki/Prometheus, cost
  sampler, verdicts H1-H8 and B1-B5; collector layers and lean Prometheus in
  bench/otel with preflight checks
- REPORT: telemetry cost hypotheses and criteria before the label

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 19:17:25 +03:00

608 lines
34 KiB
Makefile
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
validate:
$(PYTHON) scripts/validate_openapi.py
test:
$(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS)
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# -------------------------
# Приложение на хосте (свои цели; цели skeleton выше не менять)
# -------------------------
# Postgres из compose и миграции, Valkey и S3 с bootstrap из compose,
# затем сервис на хосте: 127.0.0.1:APP__PORT, reload по src/
.PHONY: run_dev
run_dev: upgrade start_cache start_s3 start_broker
APP__RUN_MODE=console uv run python -m src
# worker в консоли: тот же .env, адреса на хосте; ключи worker — в окружение
# процесса (мост S3__* в .env — ключи API). @: значения в вывод не попадают
.PHONY: run_worker
run_worker:
@S3__ACCESS_KEY_ID="$(S3_WORKER_ACCESS_KEY)" S3__SECRET_ACCESS_KEY="$(S3_WORKER_SECRET_KEY)" APP__RUN_MODE=console uv run python -m src.worker
# relay публикации заданий в консоли: без него консольный API принимает файлы, а
# задания ждут в PostgreSQL. Брокер поднимает make run_dev; те же мосты .env
.PHONY: run_relay
run_relay:
@APP__RUN_MODE=console uv run python -m src.relay
# реестр failed и replay (design change pipeline-reliability, решение 5): без
# APPLY=1 только показ; с APPLY=1 выбор обязателен (ATTACHMENT, ERROR_CODE или
# REASON), иначе код 2. Коды: 0 — выполнено или показано, 3 — есть отказы, 1 —
# отказ PostgreSQL. ATTACHMENT — id вложения, можно несколько через пробел
OPERATOR ?= $(USER)
.PHONY: replay
replay:
@$(DC) run --rm --no-deps relay replay$(foreach id,$(ATTACHMENT), --attachment-id $(id))$(if $(ERROR_CODE), --error-code $(ERROR_CODE))$(if $(REASON), --reason $(REASON))$(if $(LIMIT), --limit $(LIMIT))$(if $(filter 1,$(APPLY)), --apply)$(if $(OPERATOR), --operator $(OPERATOR))
# шаблоны копируются только если файла ещё нет: локальные значения
# не затираются. В .env подставляются случайные пароли Postgres и
# Valkey и секреты S3: в шаблоне они пустые, общего секрета стенда в git
# нет. В существующий .env дописываются переменные шаблона, которых в нём
# нет (секреты — случайными, остальные — значениями шаблона), прежние
# строки не меняются (design change upload-consistency). Печатаются
# только имена, значения — нет
ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY GRAFANA_ADMIN_PASSWORD
# шаблон с подставленными секретами — в поток, не в вывод команды
ENV_FILLED = sed \
-e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \
-e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \
-e "s/^S3_ROOT_ACCESS_KEY=$$/S3_ROOT_ACCESS_KEY=$$(openssl rand -hex 10)/" \
-e "s/^S3_ROOT_SECRET_KEY=$$/S3_ROOT_SECRET_KEY=$$(openssl rand -hex 20)/" \
-e "s/^S3_JWT_SIGNING_KEY=$$/S3_JWT_SIGNING_KEY=$$(openssl rand -hex 32)/" \
-e "s/^S3_API_ACCESS_KEY=$$/S3_API_ACCESS_KEY=$$(openssl rand -hex 10)/" \
-e "s/^S3_API_SECRET_KEY=$$/S3_API_SECRET_KEY=$$(openssl rand -hex 20)/" \
-e "s/^S3_CLEANER_ACCESS_KEY=$$/S3_CLEANER_ACCESS_KEY=$$(openssl rand -hex 10)/" \
-e "s/^S3_CLEANER_SECRET_KEY=$$/S3_CLEANER_SECRET_KEY=$$(openssl rand -hex 20)/" \
-e "s/^S3_WORKER_ACCESS_KEY=$$/S3_WORKER_ACCESS_KEY=$$(openssl rand -hex 10)/" \
-e "s/^S3_WORKER_SECRET_KEY=$$/S3_WORKER_SECRET_KEY=$$(openssl rand -hex 20)/" \
-e "s/^RABBITMQ_DEFAULT_PASS=$$/RABBITMQ_DEFAULT_PASS=$$(openssl rand -hex 16)/" \
-e "s/^GRAFANA_ADMIN_PASSWORD=$$/GRAFANA_ADMIN_PASSWORD=$$(openssl rand -hex 16)/" \
.env.example
# строки NAME=… шаблона, имени которых в .env нет, — в конец .env под
# комментарием; в вывод — только имена
ENV_APPEND_MISSING = awk -F= ' \
BEGIN { \
while ((getline line < ".env") > 0) \
if (line ~ /^[A-Za-z_][A-Za-z0-9_]*=/) { split(line, kv, "="); have[kv[1]] = 1 }; \
close(".env"); \
} \
/^[A-Za-z_][A-Za-z0-9_]*=/ && !($$1 in have) { \
if (!added++) printf "\n\# added by make env_setup from .env.example\n" >> ".env"; \
print >> ".env"; names = names " " $$1 \
} \
END { if (added) print "added to existing .env:" names }'
.PHONY: env_setup
env_setup:
@if [ ! -f .env ]; then \
$(ENV_FILLED) > .env; \
echo "new .env with random $(ENV_SECRETS)"; \
else \
$(ENV_FILLED) | $(ENV_APPEND_MISSING); \
fi
@test -f config.toml || cp config_example.toml config.toml
@echo "env ready: .env, config.toml"
# -------------------------
# Docker targets
# -------------------------
# порты — из того же .env, что читает compose; без .env — 8080
-include .env
APP__PORT ?= 8080
APP_OUT_PORT ?= 8080
# число реплик api за HAProxy — то же, что deploy.replicas в compose
API_REPLICAS ?= 2
# сколько реплик за BASE_URL ждут тесты реплик student-tests: против
# стенда с LB — API_REPLICAS, против одного процесса — 1 (их пропуск)
EXPECT_REPLICAS ?= $(API_REPLICAS)
DC=docker compose
# стенд: postgres, valkey, s3, rabbitmq -> migrate, s3-bootstrap -> api ×
# API_REPLICAS, cleaner, worker -> haproxy; телеметрия — otel-collector,
# prometheus, loki, tempo, grafana (приложение их не ждёт)
# (единственный порт API на хосте — у haproxy). env_setup создаёт
# недостающие .env и config.toml из шаблонов: без config.toml compose не
# запустится (bind с create_host_path: false), без паролей — тоже.
# Реплики, чей образ изменился, пересоздаются все разом (простой); новый
# код без простоя — make rolling_update
.PHONY: run_docker
run_docker: env_setup
DOCKER_BUILDKIT=1 $(DC) build
$(DC) up -d
.PHONY: stop
stop:
$(DC) stop
# контейнеры удаляются, volume с данными остаётся (удаление — wipe_data)
.PHONY: down
down:
$(DC) down
# журнал всех реплик api без префикса "api-1 |": каждая строка — JSON,
# реплику называет поле instance_id
.PHONY: logs
logs:
$(DC) logs -f --no-log-prefix api
# -------------------------
# PostgreSQL и миграции
# -------------------------
# Postgres стенда; --wait ждёт его healthcheck
.PHONY: start_db
start_db: env_setup
$(DC) up -d --wait postgres
.PHONY: stop_db
stop_db:
$(DC) stop postgres
# миграции с хоста: 127.0.0.1:POSTGRES_OUT_PORT из .env
.PHONY: upgrade
upgrade: start_db
uv run alembic upgrade head
# новая ревизия autogenerate; база сначала доводится до head, иначе
# autogenerate сравнит модели не с той схемой
.PHONY: revision
revision: upgrade
@read -p "Сообщение миграции (англ., прошедшее время): " msg; \
uv run alembic revision --autogenerate -m "$$msg"
# удалить контейнеры стенда и volumes с данными: только после ввода yes
.PHONY: wipe_data
wipe_data:
@project=$$($(DC) config | sed -n 's/^name: //p'); \
volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \
read -p "Удалить все данные стенда (volumes Postgres, S3, брокера и хранилищ телеметрии: $$volumes)? Введите yes: " answer; \
if [ "$$answer" = "yes" ]; then \
$(DC) down -v --remove-orphans; \
else \
echo "cancelled, nothing removed"; exit 1; \
fi
# -------------------------
# Valkey (кэш карточек чатов)
# -------------------------
# Valkey стенда; --wait ждёт его healthcheck. Volume нет: кэш после
# рестарта пуст, данные — в PostgreSQL
.PHONY: start_cache
start_cache: env_setup
$(DC) up -d --wait valkey
.PHONY: stop_cache
stop_cache:
$(DC) stop valkey
# -------------------------
# S3 (SeaweedFS, байты вложений)
# -------------------------
# S3 стенда и его bootstrap: --wait ждёт healthcheck сервера, но
# одноразовый сервис считает готовым уже запущенным, поэтому bootstrap —
# отдельным up с его кодом выхода (как миграции в rolling-update.sh)
.PHONY: start_s3
start_s3: env_setup
$(DC) up -d --wait s3
$(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap
# плавная остановка ~15 с (stop_grace_period 20 с)
.PHONY: stop_s3
stop_s3:
$(DC) stop s3
# брокер стенда: --wait ждёт healthcheck; данные — в volume rabbitmq_data
.PHONY: start_broker
start_broker: env_setup
$(DC) up -d --wait rabbitmq
.PHONY: stop_broker
stop_broker:
$(DC) stop rabbitmq
# проверка приватности bucket вне API на запущенном стенде: права ключа
# API, чужой bucket и административные запросы (bootstrap в режиме check),
# анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети;
# таблица «проверка → ожидаемо → получено», проверочные объекты и bucket
# удаляются. Код 1 — нарушение
.PHONY: s3_check
s3_check:
$(PYTHON) .claude/skills/run-mtusi-messenger/driver.py s3-check
# разовая сверка bucket и БД в контейнере уборщика (образ собирает
# make run_docker): по умолчанию dry-run — отчёт без изменений; APPLY=1 —
# исправить, MAX_CHANGES=N — предел изменений прохода вместо [reconciler]
# max_changes; STRATEGY=head — HEAD на строку вместо страниц, DEEP=1 —
# глубокая (SHA-256 содержимого), RATE=R — предел скорости, объектов S3 в
# секунду (0 — без предела) вместо [reconciler] max_objects_per_second.
# Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 — конфигурация
# (design change track2-reconciler, решения 1 и 8; track2-reconcile-cost,
# решения 4–6)
.PHONY: reconcile
reconcile:
$(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES))$(if $(STRATEGY), --strategy $(STRATEGY))$(if $(filter 1,$(DEEP)), --deep)$(if $(RATE), --max-objects-per-second $(RATE))
# -------------------------
# Реплики за балансировщиком (HAProxy)
# -------------------------
# вернуть остановленные реплики (scripts/stop-one.sh) и выставить их
# число: остановленные контейнеры запускаются с теми же ID, недостающие
# создаются, лишние удаляются; ждёт healthcheck реплик. Разовая подмена —
# make replicas API_REPLICAS=3, следующий make run_docker вернёт число
# из .env
.PHONY: replicas
replicas:
$(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api
# поочерёдная замена реплик на новый образ без простоя
# (scripts/rolling-update.sh): сборка, миграции один раз, затем по одной —
# новая реплика UP в LB, старая выводится из LB (drain), дорабатывает
# запросы, останавливается и удаляется. COMMIT=<commit> — образ из файлов
# commit (git archive, рабочее дерево не трогается), MIGRATE=0 — без
# миграций (откат на прежний образ: схема только расширялась). Нужен
# штатный стенд: API_REPLICAS реплик, все UP (make replicas)
COMMIT ?=
MIGRATE ?= 1
.PHONY: rolling_update
rolling_update:
API_REPLICAS=$(API_REPLICAS) ROLLOUT_COMMIT="$(COMMIT)" ROLLOUT_MIGRATE=$(MIGRATE) scripts/rolling-update.sh
# распределение запросов одной сессии через LB: вход одним синтетическим
# пользователем, серия GET /users/me с одним токеном, X-Instance-Id каждого
# ответа и число ответов каждой реплики
.PHONY: instances
instances:
$(PYTHON) .claude/skills/run-mtusi-messenger/driver.py --port $(APP_OUT_PORT) instances
# состояние реплик глазами HAProxy: занятые слоты, адрес, статус проверки,
# соединения, запросы, ошибки соединения, повторы и перенаправления. CSV
# статистики читается изнутри контейнера LB: порт 8404 наружу не
# опубликован, curl в образе нет, bash есть
LB_STATS_FIELDS = svname addr status check_status scur stot econ wretr wredis hrsp_5xx
.PHONY: lb_stats
lb_stats:
@$(DC) exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/8404 && printf "GET /stats;csv HTTP/1.0\r\n\r\n" >&3 && cat <&3' \
| awk -F, -v fields="$(LB_STATS_FIELDS)" ' \
/^# pxname/ { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$$i] = i; \
n = split(fields, f, " "); for (j = 1; j <= n; j++) printf "%s\t", f[j]; print ""; next } \
$$1 != "api" { next } \
$$2 != "BACKEND" && $$(col["addr"]) == "" && $$(col["status"]) == "MAINT (resolution)" { free++; next } \
{ for (j = 1; j <= n; j++) { v = $$(col[f[j]]); printf "%s\t", (v == "" ? "-" : v) }; print "" } \
END { printf "free slots: %d\n", free }' \
| column -t -s "$$(printf '\t')"
# -------------------------
# Load benchmark
# -------------------------
BENCH_LABEL ?= baseline
# macOS не засыпает на время замера (сон ставит ВМ Docker на паузу посреди
# прогона): -u будит из DarkWake полностью, -i и -s не дают уснуть до
# конца; на других ОС caffeinate нет, и префикс пустой
KEEP_AWAKE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu)
# полная матрица на своём проекте compose mtusi-bench (API, PostgreSQL,
# Valkey, без портов хоста), с фоновыми чатами разного размера, вариантами
# плана и пробами записи, ~35 мин; метка не должна существовать;
# результаты и планы запроса истории — evidence/bench/$(BENCH_LABEL)/,
# ход — строки в терминале и progress.json
.PHONY: bench
bench:
$(KEEP_AWAKE) uv run python bench/run.py --profile full --label $(BENCH_LABEL)
# самопроверка стенда на малых размерах, ~3 мин; результат в git не идёт
.PHONY: bench_quick
bench_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ)
RESTORE_LABEL ?= restore
# трек 2: backup под записью, восстановление в новое хранилище, сверка БД и
# через HTTP, кэш до и после FLUSHALL — на 10k / 100k / 500k с фоновыми
# чатами, без матрицы прогонов, ~20 мин; результат —
# evidence/bench/$(RESTORE_LABEL)/
.PHONY: bench_restore
bench_restore:
$(KEEP_AWAKE) uv run python bench/run.py --profile restore --label $(RESTORE_LABEL)
# то же на малых размерах (самопроверка, сценарий защиты), ~1,5 мин; в git
# не идёт
.PHONY: bench_restore_quick
bench_restore_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ)
FAILOVER_LABEL ?= baseline
# уровень 4: отказ реплик под нагрузкой на стенде mtusi-bench (HAProxy, две
# реплики с лимитами рабочего стенда): 100 записей с ключом и 100 чтений в
# секунду, каждая реплика в режимах stop, kill и pause с возвратом,
# посекундная шкала, время обнаружения и восстановления, сверка записей,
# CPU и память по компонентам и окнам (сэмплер); ~6 мин; результат —
# evidence/failover/$(FAILOVER_LABEL)/
.PHONY: bench_failover
bench_failover:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover --label $(FAILOVER_LABEL)
# то же короче, режимы stop и kill (самопроверка), с CPU и памятью по
# компонентам и окнам (сэмплер), ~2 мин; в git не идёт
.PHONY: bench_failover_quick
bench_failover_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover_quick --label quick-failover-$(shell date -u +%Y%m%dT%H%M%SZ)
ROLLOUT_LABEL ?= baseline
# уровень 4: поочерёдная замена реплик под нагрузкой на стенде mtusi-bench
# (HAProxy, две реплики с лимитами рабочего стенда): реплики стартуют на
# образе прежнего commit (Profile.rollout_from), посреди 100 записей с
# ключом и 100 чтений в секунду scripts/rolling-update.sh меняет их на
# образ текущего checkout; посекундная шкала, шаги по репликам, сверка
# записей, CPU и память по компонентам и окнам (сэмплер); ~3 мин;
# результат — evidence/rollout/$(ROLLOUT_LABEL)/
.PHONY: bench_rollout
bench_rollout:
$(KEEP_AWAKE) uv run python bench/run.py --profile rollout --label $(ROLLOUT_LABEL)
# то же с короткими окнами (самопроверка), с CPU и памятью по компонентам и
# окнам (сэмплер), ~2 мин; в git не идёт
.PHONY: bench_rollout_quick
bench_rollout_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile rollout_quick --label quick-rollout-$(shell date -u +%Y%m%dT%H%M%SZ)
UPLOADS_LABEL ?= baseline
# выключатель телеметрии профилей загрузок и очереди (лаба 6, design change
# track1-telemetry-cost, решение 13): on — Collector, Prometheus, Loki и Tempo
# рабочего стенда и SDK реплик, worker и relay; по умолчанию off — методика
# прежняя. Режим — в паспорте и сводке, продолжение RESUME=1 — в том же режиме
TELEMETRY ?= off
# уровень 4 лабы 4: память реплики при одновременных загрузках на стенде
# mtusi-bench (HAProxy, одна реплика 1 CPU / 512 МБ без swap, S3 рабочего
# стенда): варианты «до» (Profile.uploads_before), «без лимита» и «с
# лимитом» × тела 1 и 10 MiB × 1/10/20/40 клиентов × 3 повтора, на каждый
# прогон — новые S3 и реплика; пик памяти окна, OOM, ответы по кодам,
# загрузок/с; ~50 мин; результат — evidence/uploads/$(UPLOADS_LABEL)/.
# TELEMETRY=on|off — выключатель телеметрии стенда
.PHONY: bench_uploads
bench_uploads:
$(KEEP_AWAKE) uv run python bench/run.py --profile uploads --label $(UPLOADS_LABEL) --telemetry $(TELEMETRY)
# то же коротко (самопроверка): «без лимита» и «с лимитом», 10 MiB, 1/10/40
# клиентов, один повтор, ~5 мин; в git не идёт
.PHONY: bench_uploads_quick
bench_uploads_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile uploads_quick --label quick-uploads-$(shell date -u +%Y%m%dT%H%M%SZ) --telemetry $(TELEMETRY)
# Очередь под перегрузкой (лаба 5, трек 1; design change track1-queue-overload):
# стенд mtusi-bench с S3, брокером, relay, worker и уборщиком, настройки
# конкуренции и prefetch × классы изображений × 3 повтора и блоки предела, приёма,
# второго worker и рестартов, на каждую ячейку — свежий стенд; ~2 ч 10 мин;
# результат — evidence/queue/$(QUEUE_LABEL)/. RESUME=1 — продолжить прерванную метку
# на том же commit; TELEMETRY=on|off — выключатель телеметрии стенда
QUEUE_LABEL ?= baseline
.PHONY: bench_queue
bench_queue:
$(KEEP_AWAKE) uv run python bench/run.py --profile queue --label $(QUEUE_LABEL) $(if $(RESUME),--resume) --telemetry $(TELEMETRY)
# то же коротко (самопроверка, защита): две настройки, предел с пределом 40 и без
# него, рестарт worker, второй worker, окна короче, ~11 мин; в git не идёт
.PHONY: bench_queue_quick
bench_queue_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile queue_quick --label quick-queue-$(shell date -u +%Y%m%dT%H%M%SZ) --telemetry $(TELEMETRY)
# Цена наблюдаемости (лаба 6, трек 1; design change track1-telemetry-cost):
# стенд mtusi-bench профиля очереди и, в вариантах с телеметрией, Collector,
# Prometheus, Loki и Tempo рабочего стенда; варианты off, full, full-aa, head,
# tail, metrics, balanced × 3 повтора кругами, свежий стенд на прогон, одинаковая
# открытая нагрузка и редкие события; ~1 ч 50 мин; результат —
# evidence/telemetry-cost/$(TELEMETRY_LABEL)/. RESUME=1 — продолжить прерванную
# метку на том же commit; VARIANTS=a,b — отладка (переопределение в паспорте)
TELEMETRY_LABEL ?= baseline
.PHONY: bench_telemetry
bench_telemetry:
$(KEEP_AWAKE) uv run python bench/run.py --profile telemetry --label $(TELEMETRY_LABEL) $(if $(RESUME),--resume) $(if $(VARIANTS),--variants $(VARIANTS))
# то же коротко (калибровка, защита «для 5»): все варианты, кроме копии A/A, по
# одному разу, окна 10 + 30 + 15 с, ~20 мин; VARIANTS=off,full,tail — ~10 мин;
# в git не идёт
.PHONY: bench_telemetry_quick
bench_telemetry_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile telemetry_quick --label quick-telemetry-$(shell date -u +%Y%m%dT%H%M%SZ) $(if $(VARIANTS),--variants $(VARIANTS))
RECONCILE_LABEL ?= baseline
# трек 2 «5» лабы 4: стоимость сверки bucket и БД на стенде mtusi-bench
# (HAProxy, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего
# стенда, разовые проходы уборщика 0,25 CPU / 256 МБ, в управляемом опыте
# 1 CPU): наполнение мимо API, этапы 1 000 × 1 MiB и 10k → 30k → 100k ×
# 4 KiB, стратегии batch и head, глубокая сверка, фоновая нагрузка с
# пределом скорости и без, отказ по пределу на образе до change
# (Profile.reconcile_before) и checkout, 3 повтора; ~50 мин; результат —
# evidence/reconcile/$(RECONCILE_LABEL)/ (design change track2-reconcile-cost)
.PHONY: bench_reconcile
bench_reconcile:
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile --label $(RECONCILE_LABEL)
# то же коротко (самопроверка): 2 000 × 4 KiB, по одному проходу каждого
# вида, окна под нагрузкой по 5 с, отказ по пределу с 300 кандидатами,
# ~4 мин (3,7 мин на шумном хосте, 2026-10-23); в git не идёт
.PHONY: bench_reconcile_quick
bench_reconcile_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile reconcile_quick --label quick-reconcile-$(shell date -u +%Y%m%dT%H%M%SZ)
SCALING_LABEL ?= scaling-$(SERIES)
# уровень 5, трек 1 «Цена масштабирования»: серия на стенде mtusi-bench —
# SERIES=a (бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1, ~50 мин), b (1…6 реплик по
# 1 CPU, ~100 мин), pool (4 реплики при max_connections 100 и 50, ~35 мин),
# ab (1 × 1 и 6 × 1 для «до/после» и A/A, ~35 мин), db (1, 2, 4 реплики при
# узком лимите CPU PostgreSQL и контроль 4 × 1 при 2 CPU, ~50 мин), db4
# (из серии db только 4 × 1 при 0,5 и 2 CPU, ~25 мин), db_quick
# (самопроверка серии db, ~5 мин, метка quick-*); каждая ячейка — свежий
# стенд, открытая модель, поиск R* по SLO; результат —
# evidence/bench/$(SCALING_LABEL)/. RESUME=1 — продолжить прерванную метку
# на том же commit
.PHONY: bench_scaling
bench_scaling:
@if [ -z "$(SERIES)" ]; then \
echo "SERIES is required: make bench_scaling SERIES=a|b|pool|ab|db|db4|quick|db_quick [SCALING_LABEL=...] [RESUME=1]"; \
exit 2; \
fi
$(KEEP_AWAKE) uv run python bench/run.py --profile scaling_$(SERIES) --label $(SCALING_LABEL) $(if $(RESUME),--resume)
# самопроверка серий: две ячейки (1 × 1 и 2 × 1 при max_connections 50),
# короткие окна, ~5 мин; в git не идёт
.PHONY: bench_scaling_quick
bench_scaling_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile scaling_quick --label quick-scaling-$(shell date -u +%Y%m%dT%H%M%SZ)
PLOTS ?= scaling
# графики и сводка серий трека 1 из меток LABELS (через пробел):
# R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка
# насыщения; результат — evidence/plots/$(PLOTS)/, пересоздаётся
.PHONY: bench_plots
bench_plots:
uv run python bench/plots.py --labels "$(LABELS)" --out "$(PLOTS)"
# дельта двух меток по ячейкам матрицы или, у серий трека 1, по общим
# конфигурациям: BEFORE и AFTER обязательны, AA — метка того же кода, что
# BEFORE, для уровня шума; CHANGE — change, к которому относится сравнение
# серий (шапка таблицы, по умолчанию scaling-bench);
# результат — evidence/compare/$(BEFORE)__$(AFTER).md
.PHONY: bench_compare
bench_compare:
uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" --aa "$(AA)" $(if $(CHANGE),--change "$(CHANGE)")
# «до» и «после» подряд в одной сессии, два прогона bench: bench для
# BEFORE, commit доказательств, git revert commit REAPPLY (возврат
# откаченного изменения), затем bench для AFTER. С SERIES=<серия> вместо
# полной матрицы — серия трека 1 (make bench_scaling). Сам делает два
# коммита; рабочее дерево должно быть чистым
.PHONY: bench_ab
bench_ab:
$(KEEP_AWAKE) uv run python bench/ab.py --before "$(BEFORE)" --after "$(AFTER)" --reapply "$(REAPPLY)" $(if $(SERIES),--series "$(SERIES)")
# -------------------------
# Observability
# -------------------------
PROMETHEUS_DIR = infra/otel/prometheus
# правила Prometheus без стенда и без сети (design change slo-alerts, решение
# 11): файлы infra/otel/prometheus/ — tar в одноразовый контейнер
# закреплённого образа Prometheus (образ — из docker-compose.yml), там promtool
# check config, check rules и test rules; затем у каждого оповещения есть
# runbook_url, и каждый названный runbook — файл в git. Через stdin, а не bind
# mount: так же работает в CI (job не видит своих файлов на хосте Docker)
.PHONY: alerts_test
alerts_test:
@image=$$(sed -n 's/^ *image: *\(prom\/prometheus:[^ ]*\).*$$/\1/p' docker-compose.yml | head -n 1); \
if [ -z "$$image" ]; then echo "prometheus image is not found in docker-compose.yml"; exit 2; fi; \
echo "promtool from $$image"; \
tar -C $(PROMETHEUS_DIR) -cf - prometheus.yml rules.yml rules.test.yml | \
docker run --rm -i --network none --entrypoint sh "$$image" -c \
'set -e; cd /etc/prometheus; tar -xf -; promtool check config prometheus.yml; promtool check rules rules.yml; promtool test rules rules.test.yml'
@alerts=$$(grep -c '^ *- alert:' $(PROMETHEUS_DIR)/rules.yml); \
urls=$$(grep -c '^ *runbook_url:' $(PROMETHEUS_DIR)/rules.yml); \
if [ "$$alerts" -ne "$$urls" ]; then echo "alerts: $$alerts, runbook_url: $$urls"; exit 1; fi; \
missing=0; \
for path in $$(sed -n 's/^ *runbook_url: *//p' $(PROMETHEUS_DIR)/rules.yml); do \
if [ -f "$$path" ]; then echo "runbook $$path: ok"; else echo "runbook $$path: MISSING"; missing=1; fi; \
done; \
if [ "$$missing" -ne 0 ]; then exit 1; fi; \
echo "alerts: $$alerts, each with an existing runbook"
# -------------------------
# Common targets
# -------------------------
# собственные black-box тесты против запущенного сервера (BASE_URL).
# EXPECT_REPLICAS — сколько реплик за BASE_URL: по умолчанию API_REPLICAS
# (стенд с LB); против одного процесса — EXPECT_REPLICAS=1, и тесты
# реплик пропускаются с причиной
.PHONY: student_test
student_test:
BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest
# быстрые тесты сервисов на фейках: без PostgreSQL, Valkey, S3, брокера, docker
# и сети (design change unit-of-work, решение 13). Каталог вне student-tests:
# правило black-box там прежнее
.PHONY: service_test
service_test:
uv run pytest -c service-tests/pytest.ini service-tests/unit
# настоящая единица работы, тот же набор условий repo на SQL и общий срок запроса
# на временной базе test_uow_<db> в PostgreSQL стенда; база создаётся и мигрирует
# в начале, удаляется при любом исходе, рабочая база не затрагивается
.PHONY: service_test_db
service_test_db: start_db
uv run pytest -c service-tests/pytest.ini service-tests/db
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу и объекты
# S3 для разбора. Valkey и S3 общие с рабочим стендом: ключи кэша и
# объектов разделены именем базы, префикс test_<db>/ удаляется при уборке.
# $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку
.PHONY: test_isolated
test_isolated: env_setup start_db start_cache start_s3 start_broker
$(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,)
# проверки отказов (pytest -m fault) на отдельном стенде: свой проект
# compose <рабочий>-failures со своими Postgres и Valkey, обычный и
# «тесный» API, hook student-tests/fault_hook.py; стенд и его volume
# удаляются при любом исходе, рабочий стенд не затрагивается.
# FAULT_ARGS — дополнительные аргументы pytest, например -k "Valkey"
.PHONY: failure_checks
failure_checks: env_setup
$(PYTHON) student-tests/run_failures.py $(FAULT_ARGS)
.PHONY: lint
lint:
@ruff format .
@echo "code formatted"
@ruff check --fix .
@echo "code checked and fixed if needed"
@ruff format .
@echo "code formatted"
@ruff check --fix .
@echo "code checked and fixed if needed"