Files
mtusi2026lab6/REPORT.md

24 KiB
Raw Permalink Blame History

Отчёт — лабораторная 6

  • Автор, группа: Матвиенко Павел, БПИ2304
  • Целевая оценка; выбранный трек 5, если нужен: 3.
  • Commit/PR: ad8db1f32b898ae43df22b1d3c0a431e553beff8; mtusi2026/mtusi2026lab6#71
  • Использованные источники, библиотеки и помощь ИИ: задание и контракты лабораторной №6, документация OpenTelemetry, Prometheus, Loki, Tempo, Grafana, FastAPI, Python SDK; при разработке и отладке использовалась помощь ИИ.

Запуск из чистого clone

Среда: Windows с WSL Ubuntu и Docker Desktop с поддержкой Docker Compose.

Необходимое ПО: Git, Docker Engine / Docker Desktop, Docker Compose, Python 3, GNU Make.

Основные версии компонентов:

Компонент Версия
PostgreSQL 16-alpine
RustFS 1.0.3
RabbitMQ 4.1.8-management
Nginx 1.29-alpine
OpenTelemetry Collector Contrib 0.136.0
OpenTelemetry Python SDK 1.38.0
OpenTelemetry FastAPI instrumentation 0.59b0
Prometheus 3.5.0
Loki 3.5.5
Tempo 2.8.2
Grafana 12.1.1

Подготовка окружения:

cp .env.example .env

В .env необходимо установить собственные локальные значения паролей PostgreSQL, RabbitMQ, администратора Grafana и ключей S3. Для остальных параметров использовать значения и комментарии из .env.example.

Файл .env не должен попадать в Git. Секреты в отчёте не публикуются.

Сборка и запуск:

docker compose up -d --build

При запуске через Compose выполняются предусмотренные конфигурацией миграции PostgreSQL и инициализация приватного S3 bucket.

Проверить состояние:

docker compose ps -a

Проверить готовность бизнес-API:

curl http://127.0.0.1:8080/health/ready

Ожидаемый результат:

{"status":"ok"}

Проверить публичный контракт:

make test

Проверить корреляцию логов и трасс:

docker compose exec -T api1 python - < scripts/test-trace-correlation.py

Доступ к Grafana: http://localhost:3000. Логин администратора — admin; пароль задаётся через GRAFANA_ADMIN_PASSWORD.

Dashboard автоматически импортируется из файла observability/grafana/dashboards/messenger-lab6.json.

Безопасная остановка с сохранением данных:

docker compose down

Намеренное удаление всех учебных данных и volumes:

docker compose down -v

Последняя команда используется только при осознанном сбросе стенда, поскольку удаляет сохранённые данные приложений и подсистемы наблюдаемости.

Архитектура и решения

Схема процессов и хранилищ:

Client
  |
Nginx
  |
  +------ API1 / API2 ------ PostgreSQL
  |              |
  |              +---------- RustFS (S3)
  |
Dispatcher ---- RabbitMQ ---- Worker
     |                          |
     +------------+-------------+
                  |
             OTLP / HTTP
                  |
        OpenTelemetry Collector
                  |
          +-------+-------+
          |       |       |
     Prometheus  Loki   Tempo
          |       |       |
          +-------+-------+
                  |
                Grafana

Что перенесено из lab5:

  • Две реплики FastAPI за Nginx.
  • Авторизация, пользователи, чаты, сообщения и вложения.
  • PostgreSQL для транзакционных данных, сессий и заданий.
  • RustFS как S3-совместимое хранилище изображений.
  • RabbitMQ с устойчивой очередью image_jobs.
  • Отдельные процессы dispatcher и worker.
  • Асинхронная обработка PNG/JPEG и создание thumbnail.
  • Механизмы восстановления заданий, обработки повторных доставок и миграции БД.

Что добавлено в lab6:

  • OpenTelemetry SDK для API и worker.
  • Автоматические HTTP server spans FastAPI.
  • Consumer spans обработки изображений.
  • Счётчики HTTP-запросов и обработки заданий.
  • Гистограммы длительности HTTP-запросов и работы worker.
  • Структурированные логи с trace_id, span_id и service.name.
  • Отдельный OpenTelemetry Collector.
  • Prometheus, Loki, Tempo и Grafana.
  • Provisioning источников данных и импортируемого dashboard.
  • Скрипты проверки корреляции и контролируемых инцидентов.

