fix report.md

This commit is contained in:
2026-11-20 17:18:20 +03:00
parent 27a3a6895f
commit 2b721844fe
+45 -105
View File
@@ -1,7 +1,7 @@
# Отчёт
# Отчёт - лабораторная 6
- Автор: Григорян Илья Мурадович, БПИ2303.
- Цель: оценка **4**, лабораторная «Наблюдаемость».
- Цель: оценка **4**
- Источники: OpenTelemetry SDK 1.45.1, FastAPI, SQLAlchemy 2.1.4,
[внутренние метрики Collector](https://opentelemetry.io/docs/collector/internal-telemetry/),
[контракт наблюдаемости](contracts/observability.md). Помощь Codex.
@@ -20,53 +20,32 @@ make down
```
API доступен на http://localhost:18081, дашборд — на
http://localhost:13000/d/messenger-overview. Для подключения к хранилищам с
компьютера используйте [локальный режим](LOCAL_CONNECTIONS.md).
http://localhost:13000/d/messenger-overview.
Инициализация создаёт только отсутствующие настройки и секреты. Миграции и
настройка приватного bucket выполняются при запуске. `make down` сохраняет тома.
## Архитектура и трассировка
Две реплики API за nginx, PostgreSQL для сообщений и состояния заданий, Redis
для сессий, MinIO для файлов, RabbitMQ для доставки, отдельные publisher,
worker и cleanup. HTTP 202 возвращается после устойчивого приёма вложения.
Publisher отмечает доставку после подтверждения RabbitMQ, worker подтверждает
попытку после устойчивой фиксации исхода.
Две реплики API за nginx. PostgreSQL хранит сообщения и состояние заданий,
Redis — сессии, MinIO — файлы, RabbitMQ доставляет задания worker.
Миграции и настройка MinIO выполняются при запуске, доступы передаются
через файловые секреты. Версии, проверки готовности и тома заданы в
[compose.yaml](compose.yaml).
| Роль | Сервис и версия | Готовность, данные |
| --- | --- | --- |
| Балансировщик | nginx 1.28.0 | `/lb-health`, публикует API на `LB_HOST_PORT` |
| HTTP API | api, Python 3.12 | `/health/ready`, две реплики, `api:8080` |
| База | postgres 16.10 | `pg_isready`, `pgdata`, `postgres:5432` |
| Сессии | redis 7.4.2 | аутентифицированный `PING`, `redisdata`, `redis:6379` |
| Файлы | minio RELEASE.2025-10-15T17-29-55Z | `/minio/health/ready`, `miniodata`, `minio:9000` в сети `objects` |
| Очередь | broker, RabbitMQ 4.4.0 | `rabbitmq-diagnostics ping`, `rabbitmqdata`, `broker:5672` |
API, publisher и worker отправляют телеметрию по OTLP в Collector.
Prometheus хранит метрики, Loki — структурные логи, Tempo — трассы.
Grafana читает три источника и автоматически загружает дашборд.
История хранится 72 часа в именованных томах.
Учётные данные PostgreSQL, Redis, MinIO и RabbitMQ передаются через файловые
секреты Compose. Схему создаёт migrate, bucket и права — minio-bootstrap,
устойчивую очередь объявляют publisher и worker.
API сохраняет W3C `traceparent` и `tracestate` вместе с заданием. Publisher
создаёт дочерний producer span и передаёт контекст через заголовки RabbitMQ.
Каждая попытка получает свой consumer span в той же трассе. Успешная попытка
добавляет операции чтения и записи S3 и фиксации `ready` в PostgreSQL.
API, publisher и worker отправляют OTLP HTTP/protobuf в Collector 0.165.0.
Prometheus 3.16.0 собирает метрики, Loki 3.7.10 хранит структурные логи,
Tempo 2.9.0 хранит трассы. Grafana 13.3.1 читает три источника и загружает
дашборд из репозитория. История хранится в именованных томах, срок хранения 72 ч.
`deployment.environment.name` берётся из `APP_ENV`. В проверенном стенде
использовано значение `development`.
При приёме вложения в транзакции сохраняются только W3C `traceparent` и
`tracestate` из текущего контекста. Publisher создаёт producer span как
потомка HTTP upload и переносит его контекст в заголовки AMQP. Каждая попытка,
в том числе после retry или replay, получает собственный дочерний consumer
span со своим номером и исходом. Успешная попытка показывает чтение staging,
запись объектов S3 и фиксацию ready в PostgreSQL. У старых строк контекст
может отсутствовать, обработка сохраняется.
В логах есть timestamp, severity, event и trace/span ID. HTTP-ответ и лог
связаны через X-Request-Id, лог и трасса — через TraceID. У метрик только
ограниченные значения route template, method, status class, queue, job type
и outcome. Идентификаторы файлов используются в логах получения задания
для поиска нужной попытки. Тексты сообщений, пароли, токены, URL с
подписью, SQL и содержимое файлов в телеметрию не передаются.
HTTP-ответ и лог связаны по `X-Request-Id`, лог и трасса — по `trace_id`.
Метрики группируются по шаблону маршрута, методу, классу ответа, очереди,
типу и исходу задания. ID отдельных объектов используются для поиска в
логах, а тексты сообщений, секреты и содержимое файлов в телеметрию не передаются.
## Метрики и цели
@@ -83,14 +62,11 @@ span со своим номером и исходом. Успешная попы
| До готовности вложения | `histogram_quantile(0.95, sum by(le)(rate(messenger_job_time_to_ready_seconds_bucket[5m])))` | с |
| Экспорт Collector | `otelcol_exporter_queue_size`, `otelcol_exporter_queue_capacity` | пакеты |
Очередь измеряется по устойчивому состоянию `queued` в PostgreSQL, включая
ещё не опубликованные и отложенные попытки. Возраст считается от первичного
принятия. Время до ready измеряется для успешных заданий от записи принятия
до фиксации ready, включая ожидание и повторы. Гистограммы объединяются по
границам buckets перед вычислением процентиля. CPU и RSS относятся к процессу
Python и не включают подпроцесс resize.
Суффикс `_ratio` добавляет экспортёр Prometheus для безразмерного unit `1`.
Для глубины очереди и пула эти ряды содержат абсолютные количества.
Глубина очереди — число заданий в состоянии `queued` в PostgreSQL,
включая отложенные повторы. Возраст считается от первого приёма.
Время до `ready` включает ожидание и повторы. Процентили вычисляются
по объединённой гистограмме всех реплик. Ряды глубины и пула с суффиксом
`_ratio` содержат абсолютные количества.
SLI доступности — доля бизнес-запросов без 5xx. SLO — ≥99% за скользящие
24 часа. Для проверки используйте отношение сумм `increase(...[24h])`,
@@ -103,65 +79,29 @@ SLI доступности — доля бизнес-запросов без 5xx
## Диагностика инцидентов
1. **Рост 5xx.** В Grafana сопоставить частоту запросов, долю 5xx и задержку.
По X-Request-Id найти связанный лог и открыть TraceID. Ошибка на
`postgres.checkout` вместе с событием `dependency.unavailable`
указывает на проблему получения соединения с БД. После восстановления
проверить `/health/ready` и исчезновение firing.
2. **Растёт очередь.** Сверить глубину, возраст и занятость worker. При
остановленном worker задания принимаются, а новые попытки не появляются.
После восстановления проверить уменьшение очереди и исчезновение firing.
В Tempo открыть трассу upload и сравнить исходы отдельных попыток, затем
проверить spans S3/БД и состояние ready.
3. **Недоступен Loki.** Prometheus продолжает собирать бизнес-метрики и
внутренние метрики Collector. Сравнить число успешных сообщений, RSS,
размер экспортной очереди и прирост счётчиков отказа экспорта/постановки
в очередь. После старта Loki проверить появление новых связанных логов.
| Инцидент | Как найти причину и подтвердить восстановление |
| --- | --- |
| PostgreSQL остановлен | Рост 5xx → лог по `X-Request-Id` → ERROR span `postgres.checkout` в связанной трассе. Оповещение вошло в firing через 32,4 с и снялось через 67,5 с от начала сценария. Готовность API восстановилась. |
| Worker остановлен | Растёт возраст очереди, новые попытки отсутствуют. Оповещение сработало через 28,6 с после приёма. После пяти временных ошибок и ручного replay шестая попытка завершилась `ready`, глубина вернулась к нулю, оповещение снялось. В трассе `ff8352e27270fbc16fea7216c3ff45c0` видны все попытки и операции S3/БД. |
| Loki остановлен | В Prometheus смотрим бизнес-запросы, RSS и экспортную очередь Collector. За 51 с записано 204 сообщения, потеряно 6 логов после повторов отправки. Пик очереди — 48 из 256 пакетов, RSS — 228–231 MiB. После запуска Loki найден новый связанный лог. |
Collector использует memory limiter 192 MiB со spike 32 MiB, пакетирование до
256 записей, очередь 256 пакетов на экспортёр, по два потребителя
на очередь и до 30 с повторов доставки. Контейнер ограничен 256 MiB. SDK
имеет ограниченные очереди span/log и таймауты. Потери считаются по
счётчикам Collector для остановленного Loki. Общие потери вне Collector
этими счётчиками не измеряются.
Collector использует memory limiter (192 MiB, запас для всплесков 32 MiB),
пакеты до 256 записей, очереди по 256 пакетов для Loki и Tempo и повторы
до 30 с. Лимит контейнера — 256 MiB. Потери измерены по счётчикам Collector
для этого короткого отказа.
## Полный прогон
`make verify` поднимает один отдельный стенд с телеметрией, выполняет регрессию,
smoke, нагрузку, проверку сквозных трасс, оповещений и восстановления после
отказов, а также persistence/failover. В конце удаляются контейнеры, сеть и
тома только проверочного проекта. Настройки, общий кэш образов и данные
основного стенда сохраняются.
`make verify` запускает регрессию, smoke, нагрузку, сценарии отказов,
проверки сохранности и переключения реплик на отдельном стенде, затем
удаляет его контейнеры, сеть и тома.
Результаты прогона от 19.11.2026 сохранены в [журнале проверок](evidence/verification.json)
и [доказательствах наблюдаемости](evidence/observability.json).
Итог **PASS**, с 18:50 до 19:03 МСК. Контракт, OpenAPI, конфигурация и запуск
Compose, публичный smoke, наблюдаемость, persistence и failover прошли.
Регрессия: 206 тестов за 98,89 с. Инвентаризация после очистки показала
0 контейнеров, 0 сетей и 0 томов проверочного проекта.
Прогон 19.11.2026, 18:50–19:03 МСК — **PASS**. Регрессия: **206 тестов**
за 98,89 с. Нагрузка: 100 успешных сообщений, 0 ошибок, около 10 запросов/с.
Клиентские p50/p95/p99 — 18,0 / 39,6 / 46,0 мс. Проверены панели, связность
трасс и логов, приватность и сохранение истории после перезапуска.
Доказательства сохранены в [журнале проверок](evidence/verification.json)
и [результатах наблюдаемости](evidence/observability.json).
Нагрузка: 100 успешных сообщений, 0 ошибок, 10,078 запроса/с. Клиентские
p50/p95/p99 — 18,036 / 39,623 / 45,954 мс. Проверены все запросы панелей,
корреляция логов и трасс, отсутствие запрещённых полей и сохранение истории
после перезапуска хранилищ. В выборке приватности 413 логов.
| Сценарий | Что зафиксировал прогон |
| --- | --- |
| PostgreSQL остановлен | HTTP 503, связанный ERROR span `postgres.checkout` и `dependency.unavailable` с `TimeoutError`. Firing замечен через 32,4 с от начала сценария, снятие — через 67,5 с. Trace ID `020e820d68045ad3195e842244670b11`. |
| Worker остановлен | Глубина 1, возраст 25,6 с на момент проверки. Firing замечен через 28,6 с после приёма задания. После исчерпания пяти инъецированных временных ошибок оператор выполнил replay, шестая попытка завершилась `ready`, глубина вернулась к 0, оповещение снялось. |
| Loki остановлен | 204 сообщения записаны при недоступных логах. За 51 с измерено 6 записей, потерянных после повторов экспорта, и 0 отказов постановки в очередь. Пик очереди 48 из 256 пакетов, RSS 228–231 MiB при лимите 256 MiB. После запуска Loki найден новый лог со связанной трассой. |
Трасса повтора в Tempo — `ff8352e27270fbc16fea7216c3ff45c0`. В ней проверены
родительские связи HTTP upload → `rabbitmq.publish` → `attachment.process.v1`
для всех попыток и spans `s3.read_staging`, `s3.write_result`,
`postgres.commit_ready` успешной попытки. Контрольная трасса без инъекции —
`ad41b35e5e8b02c32f7a7b74d7b6278a`. После очистки их идентификаторы и дерево
spans остаются в JSON с доказательствами.
## Ограничения
Один Docker-host без высокой доступности и защиты от потери диска.
Контролируемая нагрузка проверяет сценарии и пригодность диагностики.
Долговременное соблюдение SLO требует наблюдения за полным 24-часовым окном.
В сценарии Loki измерен краткий отказ. Замеры RSS показывают небольшой рост,
а верхняя граница памяти обеспечивается настройками очередей и лимитом контейнера.
Стенд работает на одном Docker-хосте. Соблюдение SLO требует наблюдения
за полным 24-часовым окном.