Document lab6 results and verify application in CI

This commit is contained in:
Самохвалов Андрей Ремович
2026-10-02 17:07:23 +03:00
parent f61d070574
commit 4384098c56
2 changed files with 128 additions and 21 deletions
+35
View File
@@ -0,0 +1,35 @@
name: Lab 6 application and telemetry
on: [push, pull_request]
permissions:
contents: read
jobs:
smoke:
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: python -m pip install -r requirements-dev.txt
- run: make check validate PYTHON=python
- name: Start disposable stack
run: |
cp .env.example .env
python scripts/setup-local-secrets.py
python scripts/init_local_broker.py
docker compose -f compose.yaml -f compose.telemetry.yaml --env-file .env up -d --build --wait --scale api=2
- name: Verify API and telemetry rules
run: |
make test
python - <<'PY'
import json, urllib.request
url = 'http://127.0.0.1:9090/api/v1/rules'
data = json.load(urllib.request.urlopen(url, timeout=10))
assert data['status'] == 'success'
names = {rule['name'] for group in data['data']['groups'] for rule in group['rules']}
assert {'Lab6HighHttpErrorRate', 'Lab6QueueLag'} <= names, names
PY
- name: Stop stack
if: always()
run: docker compose -f compose.yaml -f compose.telemetry.yaml --env-file .env down || true
+93 -21
View File
@@ -1,37 +1,109 @@
# Отчёт — лабораторная 6
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор: Самохвалов Андрей Ремович, БПИ-2302.
- Целевая оценка: 5; трек 2 «SLO и обнаружение инцидентов». Уровни 3 и 4 проверяются отдельно.
- Ветка: `solution/bpi2302-samohvalov`. Локальные `docs/plans/` и `LAB_NOTES.md` не публикуются.
- Источники: `README.md`, `COURSE.md`, `contracts/observability.md`, публичные проверки и собственная lab5. Помощь ИИ: Codex; результаты ниже получены на синтетических данных.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Нужны Docker Compose и Python 3.9+. На хост открыты только loopback-порты API 8080, Grafana 3000 и Prometheus 9090. Секреты создаются локально с правами 0600 и не попадают в Git.
## Архитектура и решения
```sh
cp .env.example .env
python3 scripts/setup-local-secrets.py
python3 scripts/init_local_broker.py
docker compose -f compose.yaml -f compose.telemetry.yaml --env-file .env config --quiet
docker compose -f compose.yaml -f compose.telemetry.yaml --env-file .env up -d --build --wait --scale api=2
make check
make test BASE_URL=http://127.0.0.1:8080
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
`migrate`, `s3-volume-init`, `s3-bootstrap`, `broker-init` — одноразовые роли, их успешный `Exited (0)` штатен. Остановка с сохранением томов: `docker compose -f compose.yaml -f compose.telemetry.yaml --env-file .env down`. Намеренное удаление **только синтетических локальных** данных: та же команда с `-v`. Не запускать `-v` для существующего стенда, который нужно сохранить. Миграции 001–008 применяются под PostgreSQL advisory lock.
## Доказательства критериев
Образы: Python 3.12.12, PostgreSQL 17.6, RabbitMQ 4.1.8, HAProxy 3.0.11, MinIO `RELEASE.2025-10-15T17-29-55Z` (digest), MinIO Client `2025.7.21` (digest); OTel Collector contrib 0.128.0, Prometheus 3.5.0, Loki 3.5.0, Tempo 2.9.5, Grafana 12.0.2. Приложение: FastAPI 0.118.3, OTel SDK/API/OTLP 1.45.0, semantic conventions 0.66b0, psycopg 3.2.12, Pillow 11.3.0, pika 1.4.4. Локальный Colima/arm64: 2 CPU, 2 GiB RAM. На этом хосте Docker build обходил неисправный DNS PyPI через ignored `compose.local.yaml`; обычному окружению файл не нужен.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
## Архитектура и конфигурация
Собственный стек lab5 перенесён без замены контрактов: HAProxy → две API-реплики → PostgreSQL, приватный MinIO, долговечный RabbitMQ и отдельные publisher/worker/cleanup. API возвращает `202 queued` только после сохранения проверенного staging-объекта и одной транзакции attachment/job/outbox. Publisher подтверждает AMQP-публикацию, worker подтверждает delivery после устойчивого результата. Повторы безопасны по version/lease и уникальности эффектов. Реплика API, воркер или broker могут перезапускаться без потери принятой job; единственные DB/S3/broker/host остаются точками отказа.
| Роль | Версия, health, данные, пределы | Доступ |
| --- | --- | --- |
| `api ×2` | Python/FastAPI; `/health/ready`; 0,5 CPU/256 MiB на реплику | DB и ограниченный S3 secret; API через LB |
| `lb` | HAProxy 3.0.11; backend health; без тома; 0,5 CPU/128 MiB | `127.0.0.1:8080` |
| `postgres` | 17.6; `pg_isready`; `postgres_data` | только внутренняя сеть, secret |
| `s3` | MinIO, digest; HTTP readiness; `s3_data`; 0,5 CPU/384 MiB | приватный bucket, раздельные app/maintenance secrets |
| `broker` | RabbitMQ 4.1.8; diagnostics ping; `broker_data` | durable quorum queue, AMQP secret |
| `publisher` | Python 3.12.12; DB outbox и broker confirms | DB/AMQP secrets, нет S3 |
| `worker` | Python 3.12.12; serial consumer, 0,5 CPU/768 MiB | DB/AMQP/S3 secrets |
| `staging-cleanup` | Python 3.12.12; периодическая сверка | DB и отдельный maintenance S3 secret |
| `otel-collector` | contrib 0.128.0; internal metrics 8888; 384 MiB | OTLP 4317/4318 только Compose |
| `prometheus` | 3.5.0; `prometheus_data`, retention 7d | `127.0.0.1:9090` |
| `loki` / `tempo` | 3.5.0 / 2.9.5; `loki_data` / `tempo_data`; Tempo 768 MiB, блоки до 5 MB/1 мин | только Compose |
| `grafana` | 12.0.2; `grafana_data`, provisioning из Git | `127.0.0.1:3000`, password secret |
`.env.example` задаёт локальные порты/пределы; Compose передаёт файлы секретов через `/run/secrets`. OTLP endpoint внутри сети `otel-collector:4318`. Имена `APP_VERSION=lab6`, instance UUID и `deployment.environment.name=lab` записаны как resource attributes. Grafana импортирует три datasource и dashboard из `infra/grafana/`. Prometheus загружает rules из `infra/prometheus/rules.yml`.
OTel SDK экспортирует асинхронно раз в 5 секунд с 2-секундным timeout и очередями 512 spans/records. Collector применяет memory limiter 256/64 MiB, batch 512/2s и конечные exporter queues: metrics 1000, logs/traces по 64 batches, retry не дольше 30 секунд. Отказ хранилища наблюдаемости не входит в business readiness. Потери сигналов при долгом отказе допустимы и измеряются отдельно.
## Сигналы и запросы
| Сигнал | Native Prometheus metric / Loki / Tempo | Единица и labels |
| --- | --- | --- |
| HTTP count, duration | `messenger_http_requests_total`, `messenger_http_duration_seconds_bucket` | запросы, секунды; method/route template/status_class |
| Jobs count, duration | `messenger_jobs_processed_total`, `messenger_jobs_duration_seconds_bucket` | jobs, секунды; job_type/outcome |
| Backlog | `messenger_queue_depth`, `messenger_queue_oldest_age_seconds` | jobs, секунды; queue_name |
| Pool | `messenger_db_pool_used`, `messenger_db_pool_waiting` | connections; service_name из resource |
| Worker | `messenger_worker_busy`, `messenger_worker_capacity` | slots; capacity=1 на serial worker |
| CPU/RAM | `messenger_process_cpu_time_seconds_total`, `messenger_process_rss_bytes` | CPU-секунды, bytes текущего RSS |
| До ready | `messenger_attachments_ready_duration_seconds_bucket` | секунды от durable job creation до result COMMIT |
| Логи/трассы | Loki `{service_name="messenger-api"}` / `messenger-worker`; Tempo trace ID | timestamp, severity, event, trace/span IDs, server/producer/consumer spans |
Dashboard `infra/grafana/dashboards/telemetry.json` содержит сохранённые запросы и единицы. RPS = `sum(rate(messenger_http_requests_total{route!~"/health/.*"}[1m]))`; HTTP 5xx SLI = `sum(rate(...{status_class="5xx"}[1m])) / sum(rate(...[1m]))` для бизнес-запросов. 4xx остаются в знаменателе, отдельно показаны. p50/p95/p99 = `histogram_quantile(q,sum by(le)(rate(*_bucket[5m])))` по всем репликам; средние p95 реплик не используются. Queue age рассчитывается из старейшей queued job в PostgreSQL и не заменяет время обработки. После перезапуска publisher устаревшие remote-write ряды отфильтрованы по sample age <15 с.
Контекст W3C `traceparent/tracestate` сохраняется в job/outbox и передаётся через брокер; consumer span является потомком producer span. Один upload trace проходит API → publisher → worker → S3/render/DB. Логи API/worker сохраняют `trace_id` и `span_id`; `X-Request-Id` коррелирует HTTP-ошибку. Метки метрик не содержат ID, filename или raw URL. Тела запросов, изображения, токены, пароли, Authorization, signed URLs в telemetry не пишутся. Loki индексирует только service/environment/instance; trace ID хранится как metadata.
## Проверки критериев
| Критерий | Команда или источник | Наблюдаемый результат |
| --- | --- | --- |
| Бизнес-контракт с telemetry | `make test`; `student-tests/test_pipeline_faults.py`; `test_publish_confirm_gap.py` | smoke PASS, шесть fault-сценариев PASS, повтор после broker confirm дал один логический ready-эффект |
| Связь трёх сигналов | `student-tests/test_telemetry.py`; Loki и Tempo по одному trace ID | API upload → publisher producer → worker consumer → S3/render/DB; API и worker logs содержат тот же trace ID |
| Метрики и dashboard | Grafana API `GET /api/dashboards/uid/lab6-telemetry`; каждый PromQL из dashboard через `/api/v1/query` | dashboard импортирован, 16 панелей; запросы к реально существующим рядам возвращают `success`; inactive alert не создаёт ряд firing |
| Alert и worker stop | `student-tests/test_queue_incident.py` | 8/8 accepted→ready, queue age peak 34,47 с, `Lab6QueueLag` firing через 35 с, inactive через 12 с после запуска worker; `evidence/queue-worker-stop-2026-10-02.json` |
| Alert и DB outage | `student-tests/test_slo_alerts.py --case short/long` | 12/46 ответов 503; короткое и длинное API burn rules прошли firing→inactive; `evidence/slo-short-db-2026-10-02.json`, `slo-long-db-2026-10-02.json` |
| Отказ telemetry stores | `student-tests/test_observability_failure.py` | остановлены Prometheus/Loki/Tempo; smoke PASS, 17 876 POST без ошибки, 595,531 RPS; Collector RSS 70,82→116 MiB при лимите 384 MiB; все stores `up=1` непрерывно 30 с после восстановления; `evidence/telemetry-backend-outage-2026-10-02.json` |
| Сохранность и отказ реплики | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | существующая сессия и подтверждённые записи сохранились; после остановки одной реплики 113 успешных записей, один неопределённый ответ, первая успешная запись через 3,685 с |
| CI | `.github/workflows/application.yml` | отдельный job создаёт локальные secrets, собирает Compose, ждёт готовность, выполняет `make test` и проверяет rules API; удалённый CI ещё не запускался |
Публичный `make test` проверяет бизнес-API, но сам по себе не доказывает полноту наблюдаемости. Публичные контракты и тесты не изменялись. Отдельные тесты лежат в `student-tests/`, исходные агрегаты — в `evidence/`. Пять базовых ролей lab5 с fault matrix сохранены, migration 008 добавляет только допустимый trace carrier.
## SLO и эксперимент трека 5
Пороги зафиксированы **до SLO-инъекций** в `evidence/slo-thresholds-2026-10-02.md` и коммитах `5deecdf`, `43bcde7`. Baseline на двух API-репликах: 30,010 с closed-loop, concurrency=4, 18 260/18 260 успешных POST, 608,462 RPS, p50/p95/p99 успешных ответов 4,289/14,966/59,664 мс. Для 40 PNG (20×320×200 и 20×800×600, concurrency=4) — 40/40 ready за 13,029 с; p95 от начала upload до ready 1,305/1,618 с. Raw JSON: `evidence/lab6-http-baseline-2api-2026-10-02.json`, `lab6-image-baseline-2api-2026-10-02.json`. На спокойном 25-секундном наблюдении 6 правил × 6 samples = 36 состояний `inactive`, ложных firing нет (`evidence/slo-quiet-baseline-2026-10-02.jsonl`). Closed-loop тест имеет coordinated omission и клиентские накладные расходы; p95 изображений включает polling по 0,3 с.
- API SLO: **99%** non-health ответов без 5xx на скользящих 10 мин; 4xx в знаменателе, но не в числителе. В опыте запросы отправлены прямо в живой API-контейнер: HAProxy после потери readiness может сам вернуть 503, а SDK внутри API не видит такие ответы. Это измеряемое ограничение покрытия SLI.
- Ready SLO: **95%** завершённых image jobs дошли до ready за ≤5 с от durable job creation на скользящих 10 мин. Время upload до `202` исключено; ещё не завершённая job не входит в histogram, поэтому отдельный queue age alert обязателен.
- Burn-rate: short сочетает окна 15/30 с, >14,4× бюджета, `for:10s`; long — 60/120 с, >6×, `for:90s`. Для API error ratio это >14,4% и >6%; для ready slow ratio >72% и >30%. Оценка каждые 5 с. Формулы с фактическими buckets `le="5"` находятся в `infra/prometheus/rules.yml`; `promtool check rules` нашёл 6 правил. Время обнаружения считается от команды воздействия до первого сохранённого `firing`, восстановление — от healthy зависимости до первого `inactive`. Дискретизация 5 с даёт погрешность ±5 с, плюс задержка экспорта.
| Опыт | Воздействие и выборка | Обнаружение | Восстановление и ложные срабатывания |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Короткий DB | остановка PostgreSQL на 50 с; 12 × 503, 243 × 401 в фиктивном auth-probe | HTTP error и API short firing через 35 с | API short inactive через 22 с после DB healthy; HTTP error через 37 с; API long остался pending и затем inactive, firing не было |
| Длинный DB | остановка PostgreSQL на 180 с; 46 × 503, 234 × 401 | HTTP error 30 с; API short 36 с; API long 141 с | после DB healthy: short 68 с, long 98 с, HTTP error 78 с до inactive; данных не потеряно |
| Worker stop | 8 real uploads при остановленном worker | queue lag firing через 35 с, возраст достиг 34,47 с | 8/8 ready; queue lag inactive через 12 с после запуска; ready histogram был слеп до завершения jobs |
| Умеренный CPU throttle | worker 0,1 CPU, 40 image jobs | ready p95 больших PNG 4,757 с, peak slow ratio 11,36% | пороги burn-rate не достигнуты; 30/30 samples ready short inactive |
| Сильный CPU throttle | worker 0,05 CPU, 30 больших PNG | 30/30 ready за 72,988 с, p95 10,360 с, peak slow ratio 100%; ready short firing с 13:36:26 UTC | лимит возвращён 0,5 CPU; short/long в конце окна inactive; long дал задержанное firing после завершения нагрузки из-за 120-секундной памяти окна и `for:90s` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Пробник с четырьмя одновременными клиентами в коротком DB-опыте сам создавал клиентские timeout вместо устойчивого ряда 503; перед финальными сериями его сменили на один равномерный поток после отдельной проверки `503` через живой API. Пороги не меняли. Файлы финальных серий содержат UTC timestamps, все состояния rules и обезличенные коды ответов. Сильный CPU throttle показал известный компромисс длинного окна: сигнал может сработать уже после прекращения воздействия, пока бюджет ещё расходуется по историческим завершениям. Это одно запаздывающее оповещение, а не новая ошибка после восстановления.
## Эксперименты и отказы
## Отказ наблюдаемости и сохранённые сигналы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
В финальном опыте с остановкой всех трёх storage public smoke прошёл, 30-секундная нагрузка дала 17 876 POST без ошибок, 595,531 RPS, latency успехов p50/p95/p99 4,844/16,108/49,174 мс. Collector имел RSS 70,82 MiB до, 104,2 MiB во время, 116 MiB через 35 с; контейнерный предел 384 MiB. Дельта Collector counters: `otelcol_exporter_enqueue_failed_spans` +19 486, `send_failed_spans` +16 547, `send_failed_log_records` +11 063, `send_failed_metric_points` +484; receiver refused counters остались 0. `send_failed_*` считают неудачные попытки экспорта и не равны потерянным элементам; `enqueue_failed_spans` означает отказ поставить spans в конечную очередь. API не блокировался, но часть traces потеряна. При пропаже telemetry отсутствующая точка не считается нулём ошибок.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
В предварительном опыте `compose up` вернул код 0, но Tempo завершился по OOM при flush накопленного блока 14 MiB; первоначальная проверка восстановления была недостаточной. WAL этого синтетического блока сохранён в локальной копии `/private/tmp/lab6-tempo-wal-backup-2026-10-02`, проблемный блок изолирован внутри тома, остальные сохранённые traces доступны. Tempo получил лимит 768 MiB и блоки до 5 MB/1 мин с одним одновременным flush. Повторная нагрузка с работающей telemetry дала 18 860/18 860 успешных POST, 628,445 RPS, и Tempo оставался `up=1` после flush (`evidence/tempo-recovery-load-2026-10-02.json`). Финальный отказ хранилищ после исправления прошёл; тест восстановления требует 30 секунд непрерывного `up=1` у Prometheus, Loki и Tempo.
## Ограничения и следующие шаги
Grafana импортировала обновлённый dashboard через provisioning; Prometheus сохранил rule states, Loki — структурные API/worker logs, Tempo — один trace с API upload, publisher, worker и дочерними S3/render/DB spans. Пример доказанной цепочки в локальном хранилище: trace ID `5626970bc7d05d13fb839033d5f9b410`, worker consumer span `8850acdc538bf1ae`, API root `0ee38f12aafbf091`, publisher producer `9ef172904a867da6`. Trace ID — случайный технический идентификатор синтетического запроса; тела, credentials и URL не сохранены в evidence.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Пробный слепой разбор runbook выполнил отдельный агент только по сохранённым Prometheus/Loki/Tempo сигналам, без сценариев инъекций и Docker stdout. Для окна 13:16:20–13:21:15 UTC он нашёл первые 5xx в 13:16:30, рост ожидания DB pool до 418 и HTTP p95 до 9,75 с; предположил деградацию БД/пула, но не мог различить их без DB child span. Для 13:23:45–13:24:50 UTC он увидел восемь `job_published`, queue depth 8, рост возраста до 34,5 с, отсутствие свежей worker capacity и восемь `job_processed` после восстановления; предположил недоступность worker. Во время разбора `up{job="tempo"}=0` из-за описанного OOM, поэтому trace не был доступен, а причина остановки worker не доказывалась одними сохранёнными сигналами. Это проверка понятности runbook другим агентом, не независимая проверка студентом.
Runbook: `infra/runbooks/incident.md`. При пропаже сигнала оператор сначала проверяет `up` storage и счётчики Collector. Локальный стенд не гарантирует доступности при потере одного PostgreSQL/S3/RabbitMQ/host, а serial worker ограничивает throughput изображений. Синтетические тесты не доказывают production SLO или безошибочность внешнего клиента.