Назначение хранилищ и источник истины:

PostgreSQL остаётся источником истины для пользователей, сообщений, метаданных и состояний заданий. RustFS хранит бинарные объекты изображений. RabbitMQ доставляет задания worker.

Prometheus хранит временные ряды метрик; Loki — структурированные логи; Tempo — трассы. Grafana обеспечивает отображение и поиск данных, но не заменяет эти хранилища. Collector принимает, обрабатывает и экспортирует телеметрию, не являясь долговременной базой данных.

Транзакционные границы:

Принятие изображения фиксируется сохранением исходных байтов в RustFS и записи задания в PostgreSQL. Передача задания в RabbitMQ допускает повторную доставку. Worker проверяет состояние задания и сохраняет результат до подтверждения обработки сообщения брокеру.

Между PostgreSQL и S3 отсутствует единая распределённая транзакция. Используются повторные попытки и идемпотентная обработка.

Ресурсы и конфигурация OpenTelemetry:

Для API применяется service.name=messenger-api, для worker — service.name=messenger-worker. Используются также service.version, service.instance.id и deployment.environment.name=lab.

API и worker отправляют OTLP/HTTP в Collector на otel-collector:4318. Collector экспортирует метрики в Prometheus-compatible endpoint, логи через OTLP/HTTP в Loki, трассы через OTLP/gRPC в Tempo.

Пароли, Authorization, session token, тексты сообщений и байты изображений не включаются в специально создаваемые события телеметрии. Пользовательские UUID не используются как labels метрик. Для HTTP-маршрутов используются шаблоны, а не фактические URL с идентификаторами.

Фактические имена метрик:

Логический сигнал Имя в Prometheus Единица
HTTP requests messenger_messenger_http_requests_total запросы
HTTP duration messenger_http_server_duration_milliseconds_bucket миллисекунды
Jobs processed / failed messenger_messenger_worker_jobs_processed_total попытки
Job processing duration messenger_messenger_worker_job_duration_seconds_bucket секунды

Для API error ratio числитель — HTTP 5xx, знаменатель — все учитываемые бизнес-запросы, без health checks. Значения p95 рассчитываются из гистограмм с агрегацией buckets. Миллисекунды HTTP duration преобразуются в секунды.

Ограничения архитектуры:

Сквозной trace context между HTTP upload и обработкой задания worker не реализован. Логи API и worker коррелируют со своими реальными трассами, но не образуют единую parent-child трассу через RabbitMQ.

Возможности дополнительных метрик очереди, насыщения ресурсов и alert rules относятся к более высокому уровню и в текущей реализации не заявлены.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS, бизнес-API работает с включённой телеметрией evidence/smoke.txt
Smoke после инцидентов make test PASS после восстановления PostgreSQL и worker evidence/smoke-after-incidents.txt
Collector и хранилища трёх сигналов docker compose ps -a Collector healthy; Prometheus, Loki, Tempo и Grafana запущены evidence/containers.txt
HTTP request counter Запрос Prometheus API Найдена messenger_messenger_http_requests_total evidence/prometheus-metrics.json
HTTP duration histogram Запрос Prometheus API Найдены buckets, sum и count HTTP duration evidence/prometheus-metrics.json
Worker jobs counter Выполнение make test и запрос Prometheus API Найден счётчик заданий с outcome evidence/prometheus-metrics.json
Worker duration histogram Выполнение make test и запрос Prometheus API Найдена гистограмма длительности worker evidence/prometheus-metrics.json
Структурированные логи API Запрос Loki / Grafana Explore Найдены HTTP-события с техническими атрибутами evidence/grafana-dashboard.png
Структурированные логи worker Журналы worker и запрос Loki Найдено событие Image job handled evidence/worker-telemetry.txt
Реальная трасса API Loki → Tempo по trace ID PASS, 4 span, включая server span evidence/trace-correlation.txt
Реальная трасса worker Loki → Tempo по trace ID PASS, consumer span image_job.process evidence/trace-correlation.txt
Импортируемый dashboard Provisioning Grafana Dashboard загружен, 8 панелей observability/grafana/dashboards/messenger-lab6.json
Контролируемый отказ worker Остановка worker, upload, восстановление PASS; задание сохранено, затем обработано evidence/incident-worker.txt
Контролируемый отказ PostgreSQL python3 scripts/test-db-incident.py 5/5 неудачных запросов, восстановление HTTP 201 evidence/incident-db.txt
Критерии уровня 4 Не заявлены Дополнительные метрики и alerts не реализованы Не применяется
Трек уровня 5 Не заявлен Не выполнялся Не применяется

