814 lines
40 KiB
Markdown
814 lines
40 KiB
Markdown
# Реализация лабораторной работы 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.
|