fix report.md
This commit is contained in:
@@ -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-часовым окном.
|
||||
|
||||
Reference in New Issue
Block a user