Подтверждённая корреляция API:

  • Service: messenger-api
  • Event: HTTP request completed
  • Trace ID: c3ea28d96d7c536e222d8e4c7cba2727
  • Span ID: 3be2550ec51156e2
  • Результат: найден реальный HTTP server span POST /api/v1/auth/sessions.

Подтверждённая корреляция worker:

  • Service: messenger-worker
  • Event: Image job handled
  • Trace ID: af16dbcb7b7ca25b06d39902dc48afd8
  • Span ID: 644d3cda73387e3f
  • Результат: найден consumer span image_job.process.

Обе проверки завершились PASS: API and worker trace correlation.

Dashboard и конфигурации provisioning сохранены в репозитории, поэтому после чистого запуска они загружаются без ручной настройки через браузер.

Проверки инфраструктуры подтверждаются состоянием контейнеров и результатами отдельных запросов к Prometheus, Loki и Tempo; один только публичный smoke не считается доказательством работающей наблюдаемости.

Эксперименты и отказы

Гипотезы:

  1. При остановке worker API сохранит возможность принимать изображения, а принятые задания будут обработаны после восстановления worker.
  2. При остановке PostgreSQL запросы, требующие доступа к БД, начнут завершаться ошибками; после восстановления БД авторизация снова заработает.
  3. Метрики, логи и трассы позволят различить отсутствие фоновой обработки и недоступность базы данных.

Условия проведения:

  • Среда: локальный Docker Desktop с WSL Ubuntu.
  • Контейнеры: две API-реплики, PostgreSQL, RustFS, RabbitMQ, dispatcher, worker, Collector, Prometheus, Loki, Tempo, Grafana.
  • Нагрузка: синтетические операции публичного smoke и специальные последовательные запросы скриптов инцидентов.
  • Concurrency: в сценарии отказа БД проверочные запросы выполнялись последовательно.
  • Прогрев: перед отказом выполнялись успешные запросы к API.
  • Инцидент worker: принудительная остановка worker и дополнительная пауза 60 секунд.
  • Инцидент PostgreSQL: остановка контейнера БД, пять проверочных запросов и восстановление.
  • Аппаратная конфигурация, выделенные CPU/RAM и лимиты Docker: отдельно не фиксировались.
  • Продолжительная нагрузка с фиксированным arrival rate и несколькими уровнями concurrency: не выполнялась.
  • Повторяемость: приведены результаты одного зафиксированного прогона каждого контролируемого инцидента.

Зафиксированные измерения:

Для инцидента PostgreSQL:

Запрос Результат Длительность
До отказа HTTP 201 Не зафиксирована в выводе
Probe 1 TimeoutError 5,005 с
Probe 2 HTTP 503 0,046 с
Probe 3 HTTP 503 4,071 с
Probe 4 HTTP 503 0,038 с
Probe 5 HTTP 503 0,076 с
После восстановления HTTP 201 0,058 с

Во время отказа БД все пять запросов завершились неуспешно: четыре HTTP 503 и один клиентский тайм-аут.

В Grafana зафиксирован рост доли HTTP 5xx примерно до 67% в двухминутном окне, а также изменение p95 длительности запросов.

Отдельные нагрузочные измерения устойчивого RPS, p50/p95/p99 по серии прогонов, CPU/RAM и распределения задержек не собирались. Точки на dashboard характеризуют конкретный наблюдаемый период, но не являются результатом полноценного нагрузочного теста.

