Files
mtusi2026lab6-fork/REPORT.md
T

169 lines
23 KiB
Markdown
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.
# Отчёт — лабораторная 6
- Автор — Любченко Никита, БПИ2303.
- Целевая оценка — 4. Трек 5 не заявлен.
- Использованы Python 3.12, OpenTelemetry SDK 1.38.0, semantic conventions 0.59b0, Collector contrib 0.123.0, Prometheus 3.2.1, Loki 3.4.2, Tempo 2.7.2, Grafana 11.6.0 и компоненты lab5. ИИ использован при разработке и проверке реализации.
- Ссылку на PR добавляет автор после публикации. Результаты проверок приведены в evidence/.
## Запуск из чистого клона
Требуются Docker Engine с Compose, Make и Python 3.9+ для публичных проверок. Первая сборка обращается к реестрам образов, PyPI и исходникам MinIO. Приложение работает на Python 3.12. Изображения обрабатываются Pillow. Go используется при сборке MinIO и mc из исходников.
```sh
cp -n .env.example .env
python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env build
docker compose --env-file .env up -d --no-build
python3 scripts/manage.py status
python3 scripts/wait_ready.py
make check
make test
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
make test-observability
```
API доступен через Nginx на http://localhost:18083. Grafana — http://localhost:13000, логин admin. Пароль читается из secrets/grafana_password. Prometheus — http://localhost:19090. Loki и Tempo имеют loopback HTTP-порты 13100 и 13200 для воспроизводимых проверок. OTLP и внутренние API-порты на хост не опубликованы. Dashboard Messenger и три источника данных подключаются provisioning автоматически.
Bootstrap создаёт локальные secrets с ограниченными правами, сохраняет уже существующие значения и не печатает их. `.env`, `secrets/` и `.venv/` исключены из Git. Безопасная остановка — `docker compose down`. Намеренное удаление всех учебных данных текущего проекта — `docker compose down -v`.
## Архитектура и решения
Перенесены Nginx, две API-реплики, PostgreSQL, Redis, приватный MinIO, RabbitMQ, publisher, worker и cleaner из lab5. PostgreSQL остаётся источником истины. API сохраняет исходник в S3 и фиксирует queued, job и outbox одной транзакцией перед ответом 202. Издатель использует publisher confirms. Воркер сохраняет три варианта, фиксирует ready, затем подтверждает сообщение брокеру. Lease, retry/backoff, fencing по attempt, replay и очистка сохранены.
Добавлен путь API/publisher/worker → OTLP/gRPC → Collector → Prometheus/Loki/Tempo → Grafana. Prometheus хранит числовые временные ряды, Loki — структурные логи, Tempo — трассы. Grafana выполняет запросы к этим источникам. У хранилищ собственные volumes, retention сигналов составляет 72 часа. Collector обрабатывает и экспортирует данные.
Миграция 0006 добавляет trace_context jsonb в attachment_jobs. Контекст сохраняется вместе с заданием. Издатель создаёт producer span с родителем из сохранённого контекста и передаёт traceparent/tracestate в AMQP headers. Consumer продолжает этот контекст. Повторные попытки имеют общий исходный trace и отдельные producer/consumer spans. Старые задания получают пустой контекст и обрабатываются обычным способом.
Ресурсы содержат service.name (messenger-api, messenger-publisher, messenger-worker), service.version, service.instance.id и deployment.environment.name=lab. Логи включают timestamp, severity, event, request_id и trace_id/span_id при активном span. HTTP возвращает X-Request-Id и дополнительный X-Trace-Id. SQL-тексты, значения параметров, Authorization, пароли, signed URL, тела сообщений и изображения в инструментацию не передаются. OTLP bridge отбрасывает полный текст исключений и traceback. Технический job.id допустим для синтетических traces/logs. В metric labels его нет.
## Сигналы и запросы
| Сигнал | Реальное имя в Prometheus | Единица |
| --- | --- | --- |
| HTTP count | messenger_http_requests_total | запросы |
| HTTP duration | messenger_http_duration_seconds_bucket | секунды, histogram |
| Jobs | messenger_jobs_processed_total | попытки, outcome success/error/stale |
| Processing duration | messenger_job_duration_seconds_bucket | секунды одной попытки |
| Accepted-to-ready | messenger_attachment_time_to_ready_seconds_bucket | секунды до фиксации ready |
| Backlog | messenger_queue_depth | queued + processing, включая outbox/retry |
| Broker ready | messenger_queue_broker_ready | ожидающие доставки сообщения RabbitMQ |
| Oldest age | messenger_queue_oldest_age_seconds | возраст старейшего незавершённого задания |
| Backlog freshness | messenger_queue_observed_at_seconds | Unix timestamp последнего опроса |
| DB pool | messenger_db_pool_used, messenger_db_pool_waiting, messenger_db_pool_capacity | соединения / запросы на получение |
| Pool exhaustion | messenger_db_pool_exhausted_total | отказы получения соединения |
| Pool acquisition | messenger_db_pool_acquire_seconds_bucket | секунды |
| Worker | messenger_worker_busy, messenger_worker_capacity | занятые / доступные обработчики |
| Memory | messenger_process_memory_bytes | текущий RSS процесса, байты |
| CPU | messenger_process_cpu_seconds_total | накопленное процессорное время, секунды |
HTTP labels содержат method, route template и status_class. Health исключён из бизнес-счётчиков. Неизвестные маршруты сводятся к unmatched. Histogram boundaries — 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60, 120 секунд и +Inf. Pool waiting измеряет поток во время вызова getconn. Пул psycopg2 немедленно отказывает при исчерпании ёмкости, длительного ожидания свободного соединения в нём нет.
Time to ready начинается с clock_timestamp при регистрации задания после PUT исходника, непосредственно перед COMMIT принятия, и заканчивается после COMMIT ready. Начальная точка приближает границу durable acceptance с точностью до оставшейся части транзакции. Метрика записывается только после успешного COMMIT результата. При аварии процесса сразу после COMMIT отдельное наблюдение может отсутствовать. Бизнес-состояние восстанавливается из PostgreSQL.
Запросы dashboard сохранены в infra/grafana/dashboards/messenger.json. Например, p95 всех реплик вычисляется из объединённых buckets.
```promql
sum by (method, route) (rate(messenger_http_requests_total[1m]))
histogram_quantile(0.95, sum by (le) (rate(messenger_http_duration_seconds_bucket[1m])))
rate(messenger_process_cpu_seconds_total[1m])
messenger_queue_oldest_age_seconds
```
p50 и p99 отличаются аргументом histogram_quantile. Метрика CPU rate выражена в занятых ядрах. Backlog, processing duration и end-to-end time показывают разные части обработки. Логи ищутся в Loki запросом `{service_name=~"messenger-.*"} |= "<trace_id>"`. Tempo принимает поиск по trace ID и TraceQL `{resource.service.name = "messenger-worker"}`.
## SLI, SLO и алерты
SLI — доля бизнес-запросов без 5xx за скользящие 5 минут. SLO ≥99%. 4xx входят в знаменатель и не считаются отказом сервера. При отсутствии запросов SLI не оценивается. Этот SLI отражает запросы, дошедшие до API. Ошибки самого Nginx и отсутствие входящего трафика требуют внешнего probe.
HighApiErrorRate срабатывает при доле 5xx >1% за 1 минуту, for 6 секунд. QueueLagGrowing срабатывает при oldest age >15 секунд и backlog >0, for 6 секунд. QueueObservationStale показывает, что publisher перестал обновлять состояние очереди. Правила сохранены в infra/prometheus/alerts.yaml. Runbook находится в infra/runbook.md. Локальные firing/resolved проверяются через Prometheus API.
## Ограничение памяти и отказ телеметрии
У SDK очереди до 256 spans и 256 logs на процесс, batch 64, export timeout 1 секунда. Метрики экспортируются каждые 3 секунды. SDK передаёт телеметрию фоновыми потоками.
Collector применяет memory_limiter 128 MiB со spike 32 MiB, batch до 512 записей, очереди Loki/Tempo до 128 batches каждая, два consumer на экспортёр. Retry ограничен 10 секундами, timeout отдельного экспорта 2 секунды. Контейнер ограничен 192 MiB. При недоступности backend часть наблюдений может теряться. Prometheus забирает данные pull-запросами, остановка Prometheus создаёт пробел в истории scrape. Для логов и трасс проверяется отказ push backend Tempo.
Внутренние accepted/sent/send_failed/enqueue_failed counters Collector позволяют увидеть деградацию экспорта. send_failed показывает отказ экспорта. Потери в контролируемом окне дополнительно подсчитываются по dropped_items в журнале Collector. Точное число уникальных потерь во всей цепочке по одному counter не вычисляется.
## Проверки и эксперименты
Файлы stage1-* относятся к переносу основы до включения полного стека наблюдаемости. Итоговые доказательства приведены ниже.
| Критерий | Сценарий / результат | Доказательство |
| --- | --- | --- |
| Структура и схема API | make check, make validate | evidence/check.txt, evidence/validate.txt |
| Бизнес-API с телеметрией | make test | evidence/smoke.txt |
| Метрики, логи и реальные traces API/worker | make test-observability, проверены имена сигналов и логи трёх процессов | evidence/observability-smoke.json |
| W3C propagation и связь S3/DB | Parent-child spans, сохранён tracestate, внешний traceparent принят API | evidence/observability-smoke.json |
| Retry в исходном trace | Две consumer-попытки, ready после восстановления S3 | evidence/observability-retry.json |
| Dashboard и datasources | Provisioning 14 панелей, проверены все PromQL и поиск Tempo через Grafana | evidence/observability-smoke.json, infra/grafana |
| Percentiles, backlog, oldest age, DB pool, worker saturation, CPU/RAM | Histogram buckets и gauge/counters, единицы указаны выше | infra/grafana/dashboards/messenger.json |
| SLI/SLO и локальные alerts | promtool, firing/resolved для error rate и queue lag | evidence/alert-config.txt, evidence/observability-worker-stop.json, evidence/observability-db-outage.json |
| Остановка worker | Алерт firing через 30,1 с, после восстановления задание ready, алерт resolved | evidence/observability-worker-stop.json |
| Задержка PostgreSQL | 8 запросов получили 503, client span показывает ошибку БД, алерт firing/resolved | evidence/observability-db-outage.json |
| Отказ Tempo | 138 успешных сообщений, вложение ready, потеря 248 spans по dropped_items, без OOM/рестартов | evidence/observability-backend-outage.json |
| История сигналов после перезапуска | Сохранены исходная trace, логи трёх процессов и historical metric sample | evidence/telemetry-persistence.json |
| Сохранность бизнес-данных и отказ реплики | Публичные persistence/failover | evidence/persistence.txt, evidence/failover.txt |
| Полная HTTP duration | Регрессионная проверка включает отправку тела | evidence/http-timing.txt |
### Нагрузка
Docker Engine 29.5.3, Compose 5.1.4, aarch64, 10 доступных CPU и около 7,75 GiB RAM в VM. Лимиты API — по 0,5 CPU/256 MiB, worker — 1 CPU/768 MiB, Collector — 0,5 CPU/192 MiB. Параметры среды сохранены в evidence/environment.json.
`make load` выполнял closed-loop POST сообщений 30 секунд, concurrency 4, без автоматических повторов. Выполнено 14 048 успешных запросов, ошибок 0, 467,941 RPS. Клиентские latency успешных запросов — p50 5,119 ms, p95 33,476 ms, p99 81,147 ms. Это один прогон, отдельного прогрева не было. Percentiles клиента охватывают только успехи и подвержены coordinated omission. Они дополняют histogram dashboard. Результат не заявляется как максимальная пропускная способность. Raw summary — evidence/load-output.txt.
### Инцидент 1. Остановленный worker
При продолжающемся приёме upload возраст незавершённого задания превысил 15 секунд, backlog оставался положительным. QueueLagGrowing перешёл в firing примерно через 30,1 секунды после загрузки. По метрикам видно ожидание обработки, producer span опубликован, consumer появляется после запуска worker. После восстановления job достигла ready, backlog уменьшился, алерт resolved. Диагностика выполняется по сохранённым возрасту/глубине очереди, состоянию alert и связанной trace. Сценарий — `python3 student-tests/observability.py worker-stop`.
### Инцидент 2. Ожидание PostgreSQL
Сценарий удерживает ACCESS EXCLUSIVE lock таблицы users 35 секунд. Восемь GET /users/me завершились 503 вследствие statement_timeout. В trace длительный postgresql.transaction имеет error status, что локализует задержку в БД. HighApiErrorRate перешёл в firing, после снятия блокировки запросы восстановились, alert resolved. Сценарий — `python3 student-tests/observability.py db-outage`.
Во время разработки выявлено, что retry HTTP 503 в Nginx временно исключал обе реплики при общем тайм-ауте БД и приводил к 502. Теперь Nginx передаёт 503 клиенту. Переключение при сетевых ошибках и active readiness сохранено и проверено публичным failover. Старая и новая серии gauge после рестарта publisher различаются по service.instance.id. Dashboard и alerts используют freshness, чтобы устаревший экземпляр не создавал ложный queue alert.
### Недоступность telemetry backend
Tempo был остановлен на время последовательной записи сообщений и обработки изображения. SDK/Collector продолжили ограниченный экспорт с retry и drops. Успешно записано 138 сообщений, изображение стало ready. Collector зарегистрировал 248 dropped spans. Это число явно отброшенных записей данного exporter за окно, общая оценка уникальных потерь по всей системе не заявляется. Send-failed сравнивался до/после отказа.
Наблюдаемый RSS Collector находился примерно в пределах 92–97 MiB при лимите 192 MiB, API — около 74–76 MiB, worker — около 63 MiB, publisher — около 34 MiB. Контейнеры работали без OOM и автоматических перезапусков. Измерение длилось около 40 секунд и подтверждает поведение данного сценария. Конфигурация задаёт конечные очереди и memory limiter для более длительной недоступности. После запуска Tempo найдены новые связанные trace и логи. Сценарий — `python3 student-tests/observability.py backend-outage`.
### Воспроизведение
```sh
make test-observability
docker compose exec -T api-a python - < student-tests/http_timing.py
python3 student-tests/observability.py worker-stop
python3 student-tests/observability.py db-outage
python3 student-tests/observability.py retry
python3 student-tests/observability.py backend-outage
python3 student-tests/telemetry_persistence.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 scripts/manage.py restore
```
Fault-сценарии выполняются по одному. Для проверки retry worker запускается через docker start, чтобы Compose не поднял остановленный S3 как dependency. PostgreSQL lock освобождается по завершении ограниченного pg_sleep. Все проверки используют синтетические данные.
## Ограничения
Стенд учебный, single-node. PostgreSQL, MinIO, RabbitMQ и telemetry backend представлены одиночными экземплярами. Авторизация Grafana локальная, TLS относится к следующей лабораторной. Sampling по умолчанию 100%, исследовательские треки на 5 не заявлены. Старые вспомогательные student-tests предыдущих лабораторных могут требовать специальных условий, например остановленного worker. Для lab6 использовать make test и student-tests/observability.py.
## Источники
- https://opentelemetry.io/docs/collector/configuration/
- https://opentelemetry.io/docs/concepts/context-propagation/
- https://www.w3.org/TR/trace-context/
- https://grafana.com/docs/loki/latest/send-data/otel/
- https://prometheus.io/docs/practices/histograms/
- https://grafana.com/docs/grafana/latest/administration/provisioning/
## Соответствие переменных окружения
Compose задаёт служебные адреса и пути secrets внутри контейнеров. PUBLIC_PORT и JOB_MAX_ATTEMPTS читаются из локального .env. API использует SESSION_STORE=redis. DATABASE_URL_FILE, CACHE_URL_FILE, CURSOR_SECRET_FILE и S3_*_FILE указывают на secrets. Издатель и worker получают RABBITMQ_PASSWORD_FILE, подключаются к rabbitmq:5672 под локальным пользователем lab6. BROKER_URL_FILE из исходной заготовки заменён этой настройкой.
В данной реализации один worker-процесс обрабатывает одно задание с prefetch 1. WORKER_CONCURRENCY=1 описывает эту ёмкость. Тайм-аут попытки фиксирован на 20 секундах, lease на 60 секундах. MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS и STAGING_RETENTION_SECONDS соответствуют константам перенесённого приложения. Изменять эти поля .env отдельно от кода не следует. OTEL_SERVICE_NAME и endpoint задаются Compose отдельно для каждого процесса, используется grpc на 4317. Параметры SDK/Collector приведены выше и закреплены в коде и YAML.