forked from mtusi2026/mtusi2026lab6
report
This commit is contained in:
@@ -1,37 +1,108 @@
|
||||
# Отчёт — лабораторная 6
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Бондаренко Мария, БПИ2302
|
||||
- Целевая оценка: 4
|
||||
|
||||
## Запуск из чистого clone
|
||||
## 1. Архитектура и стек наблюдаемости
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
В рамках лабораторной работы для распределённого сервиса мессенджера развёрнут единый контур наблюдаемости на базе OpenTelemetry и стека LGTM/Prometheus:
|
||||
|
||||
## Архитектура и решения
|
||||
* Сбор и маршрутизация телеметрии — OpenTelemetry Collector (otel-collector:4317/4318):
|
||||
* принимает сигналы по протоколу OTLP (gRPC и HTTP/protobuf) от messenger-api и messenger-worker;
|
||||
* применяет процессоры memory_limiter (ограничение памяти 256 MiB) и batch (пакетная отправка по 256 записей или каждые 2 секунды);
|
||||
* маршрутизирует данные в три независимых хранилища с использованием очередей отправки:
|
||||
* Метрики -> prometheusremotewrite;
|
||||
* Трейсы -> otlphttp/tempo;
|
||||
* Логи -> otlphttp/loki.
|
||||
* Хранилище метрик и правила алертинга — Prometheus:
|
||||
* запущен с флагом --web.enable-remote-write-receiver и ретеншеном 7 дней;
|
||||
* оценивает правила оповещений из /etc/prometheus/alerts.yml с интервалом 15s.
|
||||
* Хранилище структурированных логов — Grafana Loki:
|
||||
* использует схему хранения tsdb и локальное файловое хранилище;
|
||||
* индексирует атрибуты ресурса service.name, service.namespace, deployment.environment, а также поддерживает allow_structured_metadata: true.
|
||||
* Хранилище распределённых трассировок — Grafana Tempo:
|
||||
* принимает OTLP HTTP трейсы на порту 4318, хранит блоки локально с периодом хранения 168 часов.
|
||||
* Визуализация и корреляция — Grafana:
|
||||
* настроена через provisioning (datasources.yml и dashboards.yml);
|
||||
* реализована двусторонняя связка Logs <-Traces:
|
||||
* в источнике Loki настроено derivedFields по регулярному выражению "trace_id":"([0-9a-f]{32})" для перехода из строки лога в соответствующий трейс в Tempo;
|
||||
* в источнике Tempo настроено tracesToLogsV2 с фильтрацией по TraceID и тегу service.name.
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
---
|
||||
|
||||
## Доказательства критериев
|
||||
## 2. Инструментирование сервисов
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
### 2.1. Сервис messenger-api (app.py)
|
||||
* Инициализированы TracerProvider, MeterProvider (экспорт каждые 5000 ms) и LoggerProvider через OTLP HTTP экспортеры.
|
||||
* Подключено автоматическое инструментирование FastAPI и кастомный HTTP middleware telemetry_middleware, фиксирующий низкокардинальные атрибуты.
|
||||
* Реализовано структурированное JSON-логирование, автоматически извлекающее активный контекст OpenTelemetry и добавляющее в каждую запись поля trace_id (32 hex-символа) и span_id (16 hex-символов), а также контекст запроса (method, path, status_code).
|
||||
* Реализован потокобезопасный пул соединений к PostgreSQL с корректным возвратом соединений в блоках finally.
|
||||
* При постановке задачи обработки вложения в таблицу outbox вызывается inject(job_payload), что сохраняет traceparent в JSON-полезной нагрузке задачи.
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
### 2.2. Асинхронный обработчик messenger-worker (worker.py)
|
||||
* Настроен экспорт метрик, логов и спанов с именем сервиса messenger-worker.
|
||||
* При чтении задачи из Redis Stream (attachment_jobs) воркер извлекает контекст трассировки с помощью extract(job) и открывает дочерний спан worker.process_attachment с атрибутами job.pipeline_version, job.attempt, job.outcome.
|
||||
* Реализован конвейер генерации трёх вариантов изображений (thumbnail 256px JPEG, optimized 1280px WebP, crop 128x128 JPEG), контроль таймаута (JOB_TIMEOUT_SECONDS=30), экспоненциальный backoff при временных сбоях и перенос исчерпавших попытки задач в Dead Letter Queue (attachment_jobs_dlq).
|
||||
|
||||
## Эксперименты и отказы
|
||||
---
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
## 3. Реализованные метрики, дашборды и алерты
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
### 3.1. Набор метрик
|
||||
1. Метрики API (RED и зависимости):
|
||||
* http_server_requests_total (Counter) — общее число HTTP-запросов по методу, маршруту и коду ответа;
|
||||
* http_server_errors_total (Counter) — количество ответов со статусом 4xx и 5xx;
|
||||
* http_server_request_duration_seconds (Histogram) — распределение длительности обработки HTTP-запросов;
|
||||
* http_server_dependency_errors_total (Counter) — счётчик ошибок внешних зависимостей (postgres, redis, s3, outbox, readiness);
|
||||
* db_pool_connections (ObservableGauge) — состояние соединений пула PostgreSQL в разрезе state="used" и state="idle".
|
||||
2. Метрики Worker (очередь, насыщение, длительность):
|
||||
* worker_jobs_total (Counter) — количество завершённых задач по статусу (success, failed);
|
||||
* worker_job_duration_seconds (Histogram) — время обработки задачи воркером;
|
||||
* worker_jobs_in_progress (UpDownCounter) — число задач, обрабатываемых в текущий момент (saturation);
|
||||
* worker_job_retries_total (Counter) — число запланированных повторных попыток по типу исключения (reason);
|
||||
* worker_queue_depth (ObservableGauge) — текущая глубина очереди Redis Stream attachment_jobs;
|
||||
* worker_oldest_job_age_seconds (ObservableGauge) — возраст самой старой необработанной задачи в очереди.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
### 3.2. Дашборды Grafana
|
||||
Подготовлены и автоматически загружены два дашборда в папку Messenger:
|
||||
* MTUSI Messenger — Lab 6 (Grade 3) (mtusi-messenger-lab6-g3): базовый мониторинг RPS, частоты ошибок, p95 задержки API, скорости и p95 длительности задач воркера, а также поток структурированных логов из Loki.
|
||||
* MTUSI Messenger — Lab 6 (Grade 4) (mtusi-messenger-lab6-g4): расширенный операционный дашборд, включающий:
|
||||
* API RPS (req/s) и API Error Ratio (%);
|
||||
* API Latency p50 / p95 / p99 (s);
|
||||
* DB Connection Pool (used / idle);
|
||||
* Queue Depth & Oldest Job Age;
|
||||
* Worker Saturation & Retries;
|
||||
* Worker Job Duration p50 / p95 / p99 (s);
|
||||
* панель Logs with TraceID (Loki) для быстрой навигации в Tempo.
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
### 3.3. Правила алертинга Prometheus (alerts.yml)
|
||||
Настроены две группы правил с интервалом оценки 15s:
|
||||
* MessengerApiHighErrorRate (warning) — доля ошибок API превышает 5% в течение 30s при нагрузке > 0.2 req/s.
|
||||
* MessengerApiDependencyErrors (critical) — зафиксированы ошибки обращения к PostgreSQL, Redis, S3 или в работе outbox в течение 30s.
|
||||
* MessengerApiHighLatencyP95 (warning) — 95-й перцентиль времени ответа API превышает 1.0s в течение 1m.
|
||||
* MessengerWorkerJobFailures (warning) — появление задач воркера со статусом failed в течение 30s.
|
||||
* MessengerWorkerQueueLag (critical) — возраст самой старой задачи превышает 30s или глубина очереди превышает 20 сообщений в течение 30s.
|
||||
|
||||
---
|
||||
|
||||
## 4. Проверка работоспособности и сквозной корреляции
|
||||
|
||||
1. Проверка статуса компонентов и приёма телеметрии:
|
||||
* Все контейнеры инфраструктуры (postgres, redis, s3, prometheus, loki, tempo, otel-collector, grafana) и приложения (api-1, api-2, worker, nginx) запущены и проходят проверки healthcheck.
|
||||
* В Prometheus подтверждено поступление временных рядов от otel-collector через Remote Write и активный статус правил в разделе /alerts.
|
||||
2. Сквозной пользовательский сценарий с вложением:
|
||||
* Выполнена регистрация пользователя (POST /api/v1/users), создание сессии (POST /api/v1/auth/sessions), создание чата (POST /api/v1/chats) и загрузка изображения (POST /api/v1/chats/{chat_id}/attachments).
|
||||
* Воркер забрал задачу из потока attachment_jobs, сгенерировал варианты thumbnail, optimized, crop, сохранил их в бакет messenger-attachments в S3 и перевёл статус вложения в ready.
|
||||
3. Проверка связки Metrics -> Logs -> Traces:
|
||||
* По всплеску на графиках Grafana открыта панель логов Loki, где для HTTP-запроса загрузки вложения зафиксирован JSON-лог с полем trace_id.
|
||||
* Переход по ссылке TraceID в Tempo отобразил единый распределённый трейс, начинающийся со спана POST /api/v1/chats/{chat_id}/attachments в сервисе messenger-api и продолжающийся дочерним спаном worker.process_attachment в сервисе messenger-worker.
|
||||
|
||||
---
|
||||
|
||||
## 5. Диагностика типовых инцидентов по данным телеметрии
|
||||
|
||||
| Сценарий инцидента | Проявление на дашборде и в алертах | Локализация в Loki и Tempo |
|
||||
| :--- | :--- | :--- |
|
||||
| Остановка или деградация worker | Рост worker_queue_depth и линейный рост worker_oldest_job_age_seconds; срабатывание критического алерта MessengerWorkerQueueLag. | В логах messenger-api задачи успешно записываются в outbox и Redis Stream, однако спаны worker.process_attachment в Tempo отсутствуют до момента перезапуска воркера, после чего накопившаяся очередь дренируется. |
|
||||
| Недоступность S3 (SeaweedFS) при загрузке | Всплеск API Error Ratio (%) (ответы 503), рост http_server_dependency_errors_total{component="s3"}, срабатывание MessengerApiDependencyErrors и MessengerApiHighErrorRate. | Поиск в Loki по status_code=503 выявляет логи с trace_id; в Tempo трейс обрывается на спане загрузки в S3 без постановки задачи в outbox. |
|
||||
| Загрузка повреждённого файла изображения | Воркер фиксирует неудачную задачу (worker_jobs_total{status="failed"}), срабатывает алерт MessengerWorkerJobFailures без повторных ретраев (перманентная ошибка). | В логах messenger-worker фиксируется запись "Permanent image error" с error_code="invalid_image" и trace_id, позволяющая отследить исходный запрос загрузки в messenger-api. |
|
||||
Reference in New Issue
Block a user