From 67039fd30daebdc27982067cda801ab617003d1f Mon Sep 17 00:00:00 2001 From: thefankor Date: Fri, 20 Nov 2026 19:33:15 +0300 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BA=D1=80=D1=8B=D1=82=D1=8C=20?= =?UTF-8?q?=D1=82=D1=80=D0=B5=D0=B1=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8=D1=8F=20?= =?UTF-8?q?=D0=9B=D0=A06=20=D0=BD=D0=B0=20=D0=BE=D1=86=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D1=83=204?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 5 +- REPORT.md | 43 +- docs/lab6-implementation.md | 813 ---------------------------- docs/plan/2026-11-17-lab6-grade4.md | 637 ---------------------- evidence/2026-11-17-results.md | 20 +- evidence/load.json | 4 + infra/otel/collector.yaml | 8 +- tests/README.md | 6 +- tests/alert_scenarios.py | 72 +++ tests/retry_trace.py | 144 +++++ tests/telemetry_outage.py | 43 +- 11 files changed, 323 insertions(+), 1472 deletions(-) delete mode 100644 docs/lab6-implementation.md delete mode 100644 docs/plan/2026-11-17-lab6-grade4.md create mode 100644 tests/retry_trace.py diff --git a/Makefile b/Makefile index 7bec4d4..6682322 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) OBSERVABILITY_COMPOSE = docker compose -f compose.yaml -f compose.observability-tests.yaml -.PHONY: help check validate test test-observability test-alert-worker test-alert-database test-telemetry-outage load test-persistence test-failover +.PHONY: help check validate test test-observability test-retry-trace test-alert-worker test-alert-database test-telemetry-outage load test-persistence test-failover help: @echo "check: offline structure; validate: full OpenAPI; test: public API; test-observability: Grafana/Prometheus/Loki/Tempo" @@ -22,6 +22,9 @@ test: test-observability: $(OBSERVABILITY_COMPOSE) run --rm observability-test +test-retry-trace: + $(PYTHON) tests/retry_trace.py --base-url "$(BASE_URL)" + test-alert-worker: $(PYTHON) tests/alert_scenarios.py worker --base-url "$(BASE_URL)" diff --git a/REPORT.md b/REPORT.md index 9832c8b..09add27 100644 --- a/REPORT.md +++ b/REPORT.md @@ -73,6 +73,8 @@ SDK использует bounded batch queues по 2048 элементов и ti по 500 элементов, два consumer, exponential retry не дольше 30 с. Поэтому отказ Loki/Tempo приводит к ограниченной потере telemetry, а не блокировке API или неограниченному росту RAM. +Collector self-metrics экспортируются через `readers.pull` на `:8888`; +Prometheus сохраняет RSS, размеры очередей и `send_failed` counters. Секреты и пользовательское содержимое не экспортируются. `safe_extra` отбрасывает пароли, tokens, Authorization, secrets, message body, image bytes и signed URL. @@ -136,17 +138,28 @@ production defaults. У каждого правила есть dashboard/panel l | Публичный API с telemetry | `make test` | `PASS: lab6 public API scenario` | `tests/smoke.py` | | Dashboard/alerts/3 backends | `make test-observability` | PASS: dashboard, alerts, metrics, logs, cross-process trace | `tests/observability_smoke.py` | | API → publisher → worker | тот же smoke после upload | один `trace_id`, services API/publisher/worker | Loki + Tempo API assertion | +| Retry в одной трассе | `make test-retry-trace` | 2 PRODUCER + 2 CONSUMER, SQL/S3, attachment ready | `tests/retry_trace.py` | | Worker outage | `make test-alert-worker` | Alerting 61.8 s, Normal 15.5 s после запуска | `tests/alert_scenarios.py` | -| PostgreSQL outage | `make test-alert-database` | Alerting 72.0 s, Normal 118.2 s после запуска | `tests/alert_scenarios.py` | -| Telemetry outage | `make test-telemetry-outage` | business smoke PASS, Collector running | `tests/telemetry_outage.py` | +| PostgreSQL outage | `make test-alert-database` | Alerting/Normal + linked log/failed PostgreSQL span | `tests/alert_scenarios.py` | +| Telemetry outage | `make test-telemetry-outage` | 49.5 s, smoke PASS, bounded RSS, loss counters | `tests/telemetry_outage.py` | | Конфиги | `docker compose config --quiet`; JSON parse; Grafana logs | provisioning завершён без error | `infra/` и `compose.yaml` | -Измерения выполнены 2026-11-17 на локальном Docker Desktop с Compose CPU/RAM -лимитами из `compose.yaml`. Точный hardware host не фиксировался; поэтому результаты -используются как функциональное доказательство обнаружения, а не benchmark. +Повторная проверка выполнена 2026-11-20: host Apple M4 Pro, 24 GiB RAM; +Docker Desktop VM — 12 CPU и 9.70 GiB RAM. Каждый Compose-сервис дополнительно +ограничен `cpus`/`mem_limit` из `compose.yaml`. Load evidence создал +25 638 синтетических сообщений за 120 с с concurrency 8. ## Разбор контролируемых инцидентов +### Временная ошибка S3 и retry + +Worker был остановлен до upload, затем S3 выключен только на первую +попытку. Worker сохранил `job.retry_scheduled`, после восстановления S3 +то же attachment дошло до `ready`. Трасса +`e8e2aff13b7bdb632c9cec5007dcc6d4` содержит два PRODUCER и два CONSUMER +span, а также SQL/S3 CLIENT spans. Это доказывает перенос context +через retry outbox event. + ### Worker недоступен Гипотеза: API продолжит durable acceptance, RabbitMQ и PostgreSQL сохранят работу, @@ -162,17 +175,23 @@ worker saturation отсутствует, oldest age растёт — причи Гипотеза: прямые business requests к API дадут 5xx, DB spans/логи укажут connection failure, а queue-only alert не обязан срабатывать. PostgreSQL остановлен, отдельный контейнер создавал synthetic `POST /api/v1/users` каждые 250 ms. Error-rate alert -стал `Alerting` за 72.0 с. PostgreSQL запущен в `finally`, readiness восстановилась, -rule вернулся в `Normal` через 118.2 с — старые 5xx должны были выйти из 2-минутного +стал `Alerting` за 72.2 с. PostgreSQL запущен в `finally`, readiness восстановилась, +rule вернулся в `Normal` через 113.1 с — старые 5xx должны были выйти из 2-минутного окна. Потери подтверждённых данных: 0; неуспешные запросы клиент может повторить. +Связанный log и trace `34f96d6fc934f7c54075c44a7b39c176` содержат +socket connection error и `connect` CLIENT span с `db.system=postgresql` и +`STATUS_CODE_ERROR`. Это отделяет отказ БД от просто медленного HTTP handler. ### Loki и Tempo недоступны -Оба backend остановлены одновременно, затем выполнен полный публичный smoke. API, -publisher и worker завершили сценарий успешно, Collector остался running. Через -12.7 с backend запущены обратно. Во время отказа exporters повторяют отправку в -ограниченных очередях; после 30 с данные могут быть отброшены. Это ожидаемая -at-most-bounded telemetry loss: наблюдаемость не является частью business commit. +Оба backend остановлены одновременно на 49.5 с, что дольше настроенного +30-секундного retry. Полный бизнес-smoke прошёл, Collector остался running. +RSS Collector изменился с 194.6 до пиковых 198.0 MiB при container limit +256 MiB. Internal counters зафиксировали потерю 34 log records и 30 spans. +Порог `memory_limiter=192 MiB` — мягкий порог отказа/сброса данных, а не +обещание RSS ниже 192 MiB; жёсткий предел задан Compose-лимитом 256 MiB. +Это ожидаемая bounded telemetry loss: наблюдаемость не является частью +business commit. ## Ограничения и следующие шаги diff --git a/docs/lab6-implementation.md b/docs/lab6-implementation.md deleted file mode 100644 index 31668ee..0000000 --- a/docs/lab6-implementation.md +++ /dev/null @@ -1,813 +0,0 @@ -# Реализация лабораторной работы 6 по файлам - -Документ описывает изменения относительно базового коммита переноса ЛР5 -`58f3d4c`. - -## Общая схема - -Бизнес-контур ЛР5 сохранён без изменения публичного API: - -```text -Client -> HAProxy -> API x2 - |-> PostgreSQL - |-> Redis - |-> MinIO/S3 - `-> outbox -> publisher -> RabbitMQ -> worker -> S3 + PostgreSQL -``` - -Поверх него добавлен observability-контур: - -```text -API / publisher / worker - | OTLP HTTP - v -OpenTelemetry Collector - |-> metrics -> Prometheus - |-> logs -> Loki - `-> traces -> Tempo - -Prometheus + Loki + Tempo -> Grafana -``` - -Главное изменение бизнес-пайплайна — сохранение W3C trace context в outbox и его -перенос через RabbitMQ: - -```text -HTTP SERVER span - `-> attachment upload - `-> outbox.traceparent - `-> PRODUCER span publisher - `-> AMQP traceparent header - `-> CONSUMER span worker - |-> SQL spans - `-> S3 CLIENT spans -``` - -## Корневые файлы - -### `.env.example` - -**Зачем нужен файл.** Чтобы новый разработчик или преподаватель мог поднять весь -стенд из чистого clone без догадок о названиях переменных. Это одновременно список -внешней конфигурации приложения и безопасный шаблон: реальные локальные секреты -остаются в игнорируемом `.env`. - -Пример окружения приведён в соответствие с реальным `compose.yaml`. - -Добавлены и сгруппированы: - -- PostgreSQL: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `DATABASE_URL`; -- Redis: `REDIS_URL`, `SESSION_TTL_SECONDS`; -- MinIO/S3: root credentials, API credentials, bucket, endpoint и region; -- RabbitMQ: user, password и `BROKER_URL`; -- worker: concurrency, prefetch, lease, timeout, retry и настройки изображений; -- OpenTelemetry: OTLP endpoint, timeout, queue sizes, metric interval, service - version и environment; -- Grafana: локальный порт и admin credentials. - -Устаревшие переменные вида `DATABASE_URL_FILE` удалены, потому что текущий Compose -использует прямые environment variables. - -### `requirements.txt` - -**Зачем изменён файл.** Одного Collector недостаточно: приложение должно само -создавать spans, metrics и log records. Эти библиотеки добавляют OTel SDK и -инструментацию в Python-процессы, а закреплённые версии делают сборку -воспроизводимой. - -Добавлены закреплённые зависимости: - -- `opentelemetry-api==1.31.1`; -- `opentelemetry-sdk==1.31.1`; -- `opentelemetry-exporter-otlp-proto-http==1.31.1`; -- `opentelemetry-instrumentation-fastapi==0.52b1`; -- `opentelemetry-instrumentation-sqlalchemy==0.52b1`; -- `psutil==7.0.0`. - -Они обеспечивают FastAPI/SQLAlchemy spans, OTLP-экспорт трёх сигналов и process -CPU/RAM metrics. - -### `compose.yaml` - -**Зачем изменён файл.** Задание требует общего воспроизводимого стенда, где вместе -запускаются бизнес-сервисы и все три telemetry-хранилища. Этот файл связывает их -одной сетью, задаёт limits, volumes, health checks и одинаковые OTel-настройки без -ручного запуска компонентов. - -Добавлен YAML anchor `x-otel-environment`, который передаёт единые OTel-настройки -в API, publisher и worker. - -Процессы имеют разные имена сервисов: - -- API — `messenger-api`; -- publisher — `messenger-publisher`; -- worker — `messenger-worker`. - -Добавлены сервисы: - -- `otel-collector`; -- `prometheus`; -- `loki`; -- `tempo`; -- `grafana`; -- тестовый `observability-test`, вынесенный в отдельный Compose override. - -Для observability-сервисов закреплены версии образов, CPU/RAM limits, -конфигурационные файлы, persistent volumes и restart policy. Grafana опубликована -только на `127.0.0.1:3000`. - -Добавлены volumes: - -- `prometheus_data`; -- `loki_data`; -- `tempo_data`; -- `grafana_data`. - -`observability-test` не входит в рабочий `compose.yaml`. Он определён в -`compose.observability-tests.yaml`, подключается к сети основного стенда через -Compose override и используется командой `make test-observability`. - -### `compose.observability-tests.yaml` - -**Зачем нужен файл.** `observability-test` — служебный runner, а не часть рабочего -стенда. Отдельный override не засоряет основной Compose тестовым контейнером, но при -совместном запуске подключает runner к той же сети, где доступны Grafana и другие -сервисы. - -Содержит только тестовый runner `observability-test`. Такое разделение не добавляет -служебный контейнер в рабочую конфигурацию и при этом позволяет runner обращаться к -`grafana:3000` во внутренней сети основного Compose-проекта. - -### `Makefile` - -**Зачем изменён файл.** Чтобы все проверки можно было воспроизвести короткими -стабильными командами, не копируя длинные Docker-вызовы из отчёта. Это уменьшает -вероятность, что на защите будет запущен другой сценарий или забыта часть параметров. - -Добавлены команды: - -- `make test-observability`; -- `make test-alert-worker`; -- `make test-alert-database`; -- `make test-telemetry-outage`. - -Они проверяют observability stack, переходы alerts в firing/resolved и работу -бизнес-API при недоступных telemetry backends. - -## Пакет `app/observability` - -### `app/observability/__init__.py` - -**Зачем нужен файл.** Это фасад observability-пакета. Он оставляет приложению только -две необходимые точки входа и не позволяет импортам по всему проекту зависеть от -внутренней структуры OTel-конфигурации. - -Публичный интерфейс пакета. Из него приложение импортирует: - -- `initialize_observability`; -- `get_metrics`. - -Остальному приложению не требуется знать внутреннее устройство OTel SDK. - -### `app/observability/config.py` - -**Зачем нужен файл.** Telemetry должна конфигурироваться окружением так же, как БД -или брокер. Централизованный parser не допускает, чтобы API, publisher и worker -по-разному трактовали timeout или размер очереди, и останавливает процесс при явно -опасной конфигурации. - -Добавлен dataclass `ObservabilitySettings`, который читает: - -- состояние OTel SDK; -- OTLP endpoint; -- service name/version; -- environment; -- export timeout; -- размеры trace/log queues; -- интервал отправки метрик. - -Положительные числовые значения валидируются. Нулевые и отрицательные размеры -очередей или timeout отклоняются с понятной ошибкой конфигурации. - -### `app/observability/runtime.py` - -**Зачем нужен файл.** Каждый Python-процесс должен один раз создать providers и -экспортёры с правильным `service.name`, а при shutdown ограниченно сбросить буферы. -Без этого instrumentation либо ничего не экспортирует, либо создаёт несколько -конфликтующих глобальных providers. - -Центральная инициализация OpenTelemetry. - -Создаётся OTel Resource со следующими attributes: - -- `service.name`; -- `service.version`; -- `service.instance.id`; -- `deployment.environment.name`. - -Настроены: - -1. `TracerProvider`; -2. `MeterProvider`; -3. `LoggerProvider`. - -Сигналы отправляются через OTLP HTTP: - -- `/v1/traces`; -- `/v1/metrics`; -- `/v1/logs`. - -Spans и logs используют batch processors с ограниченными очередями. Для -histograms заданы явные bucket boundaries. `ObservabilityRuntime.shutdown()` -корректно завершает providers при остановке процесса. - -### `app/observability/metrics.py` - -**Зачем нужен файл.** Автоинструментация показывает не все признаки проблемы. Для -диагностики worker и очереди нужны бизнес-метрики: backlog, time-to-ready, outcome и -saturation. Единый модуль также контролирует labels и не даёт случайно добавить -высококардинальные UUID. - -Созданы прикладные метрики: - -- `http.server.request.count`; -- `http.server.request.duration`; -- `messenger.jobs.processed`; -- `messenger.job.processing.duration`; -- `messenger.attachment.time_to_ready`; -- `messenger.queue.depth`; -- `messenger.queue.oldest.age`; -- `messenger.worker.busy`; -- `messenger.worker.capacity`; -- `messenger.db.pool.used`; -- `messenger.db.pool.waiting`; -- `process.memory.rss`; -- `process.cpu.time`. - -После экспорта в Prometheus они доступны, например, как -`http_server_request_count_total`, `http_server_request_duration_seconds_bucket`, -`messenger_queue_depth` и `process_memory_rss_bytes`. - -Для observable gauges реализован потокобезопасный `GaugeState`. В metric labels -не используются user/chat/attachment/request IDs, filename или raw URL. - -### `app/observability/logging.py` - -**Зачем нужен файл.** Обычная текстовая строка плохо фильтруется и связывается с -trace. Structured logging даёт стабильное поле `event`, а централизованная -фильтрация защищает от случайной отправки пароля, токена, тела сообщения или -изображения в Loki. - -Реализован JSON formatter для stdout со следующими полями: - -- timestamp; -- severity; -- logger; -- message; -- event; -- безопасные дополнительные attributes. - -Тот же formatter назначен OTLP logging handler, поэтому Loki получает полезные поля -не только как раскрываемые structured metadata, но и как JSON body строки. При -активном span formatter добавляет `trace_id` и `span_id` прямо в JSON. Функция -`safe_extra()` исключает пароль, Authorization, token, session token, secrets, -message body, image bytes и signed URL. - -### `app/observability/propagation.py` - -**Зачем нужен файл.** Текущий span хранится только в памяти одного процесса. После -записи задания в БД и отправки в RabbitMQ worker не может сам узнать, какой HTTP -запрос породил job. Этот модуль сериализует и восстанавливает стандартный W3C -context на асинхронных границах. - -Реализованы `inject_trace_context()` и `extract_trace_context()`. - -Разрешены только W3C-заголовки: - -- `traceparent`; -- `tracestate`. - -Остальные значения из AMQP headers игнорируются. - -## API и HTTP-метрики - -### `app/main.py` - -**Зачем изменён файл.** API является входом большинства traces, поэтому providers и -FastAPI/SQLAlchemy instrumentation должны включаться при создании приложения, а не -после первых запросов. Здесь же находится lifecycle, подходящий для корректного -shutdown экспортёров. - -Название и версия приложения изменены с LR5/`1.5.0` на LR6/`1.6.0`. - -Observability инициализируется до запуска приложения. Добавлены: - -- `FastAPIInstrumentor`; -- `SQLAlchemyInstrumentor`; -- structured startup/shutdown logs; -- shutdown telemetry providers. - -FastAPI instrumentation создаёт реальные SERVER spans. `/health/live` и -`/health/ready` исключены из автоматических traces, чтобы уменьшить шум. - -### `app/api/middleware.py` - -**Зачем изменён файл.** Автоматический HTTP span не заменяет заданные контрактом -метрики и `X-Request-Id`. Middleware видит каждый итоговый ответ, поэтому именно -здесь надёжно считаются requests, status classes и duration, а HTTP-ошибка -связывается с логом и trace. - -Сохранена логика `X-Request-Id`, `X-Instance-Id` и обработки исключений. - -Дополнительно middleware: - -- измеряет duration через `time.perf_counter()`; -- получает итоговый status code; -- использует route template вместо URL с UUID; -- увеличивает HTTP counter; -- записывает duration histogram; -- добавляет `request.id` и `http.route` в текущий span; -- пишет события `http.request.completed` и `http.request.failed`. - -Metric labels: method, route template и status class. - -Успешные `/health/live` и `/health/ready` не записываются в прикладные HTTP -counter/histogram и completion logs: частые Docker health checks иначе искажали бы -RPS и заполняли Loki. Ошибка health handler по-прежнему попадает в error log. - -### `app/db/postgres.py` - -**Зачем изменён файл.** Высокая HTTP latency может быть вызвана не медленным handler, -а исчерпанным connection pool. Метрики used/waiting позволяют отличить этот случай -от нагрузки на worker, RabbitMQ или S3. - -На SQLAlchemy engine добавлены listeners `checkout` и `checkin`. Они обновляют: - -- `messenger.db.pool.used`; -- `messenger.db.pool.waiting`. - -`used` берётся через `pool.checkedout()`, `waiting` отражает количество запросов, -ожидающих connection. - -## Сохранение trace context в outbox - -### `alembic/versions/20261117_0005_outbox_trace_context.py` - -**Зачем нужны колонки.** Между HTTP upload и обработкой worker может пройти время, -API может перезапуститься, а publisher может забрать outbox event другим процессом. -In-memory context к этому моменту уже не существует. Поэтому `traceparent` хранится -рядом с durable outbox event и переживает commit, задержку и перезапуск. Publisher -читает его и продолжает исходную трассу, а затем передаёт новый context worker через -AMQP headers. - -`tracestate` — необязательная часть стандарта W3C Trace Context. Она переносит -vendor-specific состояние трассировки и sampling; хранить только `traceparent` -технически можно, но тогда W3C context переносится не полностью. - -Колонки nullable по двум причинам: миграция должна применяться к уже существующим -outbox rows без выдуманного context, а ручные replay/старые события могут законно -начинать новую трассу. Это не бизнес-данные и не обязательное условие публикации. - -В `outbox_events` добавлены nullable-колонки: - -- `traceparent VARCHAR(55)`; -- `tracestate VARCHAR(512)`. - -Nullable сохраняет совместимость со старыми событиями. `downgrade()` удаляет обе -колонки. - -### `app/models/job.py` - -**Зачем изменён файл.** Миграция меняет физическую таблицу, а ORM должна уметь -записывать и читать новые колонки. Без синхронизации модели context остался бы в БД -недоступным для publisher. - -ORM-модель `OutboxEventRow` дополнена полями `traceparent` и `tracestate`. - -### `app/domain/models.py` - -**Зачем изменён файл.** Repository не должен отдавать наружу SQLAlchemy row. -Доменные поля позволяют передать context из слоя хранения в publisher, не связывая -job-код с ORM. - -Те же поля добавлены в доменный `OutboxEvent` с default `None`. - -### `app/services/attachments.py` - -**Зачем изменён файл.** Именно upload является моментом durable acceptance и -началом асинхронной цепочки. Здесь ещё активен HTTP span, поэтому context нужно -снять до commit и сохранить вместе с outbox event; здесь же логируется техническая -точка корреляции `attachment.accepted`. - -При upload сервис: - -1. сохраняет staging object в S3; -2. извлекает текущий W3C context; -3. передаёт context в repository; -4. атомарно создаёт attachment, job и outbox event; -5. пишет structured event `attachment.accepted`. - -Лог содержит только attachment ID, job ID и pipeline version. Изображение и -credentials не экспортируются. При ошибке транзакции staging object удаляется. - -### `app/repositories/attachments.py` - -**Зачем изменён файл.** Trace context должен фиксироваться атомарно с job и outbox. -Если записывать его отдельным запросом после commit, падение API между операциями -создаст корректную business job, которую уже невозможно связать с HTTP trace. - -`create_queued()` принимает `traceparent/tracestate` и сохраняет их в outbox в той -же транзакции, где создаются attachment и job. Поэтому причинная связь сохраняется -даже при падении API сразу после commit. - -### `app/repositories/jobs.py` - -**Зачем изменён файл.** Здесь создаются повторные outbox events и доступно durable -состояние jobs. Поэтому repository отвечает за сохранение context при retry и за -расчёт backlog по источнику истины, а не по приблизительному состоянию одного -consumer. - -При retry в новый outbox event сохраняется текущий trace context. Добавлен -`queue_stats()`, который считает в PostgreSQL: - -- количество jobs в `queued` или `processing`; -- возраст старейшей незавершённой job. - -Таким образом queue depth отражает durable business backlog. `claim()` теперь -возвращает trace context вместе с payload. Для ручного replay context равен `None`, -потому что replay является отдельным операторским действием. - -## Publisher и RabbitMQ - -### `app/jobs/broker.py` - -**Зачем изменён файл.** PostgreSQL context доводит трассу только до publisher. Чтобы -причинная связь пересекла RabbitMQ, W3C context нужно поместить в AMQP headers -сообщения, не меняя его business payload и schema version. - -Функция создания AMQP message теперь принимает headers, куда publisher помещает -`traceparent` и `tracestate`. Durability сообщения не менялась. - -### `app/jobs/runtime.py` - -**Зачем изменён файл.** Publisher и worker запускаются не через FastAPI lifecycle, -поэтому им нужна отдельная общая точка инициализации telemetry и SQLAlchemy spans. -Иначе фоновые процессы отсутствовали бы в Tempo и Loki. - -Обычный logging заменён общей observability-инициализацией. Метод -`configure_logging(service_name)` возвращает `ObservabilityRuntime`. SQLAlchemy -instrumentation включена также для publisher и worker. - -### `app/jobs/publisher.py` - -**Зачем изменён файл.** Publisher — отдельный этап между durable outbox и брокером. -PRODUCER span показывает задержку/ошибку публикации и создаёт context, который -worker продолжит. Здесь же удобно регулярно измерять durable queue backlog. - -Publisher: - -1. читает context из outbox; -2. восстанавливает parent context; -3. создаёт span `attachments publish` с `SpanKind.PRODUCER`; -4. записывает messaging attributes; -5. внедряет новый context в AMQP headers. - -Также publisher обновляет queue depth/oldest age и пишет structured events -`outbox.published` и `outbox.publish_failed`. При завершении процесса telemetry -providers закрываются. - -## Worker - -### `app/jobs/worker.py` - -**Зачем изменён файл.** Требуется видеть не только факт получения сообщения, но и -результат каждой попытки, длительность обработки, retry и загрузку worker. CONSUMER -span связывает эти данные с исходным upload и вложенными SQL/S3 операциями. - -Worker извлекает context из AMQP headers и создаёт span `attachments process` с -`SpanKind.CONSUMER`. - -Обработка вынесена во внутренний `_handle_message()`, чтобы внешний `handle()` мог: - -- создать span; -- измерить duration; -- сравнить состояние job до и после; -- определить outcome; -- обновить метрики. - -Outcomes: `ready`, `retry`, `failed`. - -Добавлены processed-attempt counter, processing duration, time-to-ready, worker -busy и worker capacity. `_busy_slot()` оборачивает semaphore и гарантированно -уменьшает busy gauge через `finally`. - -Добавлены события: - -- `job.completed`; -- `job.retry_scheduled`; -- `job.failed`; -- `job.processing_failed`; -- `staging.cleanup_deferred`. - -## S3 tracing - -### `app/storage/s3.py` - -**Зачем изменён файл.** Без отдельных S3 spans медленная загрузка объекта выглядит -как безымянная пауза внутри worker/API span. CLIENT spans позволяют отличить S3 -latency/error от CPU-обработки изображения или ожидания PostgreSQL. - -Добавлены CLIENT spans: - -- `s3 bucket exists`; -- `s3 put object`; -- `s3 get object`; -- `s3 stat object`; -- `s3 remove object`. - -В attributes записываются тип системы и bucket. Object key намеренно не -экспортируется, чтобы не создавать высокую кардинальность и не раскрывать filename -или внутреннюю структуру объектов. - -## OpenTelemetry Collector и хранилища - -### `infra/otel/collector.yaml` - -**Зачем нужен файл.** Collector отделяет приложение от конкретных backends: SDK -отправляет один стандартный OTLP-поток, а Collector маршрутизирует три сигнала. -Memory limiter, batch и bounded queues нужны, чтобы отказ Loki/Tempo не превратился -в бесконечное потребление RAM или блокировку бизнес-процессов. - -Настроен OTLP receiver: gRPC на `4317`, HTTP на `4318`. - -Processors: - -- `memory_limiter`: limit 192 MiB, spike limit 48 MiB; -- `batch`: до 1024 элементов. - -Exporters: - -- metrics — Prometheus exporter `:8889`; -- logs — Loki native OTLP HTTP; -- traces — Tempo OTLP gRPC. - -Для Loki и Tempo включены bounded queues по 500 элементов, два consumer и retry -не дольше 30 секунд. Collector self-metrics доступны на `8888`, health — на -`13133`. - -### `infra/prometheus/prometheus.yml` - -**Зачем нужен файл.** Collector экспортирует текущее Prometheus-представление, но не -является долговременной БД метрик. Prometheus регулярно scrape-ит серии, хранит -историю и выполняет PromQL для dashboard и alerts. - -Prometheus собирает прикладные и внутренние метрики Collector. В Compose хранение -ограничено семью днями и одним гигабайтом. - -### `infra/loki/loki.yaml` - -**Зачем нужен файл.** Метрика показывает, что проблема существует, но не объясняет -конкретное событие и ошибку. Loki хранит structured logs и позволяет по `trace_id`, -`event` и service name перейти от графика к деталям инцидента. - -Настроен single-node Loki с filesystem storage, TSDB schema v13, native OTLP logs, -structured metadata и retention семь дней. Resource labels включают service name, -instance ID и environment; `trace_id/span_id` доступны как structured metadata. - -### `infra/tempo/tempo.yaml` - -**Зачем нужен файл.** Trace показывает причинную и временную цепочку одного запроса -через несколько процессов. Tempo хранит spans, чтобы можно было увидеть, где именно -потрачено время: API, publisher, RabbitMQ/worker, SQL или S3. - -Настроен single-node Tempo с OTLP gRPC/HTTP receivers, локальным filesystem storage, -retention 24 часа и compaction. В одной трассе сохраняются API, publisher и worker. - -## Grafana - -### `infra/grafana/provisioning/datasources/datasources.yaml` - -**Зачем нужен файл.** Grafana сама не хранит telemetry и должна знать адрес и тип -каждого backend. Provisioning делает эту связь воспроизводимой и добавляет переходы -между логом, trace и метрикой без ручной настройки UI. - -Автоматически создаются datasources: - -- Prometheus — UID `prometheus`; -- Loki — UID `loki`; -- Tempo — UID `tempo`. - -Настроены связи Loki log -> Tempo trace, Tempo trace -> Loki logs и Tempo trace -> -Prometheus metrics. - -### `infra/grafana/provisioning/dashboards/dashboards.yaml` - -**Зачем нужен файл.** Наличие JSON в Git само по себе не загружает dashboard. -Provider сообщает Grafana, откуда читать dashboard и автоматически обновлять его при -изменении файла. - -Grafana автоматически загружает dashboard из `/var/lib/grafana/dashboards`; ручной -импорт через UI не нужен. - -### `infra/grafana/dashboards/messenger-observability.json` - -**Зачем нужен файл.** Это готовое представление основных симптомов системы для -оператора: нагрузка, ошибки, latency, backlog и saturation. Хранение JSON в Git -доказывает, что dashboard импортируем и не существует только в локальной базе -Grafana. - -Dashboard UID `messenger-observability` содержит 12 панелей: - -1. API RPS; -2. API 5xx ratio; -3. HTTP p50/p95/p99; -4. jobs по outcome; -5. worker p50/p95/p99; -6. end-to-end time-to-ready p50/p95/p99; -7. queue depth и oldest job age; -8. PostgreSQL pool used/waiting; -9. worker saturation; -10. process CPU; -11. process RSS; -12. correlated application logs. - -Percentiles вычисляются через `histogram_quantile()` по объединённым buckets всех -реплик, а не усреднением готовых p99. - -Log panel разбирает JSON, скрывает старые `/health/*` строки и сразу выводит severity, -service, event, HTTP method/route/status/duration, `trace_id` и message. Формат -`trace_id=<32 hex>` совпадает с Loki derived field, поэтому раскрытая строка содержит -ссылку `TraceID` для перехода в Tempo. Для основной диагностики поля строки больше -не требуется просматривать по одному. - -### `infra/grafana/provisioning/alerting/rules.yaml` - -**Зачем нужен файл.** Dashboard требует, чтобы человек постоянно смотрел на экран. -Alerts формализуют условия инцидента и автоматически переводят их в -Pending/Alerting/Normal. Provisioning делает правила одинаковыми после чистого -старта. - -Созданы два Grafana-managed alert rule. - -`ApiHighServerErrorRate`: - -- 5xx / все business requests; -- health endpoints исключены; -- окно две минуты; -- порог 5%; -- `for: 1m`. - -`QueueOldestJobGrowing`: - -- oldest age больше 20 секунд; -- queue depth больше нуля; -- `for: 15s`. - -Оба правила связаны с dashboard panels и локальными runbooks. - -### `infra/grafana/runbooks/api-high-error-rate.md` - -**Зачем нужен файл.** Alert сообщает симптом, но оператору нужен повторяемый путь к -причине. Runbook задаёт, какие метрики, traces, DB spans и logs смотреть и как -убедиться, что восстановление действительно произошло. - -Содержит порядок диагностики повышенного 5xx rate: PostgreSQL, API traces, DB spans, -Loki errors, readiness и проверка восстановления. - -### `infra/grafana/runbooks/queue-oldest-job.md` - -**Зачем нужен файл.** Рост backlog может быть вызван остановленным worker, отсутствием -consumer, ошибкой S3 или медленной обработкой. Runbook задаёт порядок проверок и не -даёт ограничиться одним графиком queue depth. - -Содержит порядок диагностики backlog: worker, RabbitMQ consumer, queue metrics, -worker logs, consumer traces и уменьшение backlog после восстановления. - -### `infra/grafana/provisioning/plugins/.gitkeep` - -**Зачем нужен файл.** Git не хранит пустые каталоги. `.gitkeep` гарантирует наличие -ожидаемой директории provisioning/plugins после clone и убирает лишнюю ошибку -сканирования при старте Grafana. - -Сохраняет пустой каталог plugin provisioning, чтобы Grafana не сообщала об -отсутствии ожидаемого каталога. - -## Тесты - -### `tests/observability_smoke.py` - -**Зачем нужен файл.** Healthy-контейнеры ещё не доказывают, что данные прошли всю -цепочку. Тест проверяет именно наблюдаемый результат: метрику в Prometheus, log в -Loki, `trace_id` и полный cross-process trace в Tempo. - -Через Grafana API проверяет: - -- Grafana health; -- dashboard UID и минимум 12 панелей; -- два alert rules; -- API metrics в Prometheus; -- `attachment.accepted` log в Loki; -- извлечение `trace_id` через LogQL; -- trace из Tempo; -- наличие API, publisher и worker в одном trace. - -Проверяется реальный сквозной сигнал, а не только доступность контейнеров. - -### `tests/alert_scenarios.py` - -**Зачем нужен файл.** Наличие YAML rule не доказывает его работоспособность. Эти -сценарии создают ограниченные реальные отказы, измеряют время обнаружения и -восстановления и обязательно возвращают контейнеры в рабочее состояние. - -Worker scenario останавливает worker, создаёт attachment, ждёт -`QueueOldestJobGrowing=Alerting`, восстанавливает worker в `finally`, ждёт ready и -`Normal`. - -Database scenario останавливает PostgreSQL, запускает synthetic error load, ждёт -`ApiHighServerErrorRate=Alerting`, восстанавливает БД в `finally`, ждёт readiness и -`Normal`. - -### `tests/database_error_load.py` - -**Зачем нужен файл.** После остановки PostgreSQL нужен контролируемый поток -DB-зависимых business requests, иначе error-rate останется без данных и alert не -сработает. Отдельный генератор работает внутри Compose-сети и обходит health routing -HAProxy, которое исключило бы неготовую API-реплику. - -Создаёт ограниченную synthetic-нагрузку на `POST /api/v1/users` примерно каждые -250 мс. Используются уникальные synthetic credentials, которые не печатаются. - -### `tests/telemetry_outage.py` - -**Зачем нужен файл.** Observability не должна становиться обязательной частью -business commit. Тест доказывает, что недоступные Loki/Tempo вызывают только -ограниченную потерю telemetry, а API, broker и worker продолжают работать. - -Останавливает Loki и Tempo, выполняет бизнес-smoke, проверяет readiness и работу -Collector, затем запускает хранилища обратно в `finally`. - -### `tests/README.md` - -**Зачем изменён файл.** Отказные проверки управляют реальными контейнерами и для них -важны порядок запуска, ожидаемая длительность и гарантированное восстановление. -Документация предотвращает случайный параллельный запуск конфликтующих сценариев. - -Описывает новые команды, управляемые контейнеры, обязательное восстановление через -`finally` и требование запускать отказные тесты последовательно. - -## План, отчёт и evidence - -### `docs/plan/2026-11-17-lab6-grade4.md` - -**Зачем нужен файл.** План фиксирует выбранный стек, границы оценки 4 и критерии -готовности до реализации. По нему можно проверить, что итог не является набором -случайных инструментов и покрывает каждый пункт задания. - -Подробный план реализации на оценку 4: стек, архитектура, propagation, метрики, -buckets, SLI/SLO, alerts, этапы, отказные сценарии и критерии готовности. - -### `REPORT.md` - -**Зачем изменён файл.** Это основной документ сдачи: преподаватель должен суметь -поднять стенд, понять архитектурные решения и воспроизвести доказательства без -устного восстановления контекста разработки. - -Заполнены запуск из clone, архитектура, перенос ЛР5, назначение хранилищ, таблица -метрик, PromQL, SLI/SLO, alerts, результаты тестов, инциденты, ограничения и -следующие шаги. Перед сдачей осталось вписать автора и группу. - -### `evidence/2026-11-17-results.md` - -**Зачем нужен файл.** Конфигурация и тестовый код показывают намерение, но не -подтверждают, что сценарии реально запускались. Evidence хранит наблюдённые состояния -и времена firing/resolved без секретов и пользовательского содержимого. - -Сохранены результаты публичного и observability smoke, worker/DB incidents и -telemetry outage. Секреты, tokens и пользовательские тела не сохранялись. - -## Выполненные проверки - -Успешно выполнены: - -```text -make check -make validate PYTHON=.venv/bin/python -docker compose config --quiet -docker compose --env-file .env.example config --quiet -make test -make test-observability -make test-alert-worker -make test-alert-database -make test-telemetry-outage -git diff --check -``` - -Фактические результаты инцидентов: - -- worker outage: `Alerting` через 61,8 с, `Normal` через 15,5 с после запуска; -- PostgreSQL outage: `Alerting` через 72,0 с, `Normal` через 118,2 с; -- Loki/Tempo outage: бизнес-smoke прошёл, Collector остался running. - -Также подтверждено, что Grafana provisioning проходит без ошибок, Prometheus видит -прикладные серии, Loki принимает OTLP logs, а Tempo возвращает связанную трассу с -API, publisher, worker, SQL и S3 spans. diff --git a/docs/plan/2026-11-17-lab6-grade4.md b/docs/plan/2026-11-17-lab6-grade4.md deleted file mode 100644 index 87a445f..0000000 --- a/docs/plan/2026-11-17-lab6-grade4.md +++ /dev/null @@ -1,637 +0,0 @@ -# План реализации лабораторной 6 на оценку 4 - -## Цель и границы - -Сохранить перенесённую реализацию лабораторной 5 и добавить воспроизводимую -наблюдаемость API, publisher и worker через метрики, структурированные логи и -распределённые трассы. По сохранённым сигналам оператор должен уметь: - -- найти HTTP-запрос, его лог и trace по `X-Request-Id`; -- пройти от upload через outbox и RabbitMQ до worker, S3 и фиксации `ready`; -- увидеть RPS, ошибки, latency, состояние очереди, DB pool и загрузку worker; -- обнаружить остановку worker и отказ PostgreSQL с помощью provisioned alerts; -- доказать, что недоступность telemetry backend не ломает бизнес-сценарий и не - приводит к неограниченному росту памяти. - -Целевая оценка — 4: выполняется весь уровень 3 и весь уровень 4. Треки оценки 5, -multi-window burn-rate alerts, сравнение sampling-конфигураций, Kubernetes и внешняя -доставка уведомлений в работу не входят. - -Бизнес-API и обязательные статусы/схемы ответов не меняются. Добавление служебного -`traceparent` относится только к внутреннему outbox и AMQP headers. - -## Выбранный стек - -- upstream `otel/opentelemetry-collector-contrib` как отдельный Collector; -- Prometheus как долговременное хранилище метрик; -- Loki 3+ с native OTLP ingestion как хранилище логов; -- Tempo как хранилище трасс; -- Grafana OSS для Explore, dashboard и unified alerting; -- OpenTelemetry Python SDK и OTLP/HTTP exporters в API, publisher и worker; -- FastAPI/ASGI и SQLAlchemy auto-instrumentation плюс ручные spans и metrics для - RabbitMQ, S3, очереди, DB pool и worker. - -Перед реализацией выбрать совместимые версии и закрепить каждый container image -точным tag или digest. `latest` не использовать. Версии Python-пакетов также -зафиксировать в `requirements.txt`. - -Grafana Alloy, Promtail, Jaeger и отдельный Elasticsearch не добавлять: они дублируют -выбранные роли и усложняют учебный стенд. - -## Целевая архитектура - -```text -client - -> HAProxy - -> API x2 - -> PostgreSQL / Redis / MinIO - -> outbox(traceparent, tracestate) - -> publisher producer span - -> RabbitMQ headers(traceparent, tracestate) - -> worker consumer span - -> S3 spans - -> PostgreSQL spans - -API / publisher / worker - -> OTLP/HTTP metrics, logs, traces - -> OpenTelemetry Collector - -> prometheus exporter endpoint <- Prometheus - -> OTLP/HTTP -> Loki - -> OTLP -> Tempo - -Grafana -> Prometheus + Loki + Tempo -``` - -Collector не является хранилищем. Prometheus, Loki и Tempo получают persistent -volumes. Grafana provisioning и dashboard/alert definitions лежат в Git. - -Наружу публикуется только HAProxy и локальный порт Grafana. Административные порты -backend и OTLP остаются внутри Compose network; диагностические запросы выполняются -через Grafana datasource proxy или `docker compose exec`. - -## Инварианты наблюдаемости - -1. Недоступность Collector, Prometheus, Loki, Tempo или Grafana не меняет результат - бизнес-операции и не влияет на `/health/ready` API. -2. Export выполняется фоново с коротким timeout, ограниченными очередями и - ограниченным retry; HTTP handler и consumer ack не ждут telemetry backend. -3. В metrics labels не попадают `user_id`, `chat_id`, `message_id`, `attachment_id`, - `request_id`, filename, raw URL или текст сообщения. -4. HTTP route записывается как route template, например - `/api/v1/chats/{chat_id}/messages`, а не фактический URL с UUID. -5. В telemetry не попадают `Authorization`, session token, password, message body, - image bytes, S3 credentials, signed URL и private object contents. -6. Технические ID допустимы только как структурированные log/span attributes, если - они нужны для расследования; они не становятся Loki index labels. -7. Каждый процесс имеет корректные resource attributes: - `service.name`, `service.version`, `service.instance.id` и - `deployment.environment.name=lab`. -8. Активный log record содержит `trace_id` и `span_id`; HTTP log дополнительно - содержит `request_id`. -9. `traceparent` переживает задержку outbox и переносится только через доверенные - поля PostgreSQL и AMQP headers. -10. Metric names, units и фактическое преобразование имён в Prometheus фиксируются в - `REPORT.md`; dashboard использует только реально существующие series. - -## Схема обязательных сигналов - -Логические имена ниже могут получить Prometheus-compatible suffixes `_total`, -`_seconds_bucket` и нормализацию точек в `_`. После запуска фактические имена нужно -проверить через Prometheus API и зафиксировать отображение в отчёте. - -| Логический сигнал | Тип и единица | Разрешённые атрибуты | -| --- | --- | --- | -| `http.server.request.duration` | histogram, seconds | method, route, status class, service | -| `http.server.request.count` | counter | method, route, status class, service | -| `messenger.jobs.processed` | counter | job type, outcome | -| `messenger.job.processing.duration` | histogram, seconds | job type, outcome | -| `messenger.attachment.time_to_ready` | histogram, seconds | pipeline version, outcome | -| `messenger.queue.depth` | gauge, jobs | queue name | -| `messenger.queue.oldest.age` | gauge, seconds | queue name | -| `messenger.db.pool.used` | gauge, connections | pool name, service | -| `messenger.db.pool.waiting` | gauge, requests | pool name, service | -| `messenger.worker.busy` | gauge, workers | job type | -| `messenger.worker.capacity` | gauge, workers | job type | -| process CPU time/utilization | counter/gauge | service, instance | -| process RSS | gauge, bytes | service, instance | - -Задать histogram buckets под локальный профиль, а не полагаться на случайные -defaults: - -- HTTP: `5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s`; -- processing: `50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s, 30s, 60s`; -- time-to-ready: `100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s, 30s, 60s, 120s`. - -Percentiles p50/p95/p99 считать `histogram_quantile()` по сумме buckets всех -реплик. Не усреднять quantiles отдельных instance. - -## SLI, SLO и alerts - -### API SLI/SLO - -SLI availability: - -```text -good = business HTTP requests со status < 500 -total = все business HTTP requests -исключения = /health/live, /health/ready и telemetry endpoints -SLI = good / total -``` - -Зафиксировать учебный SLO: не менее 99% good requests в rolling window 30 минут. -Клиентские 4xx входят в total, но не считаются server errors; отдельный error-rate -alert использует только 5xx, чтобы неверный пароль не имитировал отказ БД. - -### Pipeline SLI - -SLI обработки: доля attachment, достигших `ready` не позднее 60 секунд после durable -acceptance. Учебная цель — не менее 95% за rolling 30 минут при свободном worker. -Это не универсальный production SLA, а проверяемый локальный бюджет. - -### Provisioned alerts уровня 4 - -1. `ApiHighServerErrorRate`: - - ratio: 5xx business requests / all business requests; - - окно 2 минуты; - - порог 5%; - - `for: 1m`; - - annotation с причиной, dashboard link и локальным runbook. -2. `QueueOldestJobGrowing`: - - oldest job age больше 20 секунд и queue depth больше 0; - - `for: 15s` для быстрой учебной демонстрации; - - annotation с проверкой worker/consumer и runbook. - -Для каждого alert показать переход `Normal -> Pending -> Alerting -> Normal` либо -эквивалентные состояния `firing/resolved`. Пороговые значения объяснить как -демонстрационные, а не production defaults. - -## Этап 0. Зафиксировать baseline lab5 - -До изменения telemetry: - -```sh -make check -docker compose --env-file .env config --quiet -docker compose --env-file .env up -d --build --wait -make test BASE_URL=http://localhost:8080 -``` - -Сохранить краткий baseline в `evidence/`: версия commit, список контейнеров, результат -smoke и время upload-to-ready. Не копировать старые результаты lab5 как новые. - -Критерий готовности: бизнес-API проходит smoke до начала инструментирования. - -## Этап 1. Добавить telemetry foundation в приложение - -Изменить `requirements.txt` и добавить совместимые версии: - -- `opentelemetry-api`; -- `opentelemetry-sdk`; -- OTLP protobuf HTTP exporter; -- FastAPI/ASGI instrumentation; -- SQLAlchemy instrumentation; -- logging instrumentation/export components; -- system/process metrics instrumentation и необходимую runtime-зависимость. - -Создать пакет `app/observability/`: - -- `config.py` — parsing/validation OTEL settings; -- `runtime.py` — создание Resource, providers, exporters и shutdown/flush; -- `logging.py` — JSON console formatter, OTLP handler и безопасные structured events; -- `metrics.py` — instruments и thread-safe caches для observable gauges; -- `tracing.py` — tracer helpers и безопасные span attributes; -- `propagation.py` — inject/extract W3C context для outbox/AMQP. - -Инициализировать telemetry до создания FastAPI app/engine и до запуска publisher или -worker. На shutdown вызвать bounded `force_flush`/`shutdown`, но не зависать дольше -заданного timeout. - -Настройки: - -```dotenv -OTEL_SDK_DISABLED=false -OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 -OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf -OTEL_EXPORTER_OTLP_TIMEOUT=2 -OTEL_SERVICE_VERSION=1.6.0 -OTEL_DEPLOYMENT_ENVIRONMENT=lab -OTEL_TRACES_SAMPLER=always_on -OTEL_BSP_MAX_QUEUE_SIZE=2048 -OTEL_BLRP_MAX_QUEUE_SIZE=2048 -OTEL_METRIC_EXPORT_INTERVAL=5000 -``` - -API, publisher и worker переопределяют `OTEL_SERVICE_NAME`; instance ID строится из -стабильного для жизни процесса hostname/PID и не содержит credentials. - -Добавить unit tests: - -- resource attributes для каждого процесса; -- disabled mode не ломает запуск; -- bounded exporter config; -- sanitizer не пропускает запрещённые headers/body/credentials. - -Критерий готовности: приложение работает при включённом и выключенном SDK, а -недоступный Collector не увеличивает latency каждого запроса на exporter timeout. - -## Этап 2. Добавить Collector и backend в Compose - -Создать: - -```text -infra/otel/collector.yaml -infra/prometheus/prometheus.yml -infra/prometheus/rules.yml -infra/loki/loki.yaml -infra/tempo/tempo.yaml -infra/grafana/provisioning/datasources/datasources.yaml -infra/grafana/provisioning/dashboards/dashboards.yaml -infra/grafana/provisioning/alerting/rules.yaml -infra/grafana/dashboards/messenger-observability.json -infra/grafana/runbooks/api-high-error-rate.md -infra/grafana/runbooks/queue-oldest-job.md -``` - -Добавить в `compose.yaml` и `compose.tests.yaml` services: - -- `otel-collector`; -- `prometheus`; -- `loki`; -- `tempo`; -- `grafana`. - -Collector pipelines: - -```text -metrics: otlp -> memory_limiter -> resource/filter -> batch -> prometheus -logs: otlp -> memory_limiter -> resource/filter -> batch -> otlphttp/loki -traces: otlp -> memory_limiter -> resource/filter -> batch -> otlp/tempo -``` - -Обязательная защита Collector: - -- `memory_limiter` с лимитом ниже container `mem_limit`; -- `batch` с ограниченным batch size/timeout; -- exporter `sending_queue` с фиксированным `queue_size` и числом consumers; -- retry с конечным `max_elapsed_time`; -- health extension и собственные Collector metrics; -- `debug` exporter допускается только временно при разработке и не остаётся - основным путём хранения. - -Prometheus scrape-ит Collector prometheus exporter и Collector self-metrics. Loki -включает structured metadata и принимает Collector на `/otlp`. Tempo OTLP receiver -явно слушает `0.0.0.0` внутри контейнера. - -Volumes: - -- `prometheus_data`; -- `loki_data`; -- `tempo_data`; -- `grafana_data`. - -Для учебного стенда задать ограниченные retention/size policy и описать их в отчёте. -Перезапуск контейнеров без `down -v` должен сохранять историю. - -Критерии готовности: - -```sh -docker compose --env-file .env config --quiet -docker compose --env-file .env up -d --build --wait -docker compose --env-file .env ps -``` - -Все пять telemetry services healthy; Grafana автоматически видит три datasources, -dashboard появляется без ручного импорта. - -## Этап 3. Инструментировать HTTP, DB, process metrics и логи API - -В `app/main.py`: - -- обновить title/version до lab6; -- инициализировать telemetry lifecycle; -- подключить FastAPI instrumentation с исключением health routes из SLI; -- подключить SQLAlchemy instrumentation к `engine.sync_engine`; -- включить process CPU/RSS metrics. - -В `app/api/middleware.py`: - -- сохранить текущие `X-Request-Id` и `X-Instance-Id`; -- писать один structured completion log на запрос; -- записывать `http.request.method`, route template, status class и duration; -- не использовать raw URL/path как metric attribute; -- записывать `request_id` в span/log, но не в metric labels; -- отметить span error только для неожиданных server failures, а не для всех 4xx. - -Структурные API events минимум: - -- `api.startup` / `api.shutdown`; -- `http.request.completed`; -- `http.request.failed`; -- `attachment.accepted`; -- `dependency.unavailable`. - -DB pool metrics: - -- обернуть session factory наблюдаемым context manager; -- перед ожиданием connection увеличивать `waiting`, после checkout уменьшать; -- `used` брать из фактического checked-out состояния pool; -- гарантировать decrement в `finally`, включая cancellation/error; -- не путать query duration и pool wait duration. - -Добавить tests на: - -- route-template cardinality при разных UUID; -- status class и duration units; -- trace/span IDs в log внутри активного request span; -- отсутствие Authorization/body в exported log/span data; -- корректный decrement DB pool waiting после исключения. - -Критерий готовности: после smoke в Prometheus есть HTTP histogram по двум API -instances, в Loki находятся request logs, в Tempo — реальные server и DB spans. - -## Этап 4. Перенести trace context через outbox и RabbitMQ - -Добавить Alembic migration после `20261116_0004`: - -- `outbox_events.traceparent` nullable string с ограниченной длиной; -- `outbox_events.tracestate` nullable string с ограниченной длиной; -- при необходимости `outbox_events.baggage` не добавлять: пользовательские данные - через baggage не передаются. - -При durable acceptance upload: - -1. В активном API span создать/зафиксировать событие `attachment.accepted`. -2. W3C propagator inject-ит только `traceparent`/`tracestate` в разрешённый carrier. -3. Сохранить carrier атомарно вместе с outbox event. - -В publisher: - -1. Восстановить context из outbox columns. -2. Создать `PRODUCER` span `attachments publish` с messaging semantic attributes. -3. Inject текущий context в AMQP headers. -4. Добавить события confirm/failure без payload и credentials. -5. Не считать retry/duplicate publish новой логической attachment job. - -В worker: - -1. Извлечь W3C context из AMQP headers. -2. Создать `CONSUMER` span `attachments process`. -3. На redelivery сохранить причинную связь; если выбран link вместо parent, - документировать её и покрыть тестом. -4. Внутри consumer span создать child spans для trusted staging read, image pipeline, - S3 writes и DB complete/retry/fail. -5. Записать outcome и attempt как низкокардинальные/ограниченные attributes. - -Не помещать trace context в публичный jobs payload, если это нарушает -`contracts/jobs.schema.json`; использовать outbox columns и native AMQP headers. - -Добавить tests: - -- inject/extract сохраняет trace ID; -- malformed/отсутствующий header безопасно начинает новый trace; -- publisher span и consumer span имеют ожидаемого parent/link; -- redelivery не создаёт второй бизнес-эффект; -- headers не содержат token, body, image bytes или credentials. - -Критерий готовности: один upload trace содержит или причинно связывает server, -producer, consumer, S3 и DB spans; повторная доставка остаётся идемпотентной. - -## Этап 5. Инструментировать worker, publisher и очередь - -Worker metrics: - -- увеличить `worker.busy` после захвата semaphore и уменьшить в `finally`; -- `worker.capacity` равен конфигурации процесса; -- записывать processing duration для `success`, `retry`, `failed`, `duplicate`; -- jobs counter увеличивать один раз на завершившийся outcome, не на каждый broker - redelivery без обработки; -- time-to-ready считать от durable `attachment.created_at` до commit `ready`. - -Queue metrics считать по PostgreSQL как источнику истины логических jobs: - -- depth = количество `queued` и активных `processing`, ещё не terminal; -- oldest age = возраст самой старой не terminal job от durable acceptance; -- queue name — константа `attachments.process`. - -Периодический async poll выполняет publisher либо отдельная задача наблюдения внутри -publisher. Observable callbacks читают только thread-safe cache и не выполняют async -DB-запросы из callback exporter thread. - -Structured events минимум: - -- `outbox.claimed`, `outbox.published`, `outbox.publish_failed`; -- `job.received`, `job.claimed`, `job.completed`; -- `job.retry_scheduled`, `job.failed`, `job.duplicate_ignored`; -- `staging.cleanup_deferred`. - -Во всех событиях активного span должны присутствовать trace/span IDs. `job_id` и -`attachment_id` допустимы как structured metadata для synthetic lab data, но не как -Loki index labels или metric labels. - -Добавить tests на: - -- busy gauge возвращается к нулю после success/error/cancellation; -- capacity соответствует `WORKER_CONCURRENCY`; -- queue depth/oldest age на queued, processing, ready и failed fixtures; -- time-to-ready использует durable acceptance, а не consumer start; -- retry/duplicate semantics счётчиков. - -Критерий готовности: остановленный worker даёт рост depth/oldest age, после запуска -backlog уменьшается, jobs и duration отображаются без высококардинальных labels. - -## Этап 6. Создать Grafana dashboard и корреляцию сигналов - -Provisioned dashboard должен содержать минимум: - -1. API RPS по route/method. -2. API 5xx error ratio. -3. API duration p50/p95/p99 из aggregate histogram buckets. -4. Jobs rate по outcome. -5. Job processing p50/p95/p99. -6. End-to-end time-to-ready p50/p95/p99. -7. Queue depth и oldest job age. -8. DB pool used/waiting по service/instance. -9. Worker busy/capacity и saturation ratio. -10. Process CPU и RSS по service/instance. -11. Collector export failures/dropped/enqueue-failed signals. -12. Logs panel с переходом к trace. - -Настроить datasource correlations/derived fields: - -- Loki `trace_id` -> Tempo trace; -- Tempo service/trace -> Loki logs; -- exemplars из histogram -> Tempo, если текущая связка exporter/backend это - поддерживает; отсутствие exemplars не блокирует уровень 4. - -Dashboard variables ограничить низкокардинальными значениями: service, instance, -route, outcome. Не создавать variables по request/user/chat/attachment IDs. - -Все PromQL/LogQL запросы и единицы измерения указать в panel description либо -`REPORT.md`. JSON dashboard хранить форматированным и проверять provisioning с чистым -Grafana volume. - -Критерий готовности: после `down`/`up` без volumes dashboard и datasources появляются -автоматически; после smoke панели заполнены данными обеих API replicas и worker. - -## Этап 7. Реализовать alerts и runbooks - -Provision alerts в Git, без ручного создания через UI. В runbook каждого alert: - -- смысл numerator/denominator или gauge; -- порог, окно и `for`; -- команды безопасной проверки; -- переход от dashboard к logs и traces; -- ожидаемое восстановление; -- ограничения и возможные false positives. - -Проверить alert provisioning API Grafana после чистого запуска. Добавить read-only -скрипт/тест, который ожидает нужное состояние rule и сохраняет JSON без credentials. - -Критерий готовности: оба alerts существуют после provisioning, искусственно переходят -в firing и после восстановления — в resolved/normal. - -## Этап 8. Провести обязательные отказные сценарии - -### Инцидент A: worker остановлен - -1. Создать baseline traffic и убедиться, что очередь пуста. -2. Остановить только worker. -3. Загрузить несколько synthetic images и получить `202`. -4. Наблюдать queue depth и oldest age; дождаться alert firing. -5. Не смотреть состояние контейнеров до формулировки диагноза по telemetry. -6. Запустить worker; показать уменьшение backlog и alert resolved. -7. Проверить `ready`, original и thumbnail. - -Сохранить timestamps, Prometheus query results, alert states, trace/log IDs и время -восстановления. Не сохранять session token. - -### Инцидент B: PostgreSQL недоступен или медленный - -1. Создать одинаковую контролируемую HTTP-нагрузку. -2. Остановить PostgreSQL либо применить ограниченный воспроизводимый fault. -3. Получить рост 5xx/latency и alert firing. -4. По trace доказать, что время/error находится в DB span, а не в CPU image pipeline - или произвольно медленном HTTP middleware. -5. Восстановить PostgreSQL и показать alert resolved/readiness recovery. - -Воздействие не должно удалять volume или данные. В отчёте указать, какие запросы могли -получить неопределённый результат и почему. - -### Инцидент C: telemetry backend недоступен - -1. Остановить Tempo, оставив Collector и Prometheus доступными. -2. Создать контролируемую HTTP/upload нагрузку. -3. Показать, что business smoke/requests продолжают работать. -4. Наблюдать bounded queue, exporter failure/enqueue-failed/dropped counters и RSS - Collector/app processes. -5. Дождаться исчерпания конечного retry window либо заполнения bounded queue. -6. Запустить Tempo и проверить восстановление export новых traces. - -Не обещать отсутствие потерь: при заполненной bounded queue telemetry теряется -намеренно. Посчитать потери настолько, насколько позволяют Collector self-metrics, и -объяснить этот компромисс. - -## Этап 9. Автоматизировать проверки и доказательства - -Добавить цели Makefile: - -```text -test-observability -test-observability-correlation -test-alert-worker -test-alert-database -test-telemetry-outage -``` - -Предпочтительная структура tests: - -- `tests/test_observability.py` — unit tests names/labels/redaction/propagation; -- `tests/observability_smoke.py` — дождаться метрик, API/worker logs и trace; -- `tests/alert_worker.py` — bounded worker outage scenario; -- `tests/alert_database.py` — bounded DB outage scenario; -- `tests/telemetry_outage.py` — backend outage и business continuity. - -Сценарии изменения состояния должны управлять только явно названными Compose -services, не использовать `down -v` и восстанавливать сервисы в `finally`/cleanup. - -Raw evidence сохранять в `evidence/`: - -- JSON summary нагрузки; -- Prometheus query results; -- Grafana alert state JSON; -- обезличенные Loki query results; -- trace IDs и Tempo summaries без полного payload; -- `docker stats --no-stream` до/во время/после telemetry outage; -- точные команды и timestamps. - -Screenshots допустимы как дополнение, но не заменяют импортируемый dashboard, alert -rules и raw query results. - -Критерии готовности: - -```sh -make check -make validate PYTHON=.venv/bin/python -make test BASE_URL=http://localhost:8080 -make test-observability -git diff --check -``` - -## Этап 10. Заполнить REPORT.md и подготовить защиту - -В `REPORT.md` зафиксировать: - -- версии runtime, SDK, Collector и backend images; -- topology и роль каждого хранилища; -- bootstrap/provisioning из чистого clone; -- volumes, retention и exposed ports; -- logical signal -> фактическое metric/log/span name и unit; -- histogram buckets и PromQL p50/p95/p99; -- определения SLI/SLO и исключения health/4xx/5xx; -- trace propagation через outbox/AMQP; -- bounded queue/retry/memory settings SDK и Collector; -- команды и результаты smoke/load/fault tests; -- разбор двух бизнес-инцидентов и telemetry outage; -- ограничения single-host стенда и неизбежные telemetry losses при длительном outage. - -Сценарий защиты: - -1. Поднять стенд из чистого состояния и показать automatic provisioning. -2. Запустить smoke/нагрузку и показать dashboard. -3. Найти request log по `X-Request-Id`, перейти в trace. -4. Показать upload trace через producer/consumer к S3/DB и соответствующий worker log. -5. Остановить worker, получить firing queue alert, восстановить и получить resolved. -6. Воспроизвести DB incident и диагностировать его только по сохранённым сигналам. -7. Остановить Tempo и показать сохранение бизнес-работы и bounded telemetry behavior. - -## Рекомендуемые контрольные коммиты - -1. `Добавить базовую конфигурацию OpenTelemetry` -2. `Поднять Collector и хранилища телеметрии` -3. `Инструментировать API и структурированные логи` -4. `Перенести trace context через очередь` -5. `Добавить метрики worker и состояния очереди` -6. `Добавить Grafana dashboard и alerts` -7. `Добавить отказные проверки наблюдаемости` -8. `Заполнить отчёт и доказательства ЛР 6` - -Каждый контрольный коммит должен оставлять `make check` зелёным. После появления -Compose telemetry stack дополнительно проверять `docker compose config --quiet`. - -## Итоговый Definition of Done - -- lab5 business smoke проходит при включённой telemetry; -- API и worker экспортируют OTLP только через Collector; -- Prometheus, Loki, Tempo и Grafana работают в общем воспроизводимом Compose; -- dashboard/datasources/alerts автоматически provisioned из Git; -- доступны HTTP/job metrics, p50/p95/p99, error ratio, queue, DB pool, - worker saturation и process CPU/RAM; -- API и worker logs структурированы и коррелируют с trace/span; -- W3C context проходит API -> outbox -> publisher -> RabbitMQ -> worker; -- upload trace содержит producer/consumer и S3/DB work; -- SLI/SLO формально определены и запросы соответствуют определениям; -- два обязательных alerts показали firing и resolved; -- worker и DB incidents диагностированы по сохранённым наблюдениям; -- telemetry backend outage не ломает бизнес-путь, очереди и память ограничены; -- secrets, message bodies и image contents отсутствуют в telemetry; -- `REPORT.md` и `evidence/` содержат повторяемые команды и результаты. diff --git a/evidence/2026-11-17-results.md b/evidence/2026-11-17-results.md index 6ca11c8..5509f5e 100644 --- a/evidence/2026-11-17-results.md +++ b/evidence/2026-11-17-results.md @@ -1,6 +1,7 @@ -# Результаты проверок 2026-11-17 +# Результаты повторной проверки 2026-11-20 -Стенд: локальный Docker Compose, лимиты CPU/RAM из `compose.yaml`, synthetic data. +Стенд: Apple M4 Pro, 24 GiB RAM; Docker Desktop VM 12 CPU / 9.70 GiB; +лимиты сервисов из `compose.yaml`, только synthetic data. ```text make test @@ -9,17 +10,26 @@ PASS: lab6 public API scenario; infrastructure and grading evidence remain separ make test-observability PASS: dashboard, alerts, metrics, correlated logs and cross-process trace +make test-retry-trace +{"scenario":"retry_trace","attachment_id":"7ee0da1b-0c50-4d2e-9bf8-e2c68efb2ce4", + "trace_id":"e8e2aff13b7bdb632c9cec5007dcc6d4","producer_spans":2, + "consumer_spans":2,"result":"PASS"} + make test-alert-worker {"scenario":"worker_outage","firing_state":"Alerting","detect_seconds":61.8, "resolved_state":"Normal","recover_seconds":15.5,"result":"PASS"} make test-alert-database -{"scenario":"database_outage","firing_state":"Alerting","detect_seconds":72.0, - "resolved_state":"Normal","recover_seconds":118.2,"result":"PASS"} +{"scenario":"database_outage","firing_state":"Alerting","detect_seconds":72.2, + "resolved_state":"Normal","recover_seconds":113.1, + "trace_id":"34f96d6fc934f7c54075c44a7b39c176","db_span":"connect", + "db_system":"postgresql","result":"PASS"} make test-telemetry-outage {"scenario":"telemetry_backend_outage","business_smoke":"PASS", - "collector":"running","duration_seconds":12.7,"result":"PASS"} + "collector":"running","duration_seconds":49.5,"rss_before_mib":194.6, + "rss_peak_mib":198.0,"memory_limit_mib":256,"failed_log_records":34, + "failed_spans":30,"result":"PASS"} ``` Worker incident использовал attachment `a88a0cfd-bbda-4151-8584-de27154a8dcb`. diff --git a/evidence/load.json b/evidence/load.json index 6a91f80..d5ce816 100644 --- a/evidence/load.json +++ b/evidence/load.json @@ -1,10 +1,14 @@ { "lab": 6, + "implementation_commit": "9e6428d", + "host": "Apple M4 Pro, 24 GiB RAM", + "docker_vm": "12 CPU, 9.70 GiB RAM; per-service limits from compose.yaml", "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 120.0, "elapsed_seconds": 120.084, "concurrency": 8, "successful_requests": 25638, + "generated_messages": 25638, "failed_requests": 0, "error_ratio": 0.0, "successful_rps": 213.501, diff --git a/infra/otel/collector.yaml b/infra/otel/collector.yaml index 04bbc94..ae749ea 100644 --- a/infra/otel/collector.yaml +++ b/infra/otel/collector.yaml @@ -54,7 +54,13 @@ service: extensions: [health_check] telemetry: metrics: - address: 0.0.0.0:8888 + level: detailed + readers: + - pull: + exporter: + prometheus: + host: 0.0.0.0 + port: 8888 pipelines: metrics: receivers: [otlp] diff --git a/tests/README.md b/tests/README.md index 49ddc24..3863395 100644 --- a/tests/README.md +++ b/tests/README.md @@ -24,6 +24,7 @@ python3 tests/smoke.py --base-url http://localhost:8080 ```sh make test-observability # dashboard, alerts, Prometheus, Loki и Tempo +make test-retry-trace # временная S3-ошибка и retry в одной трассе make test-alert-worker # временно останавливает и восстанавливает worker make test-alert-database # временно останавливает и восстанавливает PostgreSQL make test-telemetry-outage # временно останавливает и восстанавливает Loki/Tempo @@ -31,8 +32,11 @@ make test-telemetry-outage # временно останавливает и Отказные сценарии изменяют состояние только перечисленных контейнеров и всегда выполняют восстановление в `finally`. Используются уникальные синтетические данные; -секреты и tokens не печатаются. Worker-тест ждёт `QueueOldestJobGrowing` в +секреты и tokens не печатаются. Retry-тест временно отключает S3 и проверяет +две producer/consumer попытки в одной трассе. Worker-тест ждёт `QueueOldestJobGrowing` в `Alerting`, затем `Normal`; DB-тест аналогично проверяет `ApiHighServerErrorRate`. +Тест telemetry outage держит backends выключенными более 30 с и фиксирует RSS +Collector и `send_failed` counters. Окна alerts намеренно делают эти два теста не мгновенными. Запускайте их последовательно, а не параллельно. diff --git a/tests/alert_scenarios.py b/tests/alert_scenarios.py index 82243a7..fb6adc7 100644 --- a/tests/alert_scenarios.py +++ b/tests/alert_scenarios.py @@ -6,6 +6,7 @@ import json import os import subprocess import time +import urllib.parse from client import Client @@ -40,6 +41,70 @@ def grafana_rules() -> dict: return json.loads(result.stdout) +def internal_json(url: str) -> dict: + """Читает JSON из внутреннего observability-сервиса через Grafana-контейнер.""" + + result = compose( + "exec", "-T", "grafana", "wget", "-qO-", url, capture=True + ) + return json.loads(result.stdout) + + +def database_failure_evidence(start_ns: int) -> dict[str, str]: + """Находит связанный лог и ошибочный PostgreSQL CLIENT span.""" + + deadline = time.monotonic() + 30 + while time.monotonic() < deadline: + query = urllib.parse.urlencode({ + "query": ( + '{service_name="messenger-api"} | json ' + '| logger="app.error" | message=~".*(database|socket).*"' + ), + "start": str(start_ns), + "end": str(time.time_ns()), + "direction": "backward", + "limit": "20", + }) + loki = internal_json( + "http://loki:3100/loki/api/v1/query_range?" + query + ) + streams = loki.get("data", {}).get("result", []) + if not streams: + time.sleep(2) + continue + entry = streams[0]["values"][0] + metadata = entry[2] if len(entry) > 2 else {} + body = json.loads(entry[1]) + trace_id = metadata.get("trace_id") or body.get("trace_id") + if not trace_id: + time.sleep(2) + continue + trace = internal_json(f"http://tempo:3200/api/traces/{trace_id}") + for batch in trace.get("batches", []): + scopes = batch.get( + "scopeSpans", batch.get("instrumentationLibrarySpans", []) + ) + for scope in scopes: + for span in scope.get("spans", []): + attributes = { + item["key"]: next(iter(item.get("value", {}).values()), "") + for item in span.get("attributes", []) + } + if ( + span.get("kind") == "SPAN_KIND_CLIENT" + and attributes.get("db.system") == "postgresql" + and span.get("status", {}).get("code") == "STATUS_CODE_ERROR" + ): + return { + "trace_id": trace_id, + "log_message": body.get("message", ""), + "db_span": span.get("name", ""), + "db_system": "postgresql", + } + time.sleep(2) + raise RuntimeError("linked PostgreSQL error log/trace was not found") + + def rule_state(title: str) -> str: """Находит alert по заголовку и возвращает его текущее состояние.""" @@ -98,6 +163,7 @@ def database_scenario(base_url: str): """Останавливает PostgreSQL и проверяет firing/resolved для alert по 5xx.""" Client(base_url).call("GET", "/health/ready", schema="Health") + incident_started_ns = time.time_ns() compose("stop", "postgres") load = subprocess.Popen( [ @@ -108,10 +174,12 @@ def database_scenario(base_url: str): ], cwd=ROOT, ) + evidence = None try: firing, detect_seconds = wait_state( "ApiHighServerErrorRate", {"alerting", "firing"}, 130 ) + evidence = database_failure_evidence(incident_started_ns) finally: load.terminate() try: @@ -137,6 +205,10 @@ def database_scenario(base_url: str): "detect_seconds": round(detect_seconds, 1), "resolved_state": normal, "recover_seconds": round(recover_seconds, 1), + "trace_id": evidence["trace_id"], + "log_message": evidence["log_message"], + "db_span": evidence["db_span"], + "db_system": evidence["db_system"], "result": "PASS", }, ensure_ascii=False)) diff --git a/tests/retry_trace.py b/tests/retry_trace.py new file mode 100644 index 0000000..de052b4 --- /dev/null +++ b/tests/retry_trace.py @@ -0,0 +1,144 @@ +#!/usr/bin/env python3 +"""Создаёт временную S3-ошибку и доказывает retry в одной Tempo-трассе.""" +import argparse +from datetime import datetime, timezone +import json +import os +import subprocess +import time +import urllib.parse + +from client import Client + + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +def compose(*args: str, capture: bool = False): + """Запускает Docker Compose и при необходимости возвращает его вывод.""" + + return subprocess.run( + ["docker", "compose", *args], cwd=ROOT, check=True, text=True, + capture_output=capture, + ) + + +def internal_json(url: str) -> dict: + """Читает Loki/Tempo JSON через внутреннюю сеть Compose.""" + + result = compose( + "exec", "-T", "grafana", "wget", "-qO-", url, capture=True + ) + return json.loads(result.stdout) + + +def wait_retry_log(since: str, timeout: int = 45) -> None: + """Ждёт запись worker о планировании повторной попытки.""" + + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + result = compose("logs", "--since", since, "worker", capture=True) + if "job.retry_scheduled" in result.stdout + result.stderr: + return + time.sleep(1) + raise RuntimeError("worker did not schedule retry") + + +def trace_id_for_attachment(attachment_id: str) -> str: + """Находит trace_id лога приёма конкретного синтетического вложения.""" + + deadline = time.monotonic() + 45 + while time.monotonic() < deadline: + now_ns = time.time_ns() + query = urllib.parse.urlencode( + { + "query": ( + '{service_name="messenger-api"} | json ' + f'| event="attachment.accepted" | attachment_id="{attachment_id}"' + ), + "start": str(now_ns - 600_000_000_000), + "end": str(now_ns), + "direction": "backward", + "limit": "5", + } + ) + payload = internal_json( + "http://loki:3100/loki/api/v1/query_range?" + query + ) + streams = payload.get("data", {}).get("result", []) + if streams: + entry = streams[0]["values"][0] + metadata = entry[2] if len(entry) > 2 else {} + trace_id = metadata.get("trace_id") + if not trace_id: + trace_id = json.loads(entry[1]).get("trace_id") + if trace_id: + return trace_id + time.sleep(2) + raise RuntimeError("attachment trace_id is absent in Loki") + + +def trace_span_names(trace_id: str) -> list[str]: + """Ждёт полную трассу и возвращает имена всех её spans.""" + + deadline = time.monotonic() + 60 + last: list[str] = [] + while time.monotonic() < deadline: + payload = internal_json(f"http://tempo:3200/api/traces/{trace_id}") + names: list[str] = [] + for batch in payload.get("batches", []): + scopes = batch.get( + "scopeSpans", batch.get("instrumentationLibrarySpans", []) + ) + for scope in scopes: + names.extend(span.get("name", "") for span in scope.get("spans", [])) + last = names + if names.count("attachments publish") >= 2 and names.count("attachments process") >= 2: + return names + time.sleep(2) + raise RuntimeError(f"retry spans are incomplete: {last}") + + +def main(): + """Внедряет временный отказ S3, восстанавливает его и проверяет retry trace.""" + + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + args = parser.parse_args() + client = Client(args.base_url, timeout=10) + alice, bob, _, chat = client.bootstrap() + compose("stop", "-t", "1", "worker") + attachment = None + retry_seen = False + try: + attachment, _ = client.attachment(alice, chat) + since = datetime.now(timezone.utc).isoformat() + compose("stop", "s3") + compose("up", "-d", "--no-deps", "worker") + wait_retry_log(since) + retry_seen = True + finally: + compose("start", "s3") + compose("up", "-d", "--no-deps", "worker") + if attachment is None or not retry_seen: + raise RuntimeError("retry scenario was not created") + time.sleep(5) + ready = client.wait_ready(bob, attachment, wait_seconds=120) + trace_id = trace_id_for_attachment(ready["id"]) + names = trace_span_names(trace_id) + if not any(name.startswith("s3 ") for name in names): + raise RuntimeError("S3 spans are absent from retry trace") + if not any(name.startswith(("SELECT ", "INSERT ", "UPDATE ", "connect")) for name in names): + raise RuntimeError("SQL spans are absent from retry trace") + print(json.dumps({ + "scenario": "retry_trace", + "attachment_id": ready["id"], + "trace_id": trace_id, + "producer_spans": names.count("attachments publish"), + "consumer_spans": names.count("attachments process"), + "result": "PASS", + })) + + +if __name__ == "__main__": + main() diff --git a/tests/telemetry_outage.py b/tests/telemetry_outage.py index 131c8e5..63a2944 100644 --- a/tests/telemetry_outage.py +++ b/tests/telemetry_outage.py @@ -5,6 +5,7 @@ import json import os import subprocess import time +import urllib.parse from client import Client @@ -21,24 +22,57 @@ def compose(*args: str, capture: bool = False): ) +def prometheus_value(query: str) -> float: + """Читает одно числовое значение Prometheus через внутреннюю сеть Compose.""" + + url = "http://prometheus:9090/api/v1/query?" + urllib.parse.urlencode( + {"query": query} + ) + result = compose( + "exec", "-T", "grafana", "wget", "-qO-", url, capture=True + ) + payload = json.loads(result.stdout) + series = payload.get("data", {}).get("result", []) + if not series: + return 0.0 + return float(series[0]["value"][1]) + + def main(): - """Отключает telemetry backends, запускает smoke и гарантированно восстанавливает их.""" + """Держит backends недоступными >30 с и проверяет бизнес-контур и RSS.""" parser = argparse.ArgumentParser() parser.add_argument("--base-url", default="http://localhost:8080") args = parser.parse_args() + rss_query = 'max(otelcol_process_memory_rss_bytes{job="otel-collector"})' + failed_logs_query = "sum(otelcol_exporter_send_failed_log_records_total) or vector(0)" + failed_spans_query = "sum(otelcol_exporter_send_failed_spans_total) or vector(0)" + rss_before = prometheus_value(rss_query) + failed_logs_before = prometheus_value(failed_logs_query) + failed_spans_before = prometheus_value(failed_spans_query) compose("stop", "loki", "tempo") started = time.monotonic() + rss_samples = [rss_before] try: result = subprocess.run( ["python3", "tests/smoke.py", "--base-url", args.base_url], cwd=ROOT, check=True, text=True, capture_output=True, ) - time.sleep(10) + while time.monotonic() - started < 45: + time.sleep(5) + rss_samples.append(prometheus_value(rss_query)) Client(args.base_url).call("GET", "/health/ready", schema="Health") running = compose("ps", "--status", "running", "--services", capture=True).stdout.split() if "otel-collector" not in running: raise RuntimeError("OTel Collector stopped while exporters were retrying") + failed_logs = prometheus_value(failed_logs_query) - failed_logs_before + failed_spans = prometheus_value(failed_spans_query) - failed_spans_before + if failed_logs + failed_spans <= 0: + raise RuntimeError("Collector did not account for telemetry loss") + rss_peak = max(rss_samples) + memory_limit = 256 * 1024 * 1024 + if rss_peak >= memory_limit: + raise RuntimeError("Collector reached its container memory limit") finally: compose("start", "loki", "tempo") print(json.dumps({ @@ -46,6 +80,11 @@ def main(): "business_smoke": "PASS" if "PASS:" in result.stdout else "UNKNOWN", "collector": "running", "duration_seconds": round(time.monotonic() - started, 1), + "rss_before_mib": round(rss_before / 1024 / 1024, 1), + "rss_peak_mib": round(rss_peak / 1024 / 1024, 1), + "memory_limit_mib": 256, + "failed_log_records": int(failed_logs), + "failed_spans": int(failed_spans), "result": "PASS", }))