Files
mtusi2026lab6/docs/lab6-implementation.md
T

40 KiB
Raw Blame History

Реализация лабораторной работы 6 по файлам

Документ описывает изменения относительно базового коммита переноса ЛР5 58f3d4c.

Общая схема

Бизнес-контур ЛР5 сохранён без изменения публичного API:

Client -> HAProxy -> API x2
                    |-> PostgreSQL
                    |-> Redis
                    |-> MinIO/S3
                    `-> outbox -> publisher -> RabbitMQ -> worker -> S3 + PostgreSQL

Поверх него добавлен observability-контур:

API / publisher / worker
          | OTLP HTTP
          v
OpenTelemetry Collector
    |-> metrics -> Prometheus
    |-> logs    -> Loki
    `-> traces  -> Tempo

Prometheus + Loki + Tempo -> Grafana

Главное изменение бизнес-пайплайна — сохранение W3C trace context в outbox и его перенос через RabbitMQ:

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 и пользовательские тела не сохранялись.

Выполненные проверки

Успешно выполнены:

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.