Files
2026-11-19 18:16:24 +03:00

108 lines
12 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
- Автор, группа: Бондаренко Мария, БПИ2302
- Целевая оценка: 4
## 1. Архитектура и стек наблюдаемости
В рамках лабораторной работы для распределённого сервиса мессенджера развёрнут единый контур наблюдаемости на базе 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.
---
## 2. Инструментирование сервисов
### 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-полезной нагрузке задачи.
### 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).
---
## 3. Реализованные метрики, дашборды и алерты
### 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.
### 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. |