From 2b721844feb9ccf772c34e83d53e533a9de0d185 Mon Sep 17 00:00:00 2001 From: gytall Date: Fri, 20 Nov 2026 17:18:20 +0300 Subject: [PATCH] fix report.md --- REPORT.md | 150 ++++++++++++++++-------------------------------------- 1 file changed, 45 insertions(+), 105 deletions(-) diff --git a/REPORT.md b/REPORT.md index 5f6fc17..b0f2659 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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-часовым окном.