docs: archive track1-telemetry-cost and sync its specs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -60,7 +60,8 @@ SLI и SLO (доступность на LB 99,5 %, задержка «лёгки
|
||||
пересняты (2026-11-14) `rules-test.md`, `alerts/check.md` и `backend-outage.md`;
|
||||
`evidence/telemetry/check.md` — на `4a2f9c9` (тот же код и правила, драйвер ждёт в Loki все записи
|
||||
прохода relay). Четвёртое изменение лабы, уровень 5, трек 1 «Цена наблюдаемости» — change
|
||||
`track1-telemetry-cost` (активный, `openspec/changes/track1-telemetry-cost/`, изменяет
|
||||
`track1-telemetry-cost` (заархивирован 2026-11-15,
|
||||
`openspec/changes/archive/2026-11-15-track1-telemetry-cost/`, изменяет
|
||||
`observability`, `service-configuration`, `load-benchmark`): выбор трасс в голове и наборы границ
|
||||
histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по умолчанию прежнее
|
||||
поведение), счёт начатых span `otel.sdk.span.started`, запись о старте с долей, набором и
|
||||
@@ -69,6 +70,8 @@ histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по
|
||||
`evidence/telemetry-cost/<метка>/`) и выключатель `TELEMETRY=on` у `bench_uploads` и
|
||||
`bench_queue`; сбалансированная конфигурация — `bench/otel/` (рабочий стенд остаётся со всеми
|
||||
трассами); гипотезы H1–H8 и критерии B1–B5 — `REPORT.md`, «Цена наблюдаемости (трек 1)».
|
||||
Гипотезы — commit `509afca`, метка `evidence/telemetry-cost/baseline2/` снята на коде `68e14b6`
|
||||
(каталог — commit `0f5dbfc`), правки verify — commit `56132c7`.
|
||||
Код перенесён из лабы 5 (репозиторий
|
||||
`mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit
|
||||
`046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5
|
||||
@@ -154,7 +157,7 @@ max_objects_per_second` (2000 объектов S3/с), отказ по пред
|
||||
`upload-consistency`, `upload-memory`, `track2-reconciler`,
|
||||
`fix-upload-put-flake`, `track2-reconcile-cost` лабы 4, `async-attachments`,
|
||||
`pipeline-reliability`, `unit-of-work` и `track1-queue-overload` лабы 5 и
|
||||
`otel-telemetry`, `job-trace-propagation` и `slo-alerts` лабы 6 — в
|
||||
`otel-telemetry`, `job-trace-propagation`, `slo-alerts` и `track1-telemetry-cost` лабы 6 — в
|
||||
`openspec/changes/archive/`, активных нет (новые
|
||||
capability: с `s3-storage` —
|
||||
`object-storage`, с `attachments` — `attachments`, с
|
||||
|
||||
+2
-1
@@ -401,7 +401,8 @@ design.
|
||||
|
||||
## track1-telemetry-cost
|
||||
|
||||
Change `openspec/changes/track1-telemetry-cost/` (propose 2026-11-14). Номера — решения design.
|
||||
Change `openspec/changes/archive/2026-11-15-track1-telemetry-cost/` (propose 2026-11-14, заархивирован 2026-11-15). Номера
|
||||
— решения design.
|
||||
|
||||
### Решения
|
||||
|
||||
|
||||
@@ -511,7 +511,7 @@ Collector без времени начала (их закрывает прави
|
||||
|
||||
## Цена наблюдаемости (трек 1)
|
||||
|
||||
Change `track1-telemetry-cost` (design — `openspec/changes/track1-telemetry-cost/design.md`, номера решений в скобках).
|
||||
Change `track1-telemetry-cost` (design — `openspec/changes/archive/2026-11-15-track1-telemetry-cost/design.md`, номера решений в скобках).
|
||||
Методика, гипотезы и критерии с порогами записаны **до метки** (commit `509afca`). Метка — `evidence/telemetry-cost/baseline2/`:
|
||||
код `68e14b6`, каталог метки — commit `0f5dbfc`, 21 прогон из 21, `dirty: false`. Числа раздела «Результаты» взяты из её
|
||||
`summary.md`. Арифметика поверх сводки: пересчёт приёма на сутки и неделю по её правилу (× 86 400 и × 604 800); надбавка к
|
||||
|
||||
@@ -70,8 +70,8 @@ run_dev` / `make run_docker`). После завершения, в том чис
|
||||
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
|
||||
PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL
|
||||
добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса
|
||||
уборщика. В профиле очереди к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и
|
||||
уборщик: этот профиль меряет обработку. Остальные профили брокер, relay и worker не запускают: они
|
||||
уборщика. В профилях очереди и цены телеметрии к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и
|
||||
уборщик: эти профили меряют обработку. Остальные профили брокер, relay и worker не запускают: они
|
||||
меряют реплику, а реплика к брокеру не обращается. Число реплик SHALL
|
||||
задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
|
||||
собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль
|
||||
@@ -94,13 +94,21 @@ PostgreSQL (`max_connections`) — параметр конфигурации с
|
||||
умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до
|
||||
наполнения.
|
||||
|
||||
Телеметрию стенд SHALL запускать только в вариантах профиля цены телеметрии, где она есть, и в профилях загрузок и очереди
|
||||
с включённым выключателем (требование «Выключатель телеметрии стенда»). Тогда к стенду SHALL добавляться Collector,
|
||||
Prometheus, Loki и Tempo из тех же образов, с теми же конфигурациями и лимитами, что у рабочего стенда; вариант профиля цены
|
||||
телеметрии меняет только настройки SDK, слой выбора трасс Collector и набор рядов Prometheus, которые задаёт методика.
|
||||
Хранилища телеметрии — в отдельной сети стенда; Grafana на стенде не запускается: в пути данных её нет. Без этого сервисы
|
||||
телеметрии MUST NOT запускаться, а SDK реплик, worker и relay SHALL быть выключен (`observability`, «Где телеметрия
|
||||
включена»): методика прежних профилей не меняется.
|
||||
|
||||
Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека
|
||||
1 — во всех прогонах одной конфигурации:
|
||||
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
|
||||
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по
|
||||
конфигурации);
|
||||
- у LB, PostgreSQL, Valkey, S3, брокера, relay, worker и уборщика — свои лимиты CPU и памяти
|
||||
без swap, заданные методикой; в серии трека 1 они одинаковы во всех
|
||||
- у LB, PostgreSQL, Valkey, S3, брокера, relay, worker, уборщика, Collector и хранилищ телеметрии — свои лимиты CPU и памяти
|
||||
без swap, заданные методикой (у Collector и хранилищ телеметрии — рабочего стенда); в серии трека 1 они одинаковы во всех
|
||||
конфигурациях; у уборщика в управляемом опыте профиля сверки — другой
|
||||
лимит CPU, тоже заданный методикой;
|
||||
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
|
||||
@@ -121,7 +129,7 @@ Healthcheck образа приложения SHALL быть отключён:
|
||||
SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же
|
||||
docker-сети и обращаться к приложению через LB по имени сервиса, минуя
|
||||
проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит
|
||||
готовыми все реплики.
|
||||
готовыми все реплики, а при запущенной телеметрии — ещё и когда Collector и хранилища телеметрии отвечают готовностью.
|
||||
|
||||
#### Scenario: Лимиты в паспорте
|
||||
|
||||
@@ -200,6 +208,19 @@ docker-сети и обращаться к приложению через LB п
|
||||
рабочего стенда, порт метрик брокера не опубликован на хосте, а образы, лимиты, значения конкуренции и prefetch и окружение worker и relay
|
||||
записаны в паспорт
|
||||
|
||||
#### Scenario: Телеметрия выключена по умолчанию
|
||||
|
||||
- **WHEN** запускается любой профиль, кроме профиля цены телеметрии, без выключателя телеметрии
|
||||
- **THEN** Collector, Prometheus, Loki, Tempo и Grafana стенда не запущены, записи о старте реплик, worker и relay говорят,
|
||||
что телеметрия выключена, а окружение приложения в паспорте то же, что до появления выключателя
|
||||
|
||||
#### Scenario: Сервисы телеметрии на стенде
|
||||
|
||||
- **WHEN** запускается вариант профиля цены телеметрии с телеметрией
|
||||
- **THEN** Collector, Prometheus, Loki и Tempo запущены из образов рабочего стенда с его конфигурациями, кроме слоёв
|
||||
варианта, и его лимитами без swap, порты на хост не опубликованы, Grafana не запущена, а образы, лимиты и контрольные
|
||||
суммы конфигураций записаны в паспорт
|
||||
|
||||
### Requirement: Сценарии нагрузки
|
||||
|
||||
Стенд SHALL поддерживать два сценария с синтетическими данными
|
||||
@@ -2269,3 +2290,193 @@ commit (`RESUME=1`), как у серий трека 1.
|
||||
|
||||
- **WHEN** проверяющий открывает раздел очереди в `REPORT.md`
|
||||
- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки, числа совпадают со сводкой, а рекомендуемая настройка следует из правила и таблиц
|
||||
|
||||
### Requirement: Выключатель телеметрии стенда
|
||||
|
||||
Команды `make bench_uploads`, `make bench_queue` и их быстрые варианты SHALL принимать выключатель телеметрии `TELEMETRY` со
|
||||
значениями `on` и `off`, по умолчанию `off`. С `on` стенд SHALL запускать сервисы телеметрии (требование «Фиксированный
|
||||
стенд») и включать SDK в репликах, worker и relay с настройками рабочего стенда: все трассы, прежние границы histogram и
|
||||
интервал отправки метрик. Режим SHALL записываться в паспорт метки вместе с образами и лимитами сервисов телеметрии и
|
||||
называться в сводке; это не отладочное переопределение: продолжение прерванной метки (`RESUME=1`) SHALL требовать тот же
|
||||
режим. Другие профили выключатель MUST NOT принимать: с `on` — ненулевой код до запуска стенда и сообщение с именами
|
||||
профилей, которые его принимают.
|
||||
|
||||
С включённой телеметрией сумма лимитов CPU стенда может превысить число CPU ВМ: тогда это SHALL быть предупреждением в
|
||||
паспорте и сводке с обеими суммами, а не отказом — лимиты CPU делят время, а ВМ уже отдаёт все ядра хоста. Сумма лимитов
|
||||
памяти проверяется прежним правилом.
|
||||
|
||||
У профиля загрузок вариант «до» — образ кода без SDK: при `on` его сравнение с остальными вариантами — смешанное, и сводка
|
||||
SHALL это называть. У профиля очереди CPU, троттлинг и пик памяти Collector и хранилищ телеметрии SHALL сохраняться новыми
|
||||
столбцами в конце таблицы ячеек; без телеметрии они пусты.
|
||||
|
||||
#### Scenario: Очередь с телеметрией
|
||||
|
||||
- **WHEN** выполнен `make bench_queue_quick TELEMETRY=on`
|
||||
- **THEN** записи о старте реплик, worker и relay называют телеметрию включённой и адрес Collector стенда, Collector, Prometheus,
|
||||
Loki и Tempo работают, Grafana нет, в паспорте режим `on`, у ячеек заполнены столбцы сервисов телеметрии, код выхода 0
|
||||
|
||||
#### Scenario: Выключатель у другого профиля
|
||||
|
||||
- **WHEN** профиль, кроме профилей загрузок и очереди, запущен с включённым выключателем телеметрии
|
||||
- **THEN** команда завершается ненулевым кодом до запуска стенда и называет профили, которые принимают выключатель
|
||||
|
||||
#### Scenario: Лимиты CPU больше ВМ
|
||||
|
||||
- **WHEN** сумма лимитов CPU профиля очереди с телеметрией больше числа CPU ВМ
|
||||
- **THEN** прогон идёт, а паспорт и сводка содержат предупреждение с суммой лимитов и числом CPU ВМ
|
||||
|
||||
#### Scenario: Продолжение в другом режиме
|
||||
|
||||
- **WHEN** прерванная метка профиля очереди, снятая с `TELEMETRY=on`, продолжается с `RESUME=1` без выключателя
|
||||
- **THEN** команда завершается ненулевым кодом до запуска стенда и называет режим метки
|
||||
|
||||
### Requirement: Профиль цены телеметрии
|
||||
|
||||
Команда `make bench_telemetry` (метка `TELEMETRY_LABEL`, по умолчанию `baseline`) SHALL мерить цену телеметрии и то, что
|
||||
теряет каждый вариант её настройки, при одинаковой нагрузке. Команда `make bench_telemetry_quick` — все варианты, кроме
|
||||
копии A/A, по одному разу и с короткими окнами, метка `quick-telemetry-…`, в git не идёт. Результаты SHALL сохраняться в
|
||||
`evidence/telemetry-cost/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда, кроме продолжения прерванной метки на
|
||||
том же commit (`RESUME=1`).
|
||||
|
||||
Стенд — требование «Фиксированный стенд»: LB, две реплики, PostgreSQL, Valkey, S3, брокер, relay, worker и уборщик с
|
||||
лимитами рабочего стенда без swap, а в вариантах с телеметрией — Collector, Prometheus, Loki и Tempo. Каждый прогон — свежий
|
||||
стенд на новых volume.
|
||||
|
||||
**Варианты** различаются только телеметрией, остальное одинаково:
|
||||
- `off` — телеметрия выключена, сервисов телеметрии нет;
|
||||
- `full` — как на рабочем стенде: все трассы, прежние границы, интервал отправки метрик 15 с, конфигурации Collector и
|
||||
Prometheus рабочего стенда; `full-aa` — тот же вариант под другим именем: разница с `full` — шум метода (A/A);
|
||||
- `head` — доля выбора трасс в голове 0,1 (`observability`, «Выбор трасс в голове»);
|
||||
- `tail` — типовой выбор трасс в Collector после завершения трассы: трассы со span в статусе ошибки, трассы не короче 0,25 с
|
||||
и 10 % остальных, срок ожидания решения по умолчанию;
|
||||
- `metrics` — агрегация метрик: интервал отправки 30 с, набор границ `coarse` (`observability`, «Наборы границ histogram») и
|
||||
отбор лишних рядов Prometheus — собственных метрик хранилищ;
|
||||
- `balanced` — сбалансированная конфигурация (`observability`, «Сбалансированная конфигурация телеметрии»).
|
||||
|
||||
Каждый вариант SHALL проверяться применённым: записи о старте всех реплик, worker и relay называют настройки телеметрии
|
||||
варианта, Collector и Prometheus работают с его конфигурациями; иначе — отказ команды с названием прогона. До первого
|
||||
прогона SHALL проверяться конфигурации вариантов: слой Collector — инструментом Collector и сравнением с рабочей
|
||||
конфигурацией, конфигурация Prometheus — инструментом Prometheus и совпадением с рабочей вне блоков отбора рядов; расхождение
|
||||
— отказ до стенда.
|
||||
|
||||
**План** — вариант × повтор, повторов три, круги с перестановкой от зерна, повтор одного варианта не идёт подряд; план — в
|
||||
паспорте до первого прогона.
|
||||
|
||||
**Нагрузка прогона** — открытая модель через LB, интенсивности заданы методикой и одинаковы во всех вариантах, ниже
|
||||
насыщения: чтение страницы истории, отправка сообщения с новым ключом, `GET /users/me`, карточка чата, скачивание готовых
|
||||
вложений и загрузка настоящего изображения. Рядом идут **редкие события с известным счётом**:
|
||||
- скачивание вложения, у которого нет объекта в S3, — 500 API со статусом ошибки span;
|
||||
- загрузка изображения, которое проходит проверку структуры и не декодируется, — 202, затем `failed` worker;
|
||||
- регистрация пользователя с Argon2id — редкий маршрут (сохраняется ли он, если он не медленный);
|
||||
- в окне отказов — запись в чат под короткой блокировкой таблицы сообщений: медленные запросы быстрого маршрута.
|
||||
|
||||
Окна прогона: разогрев, чистое окно — по нему считается цена, — окно отказов. Ответ не повторяется. Каждый запрос — строка с
|
||||
временем отправки, длительностью, статусом и `X-Request-Id`. После нагрузки стенд ждёт, пока незавершённых заданий нет, затем
|
||||
отправки последних метрик и решений выбора трасс и только потом читает хранилища.
|
||||
|
||||
Для каждого прогона SHALL сохраняться:
|
||||
- по классам запросов чистого окна — число ответов, ошибки, p50, p95 и p99; время до `ready` по метаданным вложений;
|
||||
- CPU, троттлинг и память (наибольшая, пик контейнера, анонимная) каждого контейнера стенда в чистом окне; CPU реплик на
|
||||
запрос;
|
||||
- объём приёма по сигналам: span, записи журнала и точки метрик, принятые и отправленные Collector; байты и единицы, принятые
|
||||
Tempo и Loki; ряды и отсчёты Prometheus; рост каждого хранилища на диске за прогон;
|
||||
- потери по звеньям SDK → Collector → хранилище для span и записей журнала — отдельно от отброшенного выборкой в голове
|
||||
(счёт начатых span SDK) и в Collector (его решения);
|
||||
- по каждому классу редких событий — счёт по клиенту и найденное в хранилищах: трасса по `X-Request-Id` (у неудачной загрузки
|
||||
— вся цепочка до consumer span исхода `failed`), запись журнала, счёт в метрике и переход от записи журнала к трассе;
|
||||
- точность квантилей: p95 и p99 двух лёгких маршрутов из buckets против точной длительности тех же запросов из журнала.
|
||||
|
||||
Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, истина о готовности — метаданные `GET
|
||||
/attachments/{id}`. Сверх этого оркестратор: читает счётчики cgroup и записи о старте процессов в журналах контейнеров;
|
||||
вставляет до нагрузки одну строку вложения без объекта в базу свежего стенда (схему не трогает); держит в окне отказов
|
||||
блокировку таблицы сообщений в своей сессии PostgreSQL; считает незавершённые задания в PostgreSQL; читает Prometheus, Loki,
|
||||
Tempo и метрики Collector по HTTP из вспомогательного контейнера в сети хранилищ; меряет размер volume хранилищ только на
|
||||
чтение. Приложение он не импортирует.
|
||||
|
||||
Достоверность:
|
||||
- строк о запросах SHALL быть столько, сколько итераций у генератора; недосланные итерации, выгрузка хоста в swap, гибель
|
||||
хранилища или сервиса телеметрии и завершение ядром из-за памяти — пометки прогона;
|
||||
- каждая принятая загрузка SHALL стать `ready`, а каждая загрузка недекодируемого изображения — `failed`; иначе прогон
|
||||
помечен, а код команды в конце метки ненулевой;
|
||||
- выборка из хранилищ, упёршаяся в предел числа результатов, SHALL быть отказом, а не неполным счётом;
|
||||
- потери телеметрии в варианте — результат с числами по звеньям, а не отказ команды.
|
||||
|
||||
В паспорте метки SHALL быть: лимиты и образы всех контейнеров; таблица вариантов с настройками SDK и контрольными суммами
|
||||
конфигураций Collector и Prometheus; интенсивности, окна и расписание блокировок; план; версия ядра ВМ; состояние хоста;
|
||||
посторонние контейнеры; сумма лимитов против ресурсов ВМ.
|
||||
|
||||
Сводка SHALL давать по каждому варианту медиану и разброс повторов, шум A/A, таблицы требования «Цена телеметрии в отчёте»,
|
||||
вывод по каждой гипотезе и по критериям сбалансированной конфигурации и графики.
|
||||
|
||||
#### Scenario: Полный профиль цены телеметрии
|
||||
|
||||
- **WHEN** выполнен `make bench_telemetry`
|
||||
- **THEN** в `evidence/telemetry-cost/<метка>/` есть паспорт, таблицы прогонов, компонентов и классов редких событий, сводка
|
||||
с выводами по гипотезам и критериям и графики, код выхода 0
|
||||
|
||||
#### Scenario: Быстрый профиль цены телеметрии
|
||||
|
||||
- **WHEN** выполнен `make bench_telemetry_quick`
|
||||
- **THEN** каждый вариант, кроме копии A/A, проходит по одному разу на свежем стенде, код выхода 0, каталог метки в git не
|
||||
попадает
|
||||
|
||||
#### Scenario: Вариант не применён
|
||||
|
||||
- **WHEN** запись о старте реплики, worker или relay называет настройки телеметрии, отличные от варианта прогона
|
||||
- **THEN** команда завершается ненулевым кодом и называет прогон и процесс
|
||||
|
||||
#### Scenario: Конфигурация варианта не прошла проверку
|
||||
|
||||
- **WHEN** слой Collector меняет что-то, кроме выбора трасс, или конфигурация Prometheus варианта расходится с рабочей вне
|
||||
блоков отбора рядов
|
||||
- **THEN** команда завершается ненулевым кодом до запуска стенда и называет файл
|
||||
|
||||
#### Scenario: Принятая загрузка не дошла до итога
|
||||
|
||||
- **WHEN** после ожидания у принятой загрузки нет статуса `ready`, а у загрузки недекодируемого изображения — `failed`
|
||||
- **THEN** прогон помечен, число таких загрузок названо в сводке, а код команды в конце метки ненулевой
|
||||
|
||||
#### Scenario: Прерванная метка цены телеметрии
|
||||
|
||||
- **WHEN** прогон метки прерван, и он запущен снова с `RESUME=1` на том же commit
|
||||
- **THEN** готовые прогоны не снимаются заново, а незавершённый снимается с новой попыткой
|
||||
|
||||
### Requirement: Цена телеметрии в отчёте
|
||||
|
||||
`REPORT.md` SHALL содержать по профилю цены телеметрии:
|
||||
- гипотезы с числовыми порогами «подтверждено / нет», записанные и зафиксированные commit раньше метки;
|
||||
- методику: стенд, лимиты, варианты и их параметры, нагрузку и окна, редкие события и как они вносятся и считаются,
|
||||
источник каждого измерения, повторы и правило шума: изменение — эффект, только если разбросы повторов не пересекаются и
|
||||
изменение медианы больше разницы `full` и `full-aa`;
|
||||
- таблицы метки по вариантам: p50, p95 и p99 лёгких запросов и остальных классов, CPU реплик на запрос, CPU и память по
|
||||
компонентам, приём по сигналам, рост хранилищ с пересчётом на сутки и на срок хранения, потери по звеньям отдельно от
|
||||
отброшенного выборкой, время до `ready`;
|
||||
- что теряет каждый вариант: по классам редких событий — трассу, цельную цепочку загрузки, запись журнала, счёт в метрике и
|
||||
переход от журнала к трассе; точность квантилей из buckets; свежесть метрик при редкой отправке; объяснение причин потерь;
|
||||
- сбалансированную конфигурацию: состав, почему каждое правило, критерии и вывод по каждому из них:
|
||||
- B1 — сохранены трассы всех внесённых 500 API и всех медленных по серверу записей (длительность записи доступа — та
|
||||
же величина, что server span, — не меньше 0,25 с) и цепочки всех неудачных загрузок; регистрация — редкий, но быстрый
|
||||
маршрут, у неё называется доля сохранённых трасс;
|
||||
- B2 — приём Tempo не больше 25 % варианта `full` и меньше, чем у `tail`; рядов Prometheus не больше 40 % `full`;
|
||||
- B3 — непреднамеренных потерь нет, трассы не отброшены до решения, пик памяти Collector не больше двух третей его лимита;
|
||||
- B4 — надбавка против `off`: CPU реплик на запрос не больше 25 %, p95 лёгких запросов — не больше 3 мс, p99 — не больше
|
||||
10 мс;
|
||||
- B5 — у сохранённых классов каждая запись журнала с идентификатором трассы ведёт на трассу в Tempo;
|
||||
- рекомендацию с условиями: что оставить на рабочем стенде, что брать при большей нагрузке и когда нужна выборка в голове;
|
||||
- режим телеметрии меток профилей загрузок и очереди последнего шага;
|
||||
- ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, короткие окна на свежих хранилищах (рост на диске —
|
||||
журнал предзаписи, без сжатых блоков), синтетические данные, один Collector, лимиты — доли CPU, Grafana не мерилась.
|
||||
|
||||
Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. Метка SHALL быть снята с закоммиченного кода,
|
||||
commit — в шапке.
|
||||
|
||||
#### Scenario: Гипотезы цены телеметрии до метки
|
||||
|
||||
- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки
|
||||
- **THEN** commit с гипотезами раньше commit с результатами метки
|
||||
|
||||
#### Scenario: Выводы по метке цены телеметрии
|
||||
|
||||
- **WHEN** проверяющий открывает раздел цены наблюдаемости в `REPORT.md`
|
||||
- **THEN** у каждой гипотезы и у каждого критерия B1–B5 есть вывод со ссылкой на таблицы сводки, числа совпадают со сводкой,
|
||||
а для каждого варианта названо, какие внесённые ошибки и медленные запросы он потерял и почему
|
||||
|
||||
@@ -294,8 +294,10 @@ stdout (`service-logging`, «Без содержимого сообщений и
|
||||
|
||||
Телеметрия SHALL быть включена на рабочем стенде compose у реплик API, worker и relay. В консоли (`make run_dev`, `make
|
||||
run_worker`, `make run_relay`), во временном прогоне `make test_isolated`, на стенде отказов `make failure_checks` и на
|
||||
стенде `bench/` она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна
|
||||
телеметрия, включает её явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей
|
||||
стенде `bench/` она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние. На стенде `bench/` её
|
||||
включают только вариант профиля цены телеметрии и выключатель профилей загрузок и очереди (`load-benchmark`, «Профиль цены
|
||||
телеметрии», «Выключатель телеметрии стенда»): у реплик, worker и relay — с настройками варианта, а Collector и хранилища
|
||||
работают на том же стенде. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей
|
||||
журнала, ни обращений к Collector, ни полей трассы в журнале, ни провайдеров и экспортёра SDK в памяти процесса. Код
|
||||
приложения MUST NOT загружать модули SDK трасс и журнала, экспортёра, protobuf и HTTP-клиента экспортёра ни при выключенной
|
||||
телеметрии, ни в процессах, которые SDK не запускают: уборщик, сервис миграций, команда replay. Модулей SDK метрик в таком
|
||||
@@ -320,6 +322,13 @@ run_worker`, `make run_relay`), во временном прогоне `make tes
|
||||
HTTP-клиента экспортёра, а модулей SDK метрик не больше, чем после одного `import redis.asyncio` в отдельном
|
||||
интерпретаторе
|
||||
|
||||
#### Scenario: Стенд bench по выключателю
|
||||
|
||||
- **WHEN** быстрый профиль очереди запущен без выключателя телеметрии, а затем с `TELEMETRY=on`
|
||||
- **THEN** в первом прогоне записи о старте реплик, worker и relay говорят, что телеметрия выключена, и Collector на стенде
|
||||
не запущен; во втором — телеметрия включена с адресом Collector этого стенда, а трассы, записи журнала и метрики реплик,
|
||||
worker и relay приходят в его хранилища
|
||||
|
||||
### Requirement: Наблюдаемость в отчёте
|
||||
|
||||
`REPORT.md` SHALL описывать:
|
||||
@@ -892,3 +901,105 @@ Dashboard из git SHALL показывать сверх панелей уров
|
||||
- **WHEN** проверяющий читает `REPORT.md`
|
||||
- **THEN** для каждого SLI есть формула и SLO, для каждого оповещения — строка таблицы и runbook, для каждого из трёх
|
||||
инцидентов — шаги диагностики со ссылками на сохранённые наблюдения, а для бюджета — числа и требуемые ресурсы ВМ
|
||||
|
||||
### Requirement: Выбор трасс в голове
|
||||
|
||||
Долю трасс, которые выбираются при создании корня, SHALL задавать настройка (`service-configuration`, «Параметры
|
||||
телеметрии»), по умолчанию — все трассы, как раньше. Корень трассы — server span запроса и consumer span доставки без
|
||||
контекста — SHALL выбираться по идентификатору трассы с этой долей; span с родителем — локальным или удалённым из задания —
|
||||
SHALL следовать флагу выборки родителя: у одной загрузки выбрана либо вся цепочка API → relay → worker, либо ни один её span.
|
||||
|
||||
Невыбранный запрос и невыбранная доставка MUST NOT записывать span, в том числе дочерние span хранилищ и процесса обработки.
|
||||
Метрики (счёт и длительность) и записи журнала у них SHALL быть те же, что у выбранных: выборка касается только трасс, а
|
||||
журнал и метрики остаются полным счётом событий. Запись журнала невыбранного запроса в хранилище логов SHALL нести его
|
||||
идентификаторы трассы и span с флагом «не выбрано» — по ним связаны записи одной загрузки, хотя трассы нет; запись stdout —
|
||||
без полей трассы, как вне span (`service-logging`, «Связь записей с трассой»).
|
||||
|
||||
SDK SHALL считать начатые span по решению выборки (выбран, отброшен) и происхождению родителя во внутренних метриках, и этот
|
||||
счёт SHALL доходить до Prometheus: отброшенное выборкой отличается от потерь. Отброшенное выборкой MUST NOT считаться
|
||||
потерей телеметрии: правило потерь (требование «Учёт потерь телеметрии») его не включает, панель потерь и `TelemetryDataLoss`
|
||||
на выборку не реагируют. Счётчик живых span MUST NOT отдаваться: для учёта он не нужен.
|
||||
|
||||
#### Scenario: Доля по умолчанию
|
||||
|
||||
- **WHEN** телеметрия включена без настройки доли, и клиент выполняет N запросов к API
|
||||
- **THEN** у каждого запроса есть трасса, как раньше, а счёт начатых span не содержит отброшенных выборкой
|
||||
|
||||
#### Scenario: Выборка десяти процентов
|
||||
|
||||
- **WHEN** доля — 0,1, и клиент выполняет N ≥ 1000 запросов с известными `X-Request-Id`
|
||||
- **THEN** трасс этих запросов в Tempo — в 95-процентном биномиальном интервале около 0,1 · N, счёт histogram длительности
|
||||
вырос на N, в Loki N записей доступа, у записей невыбранных запросов есть идентификатор трассы с флагом «не выбрано», а
|
||||
трассы с ним в Tempo нет, и счёт отброшенных выборкой корней близок к 0,9 · N
|
||||
|
||||
#### Scenario: Цепочка загрузки выбирается целиком
|
||||
|
||||
- **WHEN** доля — 0,1, и участник загружает файлы, которые становятся `ready`
|
||||
- **THEN** у каждой загрузки в Tempo либо вся цепочка — server span API, span producer relay, consumer span worker с
|
||||
дочерними span, — либо ни одного её span, а счёт исходов worker и время до готовности учитывают все загрузки
|
||||
|
||||
#### Scenario: Выборка не считается потерей
|
||||
|
||||
- **WHEN** доля — 0,1, и стенд работает под нагрузкой без отказов
|
||||
- **THEN** панель потерь показывает ноль, `TelemetryDataLoss` неактивно, а счёт отброшенных выборкой span растёт
|
||||
|
||||
### Requirement: Наборы границ histogram
|
||||
|
||||
Границы buckets histogram длительности HTTP, длительности заданий и времени до готовности SHALL выбираться набором из
|
||||
настроек (`service-configuration`, «Параметры телеметрии»): `default` — прежние границы, `coarse` — меньше границ при тех же
|
||||
покрываемых диапазонах (требования «Метрики HTTP API», «Метрики заданий worker», «Время до готовности»). Оба набора SHALL
|
||||
содержать границы SLO — 0,25 с у длительности HTTP и 30 с у времени до готовности (требование «SLI и SLO»): правила записи,
|
||||
оповещения и панели работают при любом наборе. Интервал отправки метрик SDK SHALL быть не больше половины срока, после
|
||||
которого экспортёр Collector перестаёт отдавать необновлённый ряд (требование «Счётчики после перезапуска процесса»): иначе
|
||||
ряды пропадали бы между отправками.
|
||||
|
||||
#### Scenario: Грубые границы
|
||||
|
||||
- **WHEN** телеметрия реплик и worker включена с набором `coarse`, и под нагрузкой загрузки становятся `ready`
|
||||
- **THEN** значения `le` трёх histogram в Prometheus — границы набора `coarse`, среди них `"0.25"` у длительности HTTP и
|
||||
`"30.0"` у времени до готовности, а правила записи SLI задержки и времени до готовности дают значения
|
||||
|
||||
#### Scenario: Границы по умолчанию
|
||||
|
||||
- **WHEN** телеметрия включена без настройки набора
|
||||
- **THEN** границы трёх histogram — прежние, ряды и запросы панелей те же, что раньше
|
||||
|
||||
### Requirement: Сбалансированная конфигурация телеметрии
|
||||
|
||||
Сбалансированная конфигурация — выбор трасс в Collector после завершения трассы (tail sampling) по правилам этой системы и
|
||||
отбор лишних рядов Prometheus — SHALL лежать в git рядом с профилем цены телеметрии и проверяться им (`load-benchmark`,
|
||||
«Профиль цены телеметрии»):
|
||||
- SDK отправляет все трассы; Collector держит трассу до решения не дольше срока ожидания, которого хватает цепочке загрузки
|
||||
при нагрузке ниже насыщения;
|
||||
- сохраняются все трассы, где есть span со статусом ошибки, consumer span с неуспешным исходом задания (`failed`, `retry`,
|
||||
`error`, `requeued`, `dropped`: у `failed` статуса ошибки нет — это исход, а не исключение), server span не короче порога
|
||||
SLO задержки (0,25 с) или consumer span не короче 5 с, и заданная доля остальных; поздние span уже сохранённой трассы
|
||||
сохраняются вместе с ней;
|
||||
- Prometheus забирает у Loki, Tempo и у себя только ряды приёма данных, отказов и объёма хранения (`up` — всегда); остальные
|
||||
собственные ряды хранилищ — нет: их не читает ни панель, ни правило, ни проверка; метрики приложения и Collector — все;
|
||||
- журнал и метрики приложения не выбираются.
|
||||
|
||||
Слой конфигурации Collector MUST NOT менять ничего, кроме выбора трасс в pipeline трасс, а конфигурация Prometheus — ничего,
|
||||
кроме отбора рядов собственных метрик хранилищ: проверка до замера сравнивает их с конфигурациями рабочего стенда и
|
||||
проверяет инструментами Collector и Prometheus. Рабочий стенд SHALL оставаться со всеми трассами и полным набором рядов:
|
||||
проверки уровней 3 и 4 ищут свой запрос и задание по сохранённым наблюдениям. Конфигурация считается проверенной, когда
|
||||
метка профиля подтверждает критерии B1–B5 (`load-benchmark`, «Цена телеметрии в отчёте»).
|
||||
|
||||
#### Scenario: Ошибки и медленные запросы сохраняются
|
||||
|
||||
- **WHEN** под нагрузкой профиля со сбалансированной конфигурацией внесены 500 API, неудачные задания и медленные записи
|
||||
- **THEN** в Tempo есть трасса каждого 500 и каждой записи, медленной по серверу (server span не короче 0,25 с), по
|
||||
`X-Request-Id`, у неудачного задания — вся цепочка от server span загрузки до consumer span исхода `failed`, а из
|
||||
остальных запросов, в том числе быстрых регистраций, сохранена заданная доля в биномиальном интервале
|
||||
|
||||
#### Scenario: Слой Collector меняет только выбор трасс
|
||||
|
||||
- **WHEN** проверка до замера собирает итоговую конфигурацию Collector со слоем и без него
|
||||
- **THEN** они отличаются только процессором выбора трасс и списком процессоров pipeline трасс, а иначе профиль завершается
|
||||
ненулевым кодом до стенда
|
||||
|
||||
#### Scenario: Рабочий стенд без выбора
|
||||
|
||||
- **WHEN** выполнены `make run_docker` и проверка телеметрии рабочего стенда
|
||||
- **THEN** в конфигурации Collector нет выбора трасс, Prometheus забирает все ряды хранилищ, а свой запрос и своё задание
|
||||
находятся, как раньше
|
||||
|
||||
@@ -651,21 +651,27 @@ worker секцию не используют. Запись о старте rela
|
||||
- `otlp_endpoint` — адрес OTLP/HTTP Collector (схема `http` или `https`, хост и порт, без пути и query), по умолчанию
|
||||
`http://127.0.0.1:4318`; на стенде — Collector в сети compose;
|
||||
- `environment` — значение `deployment.environment.name`, по умолчанию `lab`;
|
||||
- `trace_sample_ratio` — доля корней трасс, выбранных в голове, число от 0 до 1 включительно, по умолчанию 1 — все трассы
|
||||
(`observability`, «Выбор трасс в голове»);
|
||||
- `metric_buckets` — набор границ histogram: `default` (по умолчанию) или `coarse` (`observability`, «Наборы границ
|
||||
histogram»);
|
||||
- интервал отправки метрик, срок одной отправки, размер очереди и пакета SDK и пауза между пакетами — с безопасными
|
||||
значениями по умолчанию; положительные числа, пакет не больше очереди.
|
||||
значениями по умолчанию; положительные числа, пакет не больше очереди, интервал отправки метрик не больше 30 с — половины
|
||||
срока рядов экспортёра Collector.
|
||||
|
||||
Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»).
|
||||
Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секцию применяют только процессы API,
|
||||
worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении.
|
||||
|
||||
Переменные `OTEL_*` стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование
|
||||
«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни параметры очередей, а процесс с
|
||||
включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись `warning` с их именами, без
|
||||
значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,
|
||||
`OTEL_RESOURCE_ATTRIBUTES`) сопоставлены настройкам и постоянным значениям кода в `.env.example` и `REPORT.md`.
|
||||
«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни выбор трасс, ни параметры
|
||||
очередей, а процесс с включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись `warning` с
|
||||
их именами, без значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,
|
||||
`OTEL_RESOURCE_ATTRIBUTES`) и стандартные имена выбора трасс (`OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG`) сопоставлены
|
||||
настройкам и постоянным значениям кода в `.env.example` и `REPORT.md`.
|
||||
|
||||
Запись журнала о старте API, worker и relay SHALL называть, включена ли телеметрия, а при включённой — адрес Collector и
|
||||
окружение.
|
||||
Запись журнала о старте API, worker и relay SHALL называть, включена ли телеметрия, а при включённой — адрес Collector,
|
||||
окружение, долю выбора трасс, набор границ histogram и интервал отправки метрик.
|
||||
|
||||
#### Scenario: Телеметрия по умолчанию выключена
|
||||
|
||||
@@ -684,15 +690,22 @@ worker и relay; уборщик, миграции и команда replay те
|
||||
- **THEN** запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного —
|
||||
выключенной
|
||||
|
||||
#### Scenario: Выбор трасс и набор границ окружением
|
||||
|
||||
- **WHEN** API запущен с включённой телеметрией, `TELEMETRY__TRACE_SAMPLE_RATIO=0.1` и `TELEMETRY__METRIC_BUCKETS=coarse`, а
|
||||
файлы не менялись
|
||||
- **THEN** запись о старте называет долю 0,1, набор `coarse` и интервал отправки метрик, а без этих переменных — долю 1 и
|
||||
набор `default`
|
||||
|
||||
#### Scenario: Неверный параметр телеметрии
|
||||
|
||||
- **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик или с
|
||||
пакетом больше очереди
|
||||
- **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик,
|
||||
интервалом 60 с, пакетом больше очереди, долей выбора трасс 1.5, −0.1 или `nan` либо набором границ `fine`
|
||||
- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля
|
||||
|
||||
#### Scenario: Переменные OTEL_* не действуют
|
||||
|
||||
- **WHEN** процесс с включённой телеметрией запущен с `OTEL_SDK_DISABLED=true` и `OTEL_EXPORTER_OTLP_ENDPOINT`, указывающим в
|
||||
другое место
|
||||
- **THEN** сигналы по-прежнему приходят в Collector из `[telemetry]`, а в журнале есть запись `warning` с именами этих
|
||||
переменных без значений
|
||||
- **WHEN** процесс с включённой телеметрией запущен с `OTEL_SDK_DISABLED=true`, `OTEL_TRACES_SAMPLER=always_off` и
|
||||
`OTEL_EXPORTER_OTLP_ENDPOINT`, указывающим в другое место
|
||||
- **THEN** сигналы по-прежнему приходят в Collector из `[telemetry]`, трассы выбираются по `trace_sample_ratio`, а в журнале
|
||||
есть запись `warning` с именами этих переменных без значений
|
||||
|
||||
Reference in New Issue
Block a user