diff --git a/AGENTS.md b/AGENTS.md index 2af411a..772c587 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`, с diff --git a/QUESTIONS.md b/QUESTIONS.md index cc0958a..e9065f3 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -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. ### Решения diff --git a/REPORT.md b/REPORT.md index a674ec1..ee7d914 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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); надбавка к diff --git a/openspec/changes/track1-telemetry-cost/.openspec.yaml b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/.openspec.yaml similarity index 100% rename from openspec/changes/track1-telemetry-cost/.openspec.yaml rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/.openspec.yaml diff --git a/openspec/changes/track1-telemetry-cost/design.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/design.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/design.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/design.md diff --git a/openspec/changes/track1-telemetry-cost/proposal.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/proposal.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/proposal.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/proposal.md diff --git a/openspec/changes/track1-telemetry-cost/specs/load-benchmark/spec.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/load-benchmark/spec.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/specs/load-benchmark/spec.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/load-benchmark/spec.md diff --git a/openspec/changes/track1-telemetry-cost/specs/observability/spec.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/observability/spec.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/specs/observability/spec.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/observability/spec.md diff --git a/openspec/changes/track1-telemetry-cost/specs/service-configuration/spec.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/service-configuration/spec.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/specs/service-configuration/spec.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/specs/service-configuration/spec.md diff --git a/openspec/changes/track1-telemetry-cost/tasks.md b/openspec/changes/archive/2026-11-15-track1-telemetry-cost/tasks.md similarity index 100% rename from openspec/changes/track1-telemetry-cost/tasks.md rename to openspec/changes/archive/2026-11-15-track1-telemetry-cost/tasks.md diff --git a/openspec/specs/load-benchmark/spec.md b/openspec/specs/load-benchmark/spec.md index 8acacc7..37baeeb 100644 --- a/openspec/specs/load-benchmark/spec.md +++ b/openspec/specs/load-benchmark/spec.md @@ -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 есть вывод со ссылкой на таблицы сводки, числа совпадают со сводкой, + а для каждого варианта названо, какие внесённые ошибки и медленные запросы он потерял и почему diff --git a/openspec/specs/observability/spec.md b/openspec/specs/observability/spec.md index 1c07ff0..50ae739 100644 --- a/openspec/specs/observability/spec.md +++ b/openspec/specs/observability/spec.md @@ -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 забирает все ряды хранилищ, а свой запрос и своё задание + находятся, как раньше diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index f56bbbb..0a52019 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -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` с именами этих переменных без значений