Files
mtusi2026lab6/docs/lab6-implementation.md
T

814 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Реализация лабораторной работы 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.