Files
mtusi2026lab6/LAB6_GUIDE.md
T

84 lines
6.4 KiB
Markdown
Raw 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.
# Как работает lab6 и что объяснять на защите
Автор: **Каменский Андрей, БПИ2301**.
## Что осталось от lab5
Картинка полностью передаётся API, проходит базовые проверки и сохраняется в MinIO
в staging/. В одной транзакции PostgreSQL создаются вложение queued и job/outbox.
API отвечает 202. Dispatcher отправляет job в отдельный Redis Streams broker.
Worker получает её, читает исходник из MinIO, создаёт thumbnail, crop и WebP,
сохраняет результат и фиксирует ready. Оригинал не перекодируется.
RabbitMQ не нужен, потому что Redis Streams даёт хранимый журнал, consumer groups,
pending deliveries и подтверждения. Redis очереди отделён от Redis сессий.
Данные очереди лежат в volume, включены AOF, appendfsync=always и noeviction.
| Механизм | Что делает у нас |
| --- | --- |
| XADD | Dispatcher добавляет ID задания и служебные поля в Stream |
| XREADGROUP | Worker получает очередную доставку в consumer group |
| Pending Entries List | Хранит доставки, которые consumer ещё не подтвердил |
| XAUTOCLAIM | Позволяет забрать зависшую неподтверждённую доставку |
| XACK | Подтверждает результат после DB COMMIT |
| XDEL | Удаляет уже подтверждённую запись, чтобы Stream не рос бесконечно |
| Outbox в PostgreSQL | Сохраняет намерение отправки, если broker недоступен |
| Lease и DB row lock | Защищают захват и восстанавливают работу после смерти worker |
Один consumer берёт по одной записи; WORKER_CONCURRENCY задаёт число consumers.
Повтор доставки нормален: используем стабильный job_id и детерминированные ключи
результатов. Ready-дубль подтверждается без нового resize. Временные ошибки
повторяются с backoff/jitter, максимум пять попыток на цикл; постоянные дают failed.
CLI позволяет явно повторить failed и пишет audit.
## Что нового в шестой
Теперь каждый HTTP-запрос получает trace. Внутри него есть spans — отдельные
участки работы: db.SELECT/INSERT/UPDATE, s3.PUT/GET, queue.publish, queue.consume,
image.transform. Span содержит начало, конец, родителя и результат.
После HTTP-ответа worker работает в другом процессе. Чтобы связь не потерялась,
мы сохраняем traceparent/tracestate в job, dispatcher извлекает их, создаёт
producer span и записывает новый carrier в очередь. Worker создаёт consumer span
с этим родителем. Retry сохраняет context попытки перед повторной публикацией.
Логи http.completed/job.started/job.completed/db.error — структурный JSON.
trace_id связывает их с трассой, span_id указывает конкретную операцию.
request_id связывает HTTP-ответ и соответствующее событие. В telemetry не передаются
Authorization, пароль, текст сообщения, изображение, SQL или filename.
| Компонент | Роль |
| --- | --- |
| OpenTelemetry SDK | Создаёт spans, counters/histograms и структурные события в API/worker |
| Collector | Принимает OTLP, ограничивает память, группирует и отправляет данные |
| Prometheus | Хранит временные ряды и вычисляет alert rules |
| Loki | Хранит логи, позволяет найти события по trace_id |
| Tempo | Хранит трассы и причинные связи между процессами |
| Grafana | Показывает данные из трёх источников; не заменяет эти хранилища |
## Почему метрики не содержат chat_id
Каждое новое значение label создаёт новый временной ряд. UUID чатов или вложений
дали бы неограниченный рост. Поэтому route — шаблон /chats/{chat_id}/messages,
а labels — method, route, status_class, outcome, job_type или queue.
Технические trace/span IDs находятся в логах/трассах, не в labels метрик.
## Что значит p95
95% измерений попали ниже этого времени. Мы собираем histogram buckets и
агрегируем buckets всех API-реплик, затем применяем histogram_quantile.
Усреднять p95 разных реплик или заменять p95 средней задержкой неправильно.
## Что показать
1. make test: весь бизнес-API работает с включённой телеметрией.
2. Dashboard в Grafana: свежие RPS/latency, очередь и worker.
3. tests/observability.py: один upload найден в Tempo вместе с producer/consumer,
DB/S3 и связанными логами API/worker.
4. Prometheus /alerts: правила и локальные firing/resolved.
5. RUNBOOK.md: как отличить остановленный worker от ожидания INSERT в БД.
Недоступная telemetry не участвует в /health/ready. SDK экспортирует в фоне,
очереди ограничены; Collector при длительном отказе backend теряет telemetry,
но не бизнес-задания. Эти ограничения описаны в отчёте.