Files
mtusi2026lab6/REPORT.md

329 lines
24 KiB
Markdown
Raw Permalink 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
- **Автор, группа:** Матвиенко Павел, БПИ2304
- **Целевая оценка; выбранный трек 5, если нужен:** 3.
- **Commit/PR:** ad8db1f32b898ae43df22b1d3c0a431e553beff8; https://gitea.privcloud.tech/mtusi2026/mtusi2026lab6/pulls/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 |
**Подготовка окружения:**
```bash
cp .env.example .env
```
В `.env` необходимо установить собственные локальные значения паролей PostgreSQL, RabbitMQ, администратора Grafana и ключей S3. Для остальных параметров использовать значения и комментарии из `.env.example`.
Файл `.env` не должен попадать в Git. Секреты в отчёте не публикуются.
**Сборка и запуск:**
```bash
docker compose up -d --build
```
При запуске через Compose выполняются предусмотренные конфигурацией миграции PostgreSQL и инициализация приватного S3 bucket.
Проверить состояние:
```bash
docker compose ps -a
```
Проверить готовность бизнес-API:
```bash
curl http://127.0.0.1:8080/health/ready
```
Ожидаемый результат:
```json
{"status":"ok"}
```
Проверить публичный контракт:
```bash
make test
```
Проверить корреляцию логов и трасс:
```bash
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`.
**Безопасная остановка с сохранением данных:**
```bash
docker compose down
```
**Намеренное удаление всех учебных данных и volumes:**
```bash
docker compose down -v
```
Последняя команда используется только при осознанном сбросе стенда, поскольку удаляет сохранённые данные приложений и подсистемы наблюдаемости.
## Архитектура и решения
**Схема процессов и хранилищ:**
```text
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.