Таблица инцидентов:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка worker API принимает upload; задания остаются в queued HTTP 202, сообщение создано, после запуска worker статус ready Пауза 60 секунд; потеря принятого изображения не обнаружена
Перезапуск RabbitMQ и API при остановленном worker Принятое задание не теряется Статус queued сохранился после перезапуска После возобновления worker задание обработано
Повторное включение worker Появляется обработка и thumbnail Создан JPEG 256×160, оригинал проверен SHA-256 Точное время перехода в ready отдельно не измерялось
Остановка PostgreSQL Авторизация, зависящая от БД, перестаёт работать 4 HTTP 503 и 1 TimeoutError После восстановления БД — HTTP 201 за 0,058 с
Повторный smoke после отказов Вся бизнес-функциональность восстановлена make test — PASS Потерь подтверждённых данных в проверенных сценариях не обнаружено

Анализ инцидента worker:

На dashboard в период остановки сохранялись успешные HTTP-запросы, но новые успешные обработки worker не появлялись. После восстановления worker был зафиксирован новый успешный job и данные о длительности обработки.

Причина: отсутствие активного фонового обработчика, а не отказ API. Это подтверждено контролируемой остановкой контейнера и результатом PASS: durable worker recovery.

Доказательства: evidence/incident-worker.txt, evidence/incident-worker-dashboard.png, evidence/incident-worker-recovered.png.

Анализ инцидента PostgreSQL:

Во время остановки БД запросы авторизации завершались HTTP 503 или тайм-аутом. График 5xx в Grafana показал рост серверных ошибок. После восстановления PostgreSQL авторизация вернулась к HTTP 201.

Причина: недоступность PostgreSQL. Она подтверждается характером запросов, контролируемой остановкой контейнера, журналами и восстановлением после запуска БД.

Отдельные DB client spans отсутствуют, поэтому точная локализация по одной только трассе API ограничена.

Доказательства: evidence/incident-db.txt, evidence/incident-db-dashboard.png, evidence/incident-db-api-logs.txt, evidence/incident-db-postgres-logs.txt.

Ограничения и следующие шаги

Какие отказы выдерживаются:

  • Остановка worker не приводит к потере принятого задания при сохранности PostgreSQL и RustFS.
  • Перезапуск RabbitMQ и API не нарушает сохранность зафиксированного задания.
  • После восстановления PostgreSQL приложение возвращается к нормальной работе.
  • Публичный smoke проходит при включённой телеметрии.

Какие отказы и ограничения остаются:

  • PostgreSQL, RustFS и RabbitMQ развёрнуты одиночными экземплярами и остаются точками отказа.
  • При удалении volumes учебные данные и история наблюдаемости теряются.
  • Трассы API и worker не связаны единым W3C-контекстом через брокер.
  • Нет отдельной SQL-инструментации с DB client spans.
  • Метрики глубины и возраста очереди, насыщения ресурсов и end-to-end времени до ready не реализованы.
  • Alert rules и автоматическая проверка их переходов в firing/resolved не реализованы.
  • Не проводилось отдельное испытание недоступности backend-телеметрии и измерение потерь.
  • Метрики worker могут сбрасываться при перезапуске процесса; для анализа необходимы временные ряды и события восстановления.
  • Не выполнялись длительные нагрузочные испытания и измерения производительности с фиксированными hardware limits.

Следующие шаги:

  1. Добавить передачу W3C trace context через RabbitMQ.
  2. Инструментировать запросы к PostgreSQL и S3 отдельными spans.
  3. Добавить метрики очереди и насыщения ресурсов.
  4. Добавить alert rules с порогами, окнами и runbook.
  5. Провести повторяемые нагрузочные испытания с фиксацией CPU/RAM, RPS и p50/p95/p99.
  6. Протестировать частичную недоступность Loki, Tempo и Collector и измерить потери телеметрии.

Вывод: реализована работающая подсистема наблюдаемости на основе OpenTelemetry, Prometheus, Loki, Tempo и Grafana. Подтверждён экспорт трёх сигналов, обнаружение реальных трасс по связанным логам, работоспособность dashboard и восстановление системы после двух контролируемых отказов. Заявленный уровень — оценка 3.