forked from mtusi2026/mtusi2026lab6
329 lines
24 KiB
Markdown
329 lines
24 KiB
Markdown
# Отчёт — лабораторная 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. |