forked from mtusi2026/mtusi2026lab6
Автор / группа: ivanstorozhev, БВТ2304 Целевая оценка (3/4/5): 4 Трек 5, если заявлен: не заявлен Что реализовано и что перенесено: из lab5 перенесены Spring Boot API, PostgreSQL, Redis-кэш сессий, Argon2id, Liquibase через одноразовый сервис migrate, HAProxy без sticky session, две реплики, X-Instance-Id, обязательный Idempotency-Key, scripts/stop-one.sh и scripts/restart.sh, приватный SeaweedFS, ответ 202, staging, transactional outbox, отдельный worker, Kafka 3.9.1 (KRaft, volume kafka-data), состояния queued/processing/ready/failed, JPEG thumbnail и crop, lossy WebP, retry с backoff и jitter, топик attachments.failed, явный replay и lease. Оригинал принимается в S3 в одной транзакции со строкой outbox. Worker коммитит смещение только после записи вариантов в фиксированные ключи. Сообщение брокера содержит идентификаторы и W3C traceparent, без тела сообщения и ключа объекта. Добавлены OTLP из API и worker в Collector 0.139.0, Prometheus v3.2.1, Loki 3.4.2, Tempo 2.7.2 и Grafana 11.6.1. Producer-спан и consumer-спан связаны через заголовок Kafka. Повторная попытка остаётся в том же trace. Дашборд messenger-lab6 считает p50/p95/p99 через histogram_quantile по сумме бакетов и делит миллисекунды на 1000. SLI доступности — доля 5xx на обычных маршрутах, SLO 99% за 5 минут. SLI очереди — возраст самого старого queued или processing, SLO меньше 30 с. Алерты messenger-error-rate и messenger-queue-lag проверяются локально, без внешней доставки. memory_limiter 192 MiB и очереди экспортёров на 256 записей сбрасывают телеметрию, если хранилище недоступно. Команды запуска из чистого clone: cp .env.example .env docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build curl -fsS http://127.0.0.1:8080/health/ready make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh docker compose --env-file .env start api python3 scripts/grade6-evidence.py Результаты проверок и ссылка на REPORT.md: подробности и числа в REPORT.md make check — PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. make test — PASS: lab6 public API scenario; infrastructure and grading evidence remain separate. python3 scripts/grade6-evidence.py — PASS. Загрузка bf19675a-7d93-4379-a708-1e5efc7366a7, trace d27d941c741436ad51a3b35c2921ca4d: HTTP-спан родитель s3.PutObject, JDBC и attachments.process publish; process — ребёнок publish; S3 и JDBC worker — дети process. Тот же trace_id в логе API attachment.accepted и в логе worker job.ready, и в Loki. Повтор ac1e1581-4d24-4789-a887-c14a1852581a в trace 5540712fa2d49096df09db864f9ad9a8: два publish и два process, S3 worker только на второй попытке, итог ready. До аварий p50 0.039 с, p95 0.132 с, p99 0.134 с по гистограмме за 5 минут. slow-db: JDBC query 3013 мс; slow-handler: сервер 3026 мс и ни одного JDBC-спана. Остановка worker: возраст очереди 75.5 с, алерт Alerting, после старта то же вложение ready и алерт Normal. 608 ответов 500: доля 1 и Alerting, после тишины доля 0 и Normal. При остановленных Prometheus, Loki и Tempo сообщение получило 201, вложение стало ready, память collector 100 → 98.87 MiB при лимите 320 MiB, 32 строки ошибки экспорта. mvn -q test в backend/ — код выхода 0, 22 теста, 0 failures, 0 errors. Ограничения / известные ошибки: трек 5 не делался. Один Docker-хост, единственные PostgreSQL, Redis, SeaweedFS, Kafka, Loki, Tempo и Prometheus остаются точками отказа. Replication factor топиков равен 1. Доставка at least once: повтор перезаписывает те же ключи, но это не exactly-once на стороне S3. Пока хранилище телеметрии лежит, часть спанов и строк отбрасывается; после возвращения дырка в этом интервале остаётся. Шаг метрик 10 с, поэтому короткий pg_sleep может не попасть в hikaricp_connections_pending; различие снято по спанам. Staging failed-задания хранится сутки; позже replay уже не находит байты. Пока HAProxy не снял backend, часть запросов на останавливаемую реплику завершается ошибкой соединения; повтор с тем же Idempotency-Key безопасен для отправки сообщения. Источники и использование ИИ: контракт contracts/openapi.json, contracts/README.md, contracts/observability.md, contracts/jobs.schema.json; код lab5; Spring Boot 4.1.1, Spring Data JPA, spring-security-crypto, Spring Data Redis, Spring Kafka, Liquibase, Actuator, OpenTelemetry, opentelemetry-logback-appender 2.28.1-alpha, datasource-micrometer-spring-boot 2.3.0, MapStruct 1.6.3, OpenAPI Generator 7.17.0, AWS SDK for Java 2.31.50, Thumbnailator 0.4.20, webp-imageio 0.11.0, Bouncy Castle, PostgreSQL 16.10, Redis 7.4.6, HAProxy 3.2.6, SeaweedFS 4.52, Apache Kafka 3.9.1, Collector 0.139.0, Prometheus v3.2.1, Loki 3.4.2, Tempo 2.7.2, Grafana 11.6.1, Testcontainers. Помощь ИИ использована при переносе lab5, инструментации и отчёте. Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. Контракт и публичные тесты не ослаблены. make check и make test выполнены; приложен реальный вывод. Сценарии отказов своего уровня воспроизведены. Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
121 lines
20 KiB
Markdown
121 lines
20 KiB
Markdown
# Отчёт — лабораторная 6
|
||
|
||
- Автор, группа: ivanstorozhev, БВТ2304
|
||
- Целевая оценка: 4
|
||
- Трек 5: не выбран
|
||
- Commit/PR: локальная работа, ещё не публиковалась
|
||
- Использованные источники, библиотеки и помощь ИИ: контракт `contracts/openapi.json`, `contracts/observability.md`, `contracts/jobs.schema.json`. Код lab5 перенесён как основа (Spring Boot 4.1.1, Spring Data JPA, Liquibase, Redis, HAProxy, Kafka 3.9.1, SeaweedFS 4.52, Argon2id). Наблюдаемость: Spring Boot OpenTelemetry, OTLP-логгер `opentelemetry-logback-appender` 2.28.1-alpha, JDBC-наблюдения `datasource-micrometer-spring-boot` 2.3.0, Collector 0.139.0, Prometheus v3.2.1, Loki 3.4.2, Tempo 2.7.2, Grafana 11.6.1. Помощь ИИ: перенос lab5, инструментация и отчёт.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Desktop (проверено 28.5.1), Docker Compose и Python 3.9+. JDK 21 и Maven 3.9 нужны только для `mvn test` вне образа. На этой машине JDK — `/opt/homebrew/opt/openjdk@21`.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
# Перед общим стендом замените учебные пароли PostgreSQL, ключи S3 и пароль Grafana в .env.
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
curl -fsS http://127.0.0.1:8080/health/ready
|
||
make test
|
||
python3 scripts/grade6-evidence.py
|
||
```
|
||
|
||
Образ приложения — `messenger-lab6:1.0.0`, `pull_policy: never`. Сервис `migrate` применяет Liquibase и завершается с кодом 0. У миграции экспорт телеметрии выключен, чтобы процесс не ждал Collector. Реплики `api` и `worker` стартуют после миграции с `SPRING_LIQUIBASE_ENABLED=false`.
|
||
|
||
Остановка без удаления данных: `docker compose --env-file .env stop`. Снятие контейнеров с сохранением volumes: `docker compose --env-file .env down`. Намеренное удаление учебных данных: `docker compose --env-file .env down -v`. Файл `.env` в Git не входит.
|
||
|
||
Свои проверки: `JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -f backend/pom.xml test`. Testcontainers поднимает PostgreSQL, Redis, Kafka и SeaweedFS. В этом прогоне 22 теста, 0 ошибок.
|
||
|
||
Наружу опубликованы только `127.0.0.1:8080` (HAProxy), `127.0.0.1:9090` (Prometheus) и `127.0.0.1:3000` (Grafana). Loki, Tempo и Collector остаются в сети стенда.
|
||
|
||
## Архитектура и решения
|
||
|
||
Клиент ходит только в HAProxy. Две реплики `api` портов наружу не публикуют. Пользователи, чаты, сообщения, сессии и идемпотентность те же, что в lab5: PostgreSQL — источник истины, Redis — кэш разбора Bearer.
|
||
|
||
`POST /api/v1/chats/{chat_id}/attachments` проверяет тип и размер, пишет байты в `staging/{id}` и в одной транзакции сохраняет строку `attachments` (`queued`) и строку `job_outbox`. Ответ — 202. В брокер на этом шаге ещё ничего не уходит. Публикацию делает цикл outbox: строка берётся `FOR UPDATE SKIP LOCKED`, запись уходит в топик `attachments.process` с `acks=all`, и только потом ставится `published_at`. Worker коммитит смещение Kafka только после записи исхода в PostgreSQL. Оригинал и производные пишутся в фиксированные ключи. Повтор перезаписывает те же ключи и те же строки `attachment_variants`.
|
||
|
||
Состояния: `queued`, `processing`, `ready`, `failed`. Пока вложение не `ready`, `GET .../content` отвечает 409. Временная ошибка возвращает задание в `queued` с задержкой от половины `JOB_BACKOFF_BASE_MS` до всей базы. Постоянная ошибка сразу даёт `failed`. Для демонстрации retry worker один раз читает и удаляет файл `/tmp/messenger-fail-transient`.
|
||
|
||
В JSON задания добавлены необязательные `traceparent` и `tracestate`. Они уже были в `contracts/jobs.schema.json`. Тело сообщения, пароль, токен и ключ объекта в задание и в метрики не попадают. `attachment_id` есть в логе и в трассировке, потому что по нему находится одна загрузка. Меткой метрики он не является.
|
||
|
||
Трассировка W3C. HTTP-спан загрузки записывает `traceparent` в задание. Поздний outbox поднимает producer-спан `attachments.process publish` как потомка этого контекста и кладёт заголовок в Kafka. Consumer-спан `attachments.process process` — потомок producer. При retry текущий consumer-спан снова записывается в новое задание, поэтому вторая публикация остаётся в том же trace. S3-спаны `s3.PutObject` и `s3.GetObject` создаются только внутри уже открытого спана и не содержат ключ объекта. JDBC-спаны `query` идут от datasource-micrometer и тоже становятся детьми текущего спана.
|
||
|
||
Ресурсы: `service.name` равен `messenger-api` или `messenger-worker`, `service.version=1.0.0`, `deployment.environment.name=lab`. OTLP/HTTP идёт на `http://otel-collector:4318`. Сэмплирование в стенде всегда включено.
|
||
|
||
Метрики таймеров Micrometer экспортируются в миллисекундах: `http_server_requests_milliseconds_*`, `messenger_job_duration_milliseconds_*`, `messenger_job_time_to_ready_milliseconds_*`. Панели считают `histogram_quantile` по сумме бакетов всех реплик (`sum by (le)`) и делят на 1000. Единица панели — секунды. Усреднять готовые p99 реплик нельзя: квантиль берётся из общей гистограммы. Возраст очереди уже в секундах: `messenger_queue_oldest_age_seconds`. HTTP-метки — метод, шаблон маршрута, статус и исход. `/health/*` и `/actuator` в RPS и в долю ошибок не входят.
|
||
|
||
**SLI доступности:** число ответов 5xx на обычных маршрутах, делённое на все такие запросы. Ответ 4xx в числитель не входит. **SLO:** 99% успешных ответов на окне 5 минут. Алерт `messenger-error-rate` смотрит долю 5xx на окне 2 минуты и переходит в firing, если она выше 5% в течение 1 минуты.
|
||
|
||
**SLI очереди:** возраст самого старого вложения в `queued` или `processing`. **SLO:** этот возраст меньше 30 секунд. Алерт `messenger-queue-lag` срабатывает, когда возраст больше 15 секунд в течение 30 секунд. Это возраст хвоста, а не длительность worker-спана.
|
||
|
||
Collector принимает OTLP и раскладывает три сигнала: traces в Tempo, logs в Loki, metrics в Prometheus remote write. Первый процессор — `memory_limiter` на 192 MiB. Дальше batch. У Tempo и Loki очередь 256 и `block_on_overflow: false`. У Prometheus своя `remote_write_queue` на 256: экспортер 0.139 не принимает `sending_queue`. Повтор экспортёра ограничен 30 секундами. Логи приложений пишут `trace_id` и `span_id` в строку и в structured metadata Loki. Поле `event` позволяет выбрать `http.completed`, `job.ready` или `job.retry`.
|
||
|
||
| Роль | Сервис | Образ | Volume |
|
||
| --- | --- | --- | --- |
|
||
| API | `api` × 2 | `messenger-lab6:1.0.0` | нет |
|
||
| Worker | `worker` | тот же образ, профиль `worker` | нет |
|
||
| Балансировщик | `lb` | `haproxy:3.2.6` | нет, только `127.0.0.1:8080` |
|
||
| Метаданные | `postgres` | `postgres:16.10` | `postgres-data` |
|
||
| Кэш сессии | `redis` | `redis:7.4.6` | `redis-data` |
|
||
| Брокер | `kafka` | `apache/kafka:3.9.1` | `kafka-data` |
|
||
| Объекты | `s3` | `chrislusf/seaweedfs:4.52` | `s3-data` |
|
||
| Приём телеметрии | `otel-collector` | `otel/opentelemetry-collector-contrib:0.139.0` | нет, лимит 320 MiB |
|
||
| Метрики | `prometheus` | `prom/prometheus:v3.2.1` | `prometheus-data`, только `127.0.0.1:9090` |
|
||
| Логи | `loki` | `grafana/loki:3.4.2` | `loki-data` |
|
||
| Трассы | `tempo` | `grafana/tempo:2.7.2` | `tempo-data` |
|
||
| Обзор и алерты | `grafana` | `grafana/grafana:11.6.1` | `grafana-data`, только `127.0.0.1:3000` |
|
||
|
||
Prometheus хранит ряды и отвечает на запросы дашборда и алертов. Loki хранит строки и structured metadata, по ним находится лог одного trace. Tempo хранит спаны и связи parent. Grafana только читает эти три хранилища: datasource, дашборд `messenger-lab6` и правила лежат в `infra/grafana` и подключаются provisioning-ом. Остановка Grafana не останавливает приём сообщений.
|
||
|
||
Лимиты прежних сервисов те же, что в lab5: API и worker по 1 CPU и 1024 MiB. Collector — 0.5 CPU и 320 MiB, Prometheus, Loki и Tempo — 0.5 CPU и 512 MiB, Grafana — 0.5 CPU и 384 MiB.
|
||
|
||
Новые переменные `.env.example`: `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_RESOURCE_ATTRIBUTES`, `GRAFANA_ADMIN_USER`, `GRAFANA_ADMIN_PASSWORD`. Остальные переменные lab5 сохранены.
|
||
|
||
## Доказательства критериев
|
||
|
||
Стенд: та же машина, что в lab5 (Mac arm64), Docker 28.5.1. Прогон 19 ноября 2026. Команды и цифры — `evidence/results.txt` и `evidence/grade6.txt`. Токены и текст сообщений туда не записывались. Первый запрос Tempo в сценарии видел только спаны API: worker-спаны попали в тот же trace на несколько секунд позже. В файле есть повторное чтение.
|
||
|
||
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke при включённой телеметрии | `make test` | код 0, `PASS: lab6 public API scenario` | `evidence/results.txt` |
|
||
| Свои тесты | `mvn -f backend/pom.xml test` | 22 теста, 0 failures, 0 errors | прогон 19 ноября |
|
||
| Collector, Prometheus, Loki, Tempo и Grafana в одном Compose, конфиги в Git, volumes сохраняются | `docker compose up`, каталоги `infra/otel`, `infra/prometheus`, `infra/loki`, `infra/tempo`, `infra/grafana` | после `stop`/`start` хранилищ дашборд и ряды снова доступны; Grafana `/api/health` 200, Prometheus `/-/ready` 200 | `compose.yaml`, `evidence/grade6.txt` |
|
||
| API и worker шлют OTLP | загрузка `bf19675a-7d93-4379-a708-1e5efc7366a7` | в одном trace есть `service.name=messenger-api` и `messenger-worker` | `evidence/grade6.txt` |
|
||
| Дашборд импортируется из Git | provisioning `infra/grafana/dashboards/messenger.json`, uid `messenger-lab6` | 12 панелей: RPS, доля 5xx, p50/p95/p99, jobs, длительность worker, время до ready, глубина и возраст очереди, Hikari, занятость worker, CPU, heap | `infra/grafana` |
|
||
| Низкая кардинальность и связь лога с trace | Loki `{service_name="messenger-api"} \| trace_id="d27d941c741436ad51a3b35c2921ca4d"` | `http.completed` с шаблоном `/api/v1/chats/{chatId}/attachments` и статусом 202; `attachment.accepted` с тем же trace. Тела сообщения и токена в строке нет | `evidence/grade6.txt` |
|
||
| Задание находится в trace и логе worker | тот же trace и Loki по `5540712fa2d49096df09db864f9ad9a8` | `job.retry` и `job.ready` worker, `service_name=messenger-worker` | `evidence/grade6.txt` |
|
||
| W3C от API через брокер к worker | Tempo trace `d27d941c741436ad51a3b35c2921ca4d` | HTTP-спан — родитель `s3.PutObject`, JDBC `query` и `attachments.process publish`. Process — ребёнок publish. S3 Get/Put worker и JDBC worker — дети process | `evidence/grade6.txt` |
|
||
| Та же цепочка вместе с retry | файл `/tmp/messenger-fail-transient`, вложение `ac1e1581-4d24-4789-a887-c14a1852581a` | один trace `5540712fa2d49096df09db864f9ad9a8`: два publish и два process. Второй publish — ребёнок первого process. S3 worker есть только у второго process. Итог `ready` | `evidence/grade6.txt` |
|
||
| p50/p95/p99 из гистограммы | `histogram_quantile` по `http_server_requests_milliseconds_bucket` / 1000, окно 5 минут, до аварий | p50 0.039 с, p95 0.132 с, p99 0.134 с. Это короткий учебный поток, не нагрузочный прогон | `evidence/grade6.txt` |
|
||
| Алерт доли ошибок, firing и resolved локально | 608 ответов `POST /internal/demo/error` за 100 с, затем тишина | во время потока state `Alerting`, доля 5xx за 2 минуты равна 1. После окна state `Normal`, доля 0. Внешней доставки нет | `evidence/grade6.txt`, `infra/grafana/provisioning/alerting/rules.yml` |
|
||
| Алерт возраста очереди | `compose stop worker`, одна загрузка, затем `start worker` | возраст 15.3 с, затем 75.5 с при state `Alerting`. После старта то же вложение `5c74e9f3-babc-424e-82df-55d025469ede` стало `ready`, возраст 0, state `Normal` | `evidence/grade6.txt` |
|
||
| Медленная БД и медленный обработчик | `POST /internal/demo/slow-db?seconds=3` и `slow-handler?seconds=3` с `X-Demo-Token` | slow-db: сервер 3088 мс, JDBC `query` 3013 мс. slow-handler: сервер 3026 мс, JDBC-детей нет | `evidence/grade6.txt` |
|
||
| Остановка хранилищ телеметрии не ломает сообщения и не растит память | `compose stop prometheus loki tempo`, затем сообщение и загрузка | сообщение 201, вложение `9a27a451-d677-4ed9-9684-a440620bb017` стало `ready`. Память collector 100 → 99.99 → 98.87 MiB при лимите 320 MiB. API около 495 и 515 MiB. В логе collector 32 строки ошибки экспорта | `evidence/grade6.txt` |
|
||
| Трек 5 | не заявлен | — | — |
|
||
|
||
Шаги разбора двух инцидентов лежат в `infra/grafana/runbooks/high-error-rate.md` и `infra/grafana/runbooks/queue-lag.md`. Различие slow-db и slow-handler — в `infra/grafana/runbooks/slow-database.md`. Рабочий фильтр Loki для 5xx: `{service_name="messenger-api"} | event="http.completed" |= "status=5"`. Поле `status` находится в тексте строки.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Отдельного замера RPS нет. Окно гистограммы — 5 минут учебных запросов `make test` и двух загрузок. p99 этого окна — 0.134 с. После 608 ответов 500 доля ошибок на двухминутном окне стала 1 и затем вернулась к 0. Это проверка порога, а не профиль нагрузки.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Восстановление |
|
||
| --- | --- | --- | --- |
|
||
| Worker остановлен, одна загрузка | 202, возраст очереди растёт, алерт firing, после старта то же вложение ready | возраст дошёл до 75.5 с, алерт `Alerting`, затем `ready` и возраст 0, алерт `Normal` | работа не потеряна |
|
||
| Серия демонстрационных 500 | доля 5xx выше 5% дольше 1 минуты, затем resolved | 608 ответов, `Alerting` при доле 1, после тишины `Normal` и доля 0 | обычные запросы не останавливались |
|
||
| `pg_sleep` 3 с и sleep в обработчике 3 с | у БД длинный JDBC-спан, у обработчика длинный сервер без JDBC | 3013 мс `query` против 0 JDBC-спанов при сервере 3026 мс | оба вызова завершились 200 |
|
||
| Один временный сбой worker до записи S3 | второй process в том же trace, итог ready | `job.retry` и `job.ready` с одним trace id, S3 только на второй попытке | вложение ready, дубль объекта не потребовался |
|
||
| Остановлены Prometheus, Loki и Tempo | сообщение и загрузка проходят, память collector ограничена | 201 и `ready`, память collector не выросла, 32 ошибки экспорта | хранилища подняты обратно, Grafana и Prometheus снова 200 |
|
||
|
||
Гейдж `hikaricp_connections_pending` на трёхсекундном `pg_sleep` в Prometheus не использовался: шаг OTLP-метрик 10 с, и такое окно легко попадает между отправками. Различие снято по длительности спанов.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Один Docker-host не переживает потерю этой машины. PostgreSQL, Redis, SeaweedFS, Kafka, Loki, Tempo и Prometheus в одном экземпляре. Replication factor топиков равен 1.
|
||
|
||
Доставка заданий at least once. Повтор перезаписывает те же ключи S3 и те же строки вариантов. Подтверждение брокера и commit смещения — разные границы.
|
||
|
||
Пока backend телеметрии лежит, часть спанов и строк отбрасывается: очередь экспортёра короткая и не блокирует приложение. После возвращения Loki или Tempo дырка в этом интервале остаётся. Алерт при `NoData` считается нормальным, чтобы простой стенд без трафика не горел.
|
||
|
||
Демо-маршруты `/internal/demo/*` закрыты общим `X-Demo-Token` и не входят в OpenAPI. Трек 5 не делался.
|