Закрыть требования ЛР6 на оценку 4

This commit is contained in:
2026-11-20 19:33:15 +03:00
parent 9e6428de05
commit 67039fd30d
11 changed files with 323 additions and 1472 deletions
+4 -1
View File
@@ -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)"
+31 -12
View File
@@ -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.
## Ограничения и следующие шаги
-813
View File
@@ -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.
-637
View File
@@ -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/` содержат повторяемые команды и результаты.
+15 -5
View File
@@ -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`.
+4
View File
@@ -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,
+7 -1
View File
@@ -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]
+5 -1
View File
@@ -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 намеренно делают эти два теста не мгновенными. Запускайте их
последовательно, а не параллельно.
+72
View File
@@ -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))
+144
View File
@@ -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()
+41 -2
View File
@@ -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",
}))