docs: archive track1-telemetry-cost and sync its specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 06:17:06 +03:00
co-authored by Claude Opus 5.5
parent 56132c77e9
commit b3a5ab8c2b
13 changed files with 363 additions and 24 deletions
+5 -2
View File
@@ -60,7 +60,8 @@ SLI и SLO (доступность на LB 99,5 %, задержка «лёгки
пересняты (2026-11-14) `rules-test.md`, `alerts/check.md` и `backend-outage.md`; пересняты (2026-11-14) `rules-test.md`, `alerts/check.md` и `backend-outage.md`;
`evidence/telemetry/check.md` — на `4a2f9c9` (тот же код и правила, драйвер ждёт в Loki все записи `evidence/telemetry/check.md` — на `4a2f9c9` (тот же код и правила, драйвер ждёт в Loki все записи
прохода relay). Четвёртое изменение лабы, уровень 5, трек 1 «Цена наблюдаемости» — change прохода 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`): выбор трасс в голове и наборы границ `observability`, `service-configuration`, `load-benchmark`): выбор трасс в голове и наборы границ
histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по умолчанию прежнее histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по умолчанию прежнее
поведение), счёт начатых span `otel.sdk.span.started`, запись о старте с долей, набором и поведение), счёт начатых span `otel.sdk.span.started`, запись о старте с долей, набором и
@@ -69,6 +70,8 @@ histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по
`evidence/telemetry-cost/<метка>/`) и выключатель `TELEMETRY=on` у `bench_uploads` и `evidence/telemetry-cost/<метка>/`) и выключатель `TELEMETRY=on` у `bench_uploads` и
`bench_queue`; сбалансированная конфигурация — `bench/otel/` (рабочий стенд остаётся со всеми `bench_queue`; сбалансированная конфигурация — `bench/otel/` (рабочий стенд остаётся со всеми
трассами); гипотезы H1–H8 и критерии B1–B5 — `REPORT.md`, «Цена наблюдаемости (трек 1)». трассами); гипотезы H1–H8 и критерии B1–B5 — `REPORT.md`, «Цена наблюдаемости (трек 1)».
Гипотезы — commit `509afca`, метка `evidence/telemetry-cost/baseline2/` снята на коде `68e14b6`
(каталог — commit `0f5dbfc`), правки verify — commit `56132c7`.
Код перенесён из лабы 5 (репозиторий Код перенесён из лабы 5 (репозиторий
`mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit `mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit
`046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5 `046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5
@@ -154,7 +157,7 @@ max_objects_per_second` (2000 объектов S3/с), отказ по пред
`upload-consistency`, `upload-memory`, `track2-reconciler`, `upload-consistency`, `upload-memory`, `track2-reconciler`,
`fix-upload-put-flake`, `track2-reconcile-cost` лабы 4, `async-attachments`, `fix-upload-put-flake`, `track2-reconcile-cost` лабы 4, `async-attachments`,
`pipeline-reliability`, `unit-of-work` и `track1-queue-overload` лабы 5 и `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/`, активных нет (новые `openspec/changes/archive/`, активных нет (новые
capability: с `s3-storage` — capability: с `s3-storage` —
`object-storage`, с `attachments` — `attachments`, с `object-storage`, с `attachments` — `attachments`, с
+2 -1
View File
@@ -401,7 +401,8 @@ design.
## track1-telemetry-cost ## 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.
### Решения ### Решения
+1 -1
View File
@@ -511,7 +511,7 @@ Collector без времени начала (их закрывает прави
## Цена наблюдаемости (трек 1) ## Цена наблюдаемости (трек 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/`: Методика, гипотезы и критерии с порогами записаны **до метки** (commit `509afca`). Метка — `evidence/telemetry-cost/baseline2/`:
код `68e14b6`, каталог метки — commit `0f5dbfc`, 21 прогон из 21, `dirty: false`. Числа раздела «Результаты» взяты из её код `68e14b6`, каталог метки — commit `0f5dbfc`, 21 прогон из 21, `dirty: false`. Числа раздела «Результаты» взяты из её
`summary.md`. Арифметика поверх сводки: пересчёт приёма на сутки и неделю по её правилу (× 86 400 и × 604 800); надбавка к `summary.md`. Арифметика поверх сводки: пересчёт приёма на сутки и неделю по её правилу (× 86 400 и × 604 800); надбавка к
+216 -5
View File
@@ -70,8 +70,8 @@ run_dev` / `make run_docker`). После завершения, в том чис
Стенд SHALL состоять из балансировщика (LB), реплик приложения, Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL
добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса
уборщика. В профиле очереди к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и уборщика. В профилях очереди и цены телеметрии к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и
уборщик: этот профиль меряет обработку. Остальные профили брокер, relay и worker не запускают: они уборщик: эти профили меряют обработку. Остальные профили брокер, relay и worker не запускают: они
меряют реплику, а реплика к брокеру не обращается. Число реплик SHALL меряют реплику, а реплика к брокеру не обращается. Число реплик SHALL
задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль
@@ -94,13 +94,21 @@ PostgreSQL (`max_connections`) — параметр конфигурации с
умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до
наполнения. наполнения.
Телеметрию стенд SHALL запускать только в вариантах профиля цены телеметрии, где она есть, и в профилях загрузок и очереди
с включённым выключателем (требование «Выключатель телеметрии стенда»). Тогда к стенду SHALL добавляться Collector,
Prometheus, Loki и Tempo из тех же образов, с теми же конфигурациями и лимитами, что у рабочего стенда; вариант профиля цены
телеметрии меняет только настройки SDK, слой выбора трасс Collector и набор рядов Prometheus, которые задаёт методика.
Хранилища телеметрии — в отдельной сети стенда; Grafana на стенде не запускается: в пути данных её нет. Без этого сервисы
телеметрии MUST NOT запускаться, а SDK реплик, worker и relay SHALL быть выключен (`observability`, «Где телеметрия
включена»): методика прежних профилей не меняется.
Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека
1 — во всех прогонах одной конфигурации: 1 — во всех прогонах одной конфигурации:
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный - у каждой реплики приложения — лимит CPU и памяти без swap, заданный
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по
конфигурации); конфигурации);
- у LB, PostgreSQL, Valkey, S3, брокера, relay, worker и уборщика — свои лимиты CPU и памяти - у LB, PostgreSQL, Valkey, S3, брокера, relay, worker, уборщика, Collector и хранилищ телеметрии — свои лимиты CPU и памяти
без swap, заданные методикой; в серии трека 1 они одинаковы во всех без swap, заданные методикой (у Collector и хранилищ телеметрии — рабочего стенда); в серии трека 1 они одинаковы во всех
конфигурациях; у уборщика в управляемом опыте профиля сверки — другой конфигурациях; у уборщика в управляемом опыте профиля сверки — другой
лимит CPU, тоже заданный методикой; лимит CPU, тоже заданный методикой;
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без - у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
@@ -121,7 +129,7 @@ Healthcheck образа приложения SHALL быть отключён:
SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же
docker-сети и обращаться к приложению через LB по имени сервиса, минуя docker-сети и обращаться к приложению через LB по имени сервиса, минуя
проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит
готовыми все реплики. готовыми все реплики, а при запущенной телеметрии — ещё и когда Collector и хранилища телеметрии отвечают готовностью.
#### Scenario: Лимиты в паспорте #### Scenario: Лимиты в паспорте
@@ -200,6 +208,19 @@ docker-сети и обращаться к приложению через LB п
рабочего стенда, порт метрик брокера не опубликован на хосте, а образы, лимиты, значения конкуренции и prefetch и окружение worker и relay рабочего стенда, порт метрик брокера не опубликован на хосте, а образы, лимиты, значения конкуренции и prefetch и окружение worker и relay
записаны в паспорт записаны в паспорт
#### Scenario: Телеметрия выключена по умолчанию
- **WHEN** запускается любой профиль, кроме профиля цены телеметрии, без выключателя телеметрии
- **THEN** Collector, Prometheus, Loki, Tempo и Grafana стенда не запущены, записи о старте реплик, worker и relay говорят,
что телеметрия выключена, а окружение приложения в паспорте то же, что до появления выключателя
#### Scenario: Сервисы телеметрии на стенде
- **WHEN** запускается вариант профиля цены телеметрии с телеметрией
- **THEN** Collector, Prometheus, Loki и Tempo запущены из образов рабочего стенда с его конфигурациями, кроме слоёв
варианта, и его лимитами без swap, порты на хост не опубликованы, Grafana не запущена, а образы, лимиты и контрольные
суммы конфигураций записаны в паспорт
### Requirement: Сценарии нагрузки ### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными Стенд SHALL поддерживать два сценария с синтетическими данными
@@ -2269,3 +2290,193 @@ commit (`RESUME=1`), как у серий трека 1.
- **WHEN** проверяющий открывает раздел очереди в `REPORT.md` - **WHEN** проверяющий открывает раздел очереди в `REPORT.md`
- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки, числа совпадают со сводкой, а рекомендуемая настройка следует из правила и таблиц - **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 есть вывод со ссылкой на таблицы сводки, числа совпадают со сводкой,
а для каждого варианта названо, какие внесённые ошибки и медленные запросы он потерял и почему
+113 -2
View File
@@ -294,8 +294,10 @@ stdout (`service-logging`, «Без содержимого сообщений и
Телеметрия SHALL быть включена на рабочем стенде compose у реплик API, worker и relay. В консоли (`make run_dev`, `make Телеметрия SHALL быть включена на рабочем стенде compose у реплик API, worker и relay. В консоли (`make run_dev`, `make
run_worker`, `make run_relay`), во временном прогоне `make test_isolated`, на стенде отказов `make failure_checks` и на run_worker`, `make run_relay`), во временном прогоне `make test_isolated`, на стенде отказов `make failure_checks` и на
стенде `bench/` она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна стенде `bench/` она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние. На стенде `bench/` её
телеметрия, включает её явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей включают только вариант профиля цены телеметрии и выключатель профилей загрузок и очереди (`load-benchmark`, «Профиль цены
телеметрии», «Выключатель телеметрии стенда»): у реплик, worker и relay — с настройками варианта, а Collector и хранилища
работают на том же стенде. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей
журнала, ни обращений к Collector, ни полей трассы в журнале, ни провайдеров и экспортёра SDK в памяти процесса. Код журнала, ни обращений к Collector, ни полей трассы в журнале, ни провайдеров и экспортёра SDK в памяти процесса. Код
приложения MUST NOT загружать модули SDK трасс и журнала, экспортёра, protobuf и HTTP-клиента экспортёра ни при выключенной приложения MUST NOT загружать модули SDK трасс и журнала, экспортёра, protobuf и HTTP-клиента экспортёра ни при выключенной
телеметрии, ни в процессах, которые SDK не запускают: уборщик, сервис миграций, команда replay. Модулей SDK метрик в таком телеметрии, ни в процессах, которые SDK не запускают: уборщик, сервис миграций, команда replay. Модулей SDK метрик в таком
@@ -320,6 +322,13 @@ run_worker`, `make run_relay`), во временном прогоне `make tes
HTTP-клиента экспортёра, а модулей SDK метрик не больше, чем после одного `import redis.asyncio` в отдельном HTTP-клиента экспортёра, а модулей SDK метрик не больше, чем после одного `import redis.asyncio` в отдельном
интерпретаторе интерпретаторе
#### Scenario: Стенд bench по выключателю
- **WHEN** быстрый профиль очереди запущен без выключателя телеметрии, а затем с `TELEMETRY=on`
- **THEN** в первом прогоне записи о старте реплик, worker и relay говорят, что телеметрия выключена, и Collector на стенде
не запущен; во втором — телеметрия включена с адресом Collector этого стенда, а трассы, записи журнала и метрики реплик,
worker и relay приходят в его хранилища
### Requirement: Наблюдаемость в отчёте ### Requirement: Наблюдаемость в отчёте
`REPORT.md` SHALL описывать: `REPORT.md` SHALL описывать:
@@ -892,3 +901,105 @@ Dashboard из git SHALL показывать сверх панелей уров
- **WHEN** проверяющий читает `REPORT.md` - **WHEN** проверяющий читает `REPORT.md`
- **THEN** для каждого SLI есть формула и SLO, для каждого оповещения — строка таблицы и runbook, для каждого из трёх - **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 забирает все ряды хранилищ, а свой запрос и своё задание
находятся, как раньше
+26 -13
View File
@@ -651,21 +651,27 @@ worker секцию не используют. Запись о старте rela
- `otlp_endpoint` — адрес OTLP/HTTP Collector (схема `http` или `https`, хост и порт, без пути и query), по умолчанию - `otlp_endpoint` — адрес OTLP/HTTP Collector (схема `http` или `https`, хост и порт, без пути и query), по умолчанию
`http://127.0.0.1:4318`; на стенде — Collector в сети compose; `http://127.0.0.1:4318`; на стенде — Collector в сети compose;
- `environment` — значение `deployment.environment.name`, по умолчанию `lab`; - `environment` — значение `deployment.environment.name`, по умолчанию `lab`;
- `trace_sample_ratio` — доля корней трасс, выбранных в голове, число от 0 до 1 включительно, по умолчанию 1 — все трассы
(`observability`, «Выбор трасс в голове»);
- `metric_buckets` — набор границ histogram: `default` (по умолчанию) или `coarse` (`observability`, «Наборы границ
histogram»);
- интервал отправки метрик, срок одной отправки, размер очереди и пакета SDK и пауза между пакетами — с безопасными - интервал отправки метрик, срок одной отправки, размер очереди и пакета SDK и пауза между пакетами — с безопасными
значениями по умолчанию; положительные числа, пакет не больше очереди. значениями по умолчанию; положительные числа, пакет не больше очереди, интервал отправки метрик не больше 30 с — половины
срока рядов экспортёра Collector.
Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»). Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»).
Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секцию применяют только процессы API, Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секцию применяют только процессы API,
worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении. worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении.
Переменные `OTEL_*` стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование Переменные `OTEL_*` стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование
«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни параметры очередей, а процесс с «Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни выбор трасс, ни параметры
включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись `warning` с их именами, без очередей, а процесс с включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись `warning` с
значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, их именами, без значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,
`OTEL_RESOURCE_ATTRIBUTES`) сопоставлены настройкам и постоянным значениям кода в `.env.example` и `REPORT.md`. `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: Телеметрия по умолчанию выключена #### Scenario: Телеметрия по умолчанию выключена
@@ -684,15 +690,22 @@ worker и relay; уборщик, миграции и команда replay те
- **THEN** запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного — - **THEN** запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного —
выключенной выключенной
#### Scenario: Выбор трасс и набор границ окружением
- **WHEN** API запущен с включённой телеметрией, `TELEMETRY__TRACE_SAMPLE_RATIO=0.1` и `TELEMETRY__METRIC_BUCKETS=coarse`, а
файлы не менялись
- **THEN** запись о старте называет долю 0,1, набор `coarse` и интервал отправки метрик, а без этих переменных — долю 1 и
набор `default`
#### Scenario: Неверный параметр телеметрии #### Scenario: Неверный параметр телеметрии
- **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик или с - **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик,
пакетом больше очереди интервалом 60 с, пакетом больше очереди, долей выбора трасс 1.5, −0.1 или `nan` либо набором границ `fine`
- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля - **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля
#### Scenario: Переменные OTEL_* не действуют #### Scenario: Переменные OTEL_* не действуют
- **WHEN** процесс с включённой телеметрией запущен с `OTEL_SDK_DISABLED=true` и `OTEL_EXPORTER_OTLP_ENDPOINT`, указывающим в - **WHEN** процесс с включённой телеметрией запущен с `OTEL_SDK_DISABLED=true`, `OTEL_TRACES_SAMPLER=always_off` и
другое место `OTEL_EXPORTER_OTLP_ENDPOINT`, указывающим в другое место
- **THEN** сигналы по-прежнему приходят в Collector из `[telemetry]`, а в журнале есть запись `warning` с именами этих - **THEN** сигналы по-прежнему приходят в Collector из `[telemetry]`, трассы выбираются по `trace_sample_ratio`, а в журнале
переменных без значений есть запись `warning` с именами этих переменных без значений