From 72cfa9aaf6cce1069c1f748a337f98cfb663c2f3 Mon Sep 17 00:00:00 2001 From: roman Date: Wed, 11 Nov 2026 19:54:37 +0300 Subject: [PATCH] feat: propagate trace context through outbox and add pipeline saturation metrics Co-Authored-By: Claude Opus 5.5 --- .claude/rules/bench.md | 6 +- .claude/rules/docker.md | 15 +- .claude/rules/dto.md | 8 + .claude/rules/infra.md | 16 +- .claude/rules/logging.md | 14 +- .claude/rules/migrations.md | 8 + .claude/rules/repo-layer.md | 7 +- .claude/rules/run-modes.md | 10 +- .claude/rules/settings.md | 8 +- .claude/rules/student-tests.md | 6 +- .claude/rules/telemetry.md | 73 +- .claude/rules/worker.md | 21 +- .claude/skills/run-mtusi-messenger/SKILL.md | 58 +- .claude/skills/run-mtusi-messenger/driver.py | 1030 ++++++++++++++++- .env.example | 6 +- AGENTS.md | 48 +- PLAN.md | 9 +- QUESTIONS.md | 24 +- REPORT.md | 156 ++- bench/bench.compose.yml | 4 + config_example.toml | 9 +- docker-compose.yml | 5 +- .../dashboards/messenger-overview.json | 234 +++- ...00-e4b8c2d17f90_added_job_trace_context.py | 63 + .../changes/job-trace-propagation/design.md | 46 + .../changes/job-trace-propagation/tasks.md | 82 +- service-tests/db/test_pool_counts.py | 85 ++ service-tests/db/test_uow.py | 4 + service-tests/fakes/clients.py | 14 +- service-tests/fakes/repos.py | 35 + service-tests/repo_contract.py | 103 ++ .../unit/test_attachment_processing.py | 97 +- service-tests/unit/test_attachment_relay.py | 140 +++ service-tests/unit/test_attachment_service.py | 40 + service-tests/unit/test_telemetry.py | 721 +++++++++++- service-tests/unit/test_worker_deliveries.py | 73 ++ src/api/dependencies.py | 15 + src/api/routers/v1/attachment.py | 14 +- src/config/settings.py | 10 +- src/core/ports/attachment_job.py | 18 +- src/core/repos/attachment_job.py | 62 + src/core/services/attachment.py | 18 + src/core/services/attachment_processing.py | 106 +- src/core/services/attachment_relay.py | 38 +- src/infra/broker/client.py | 99 +- src/infra/db/engine.py | 40 + src/infra/db/models/attachment.py | 15 + src/infra/logger.py | 7 + src/infra/telemetry/__init__.py | 24 +- src/infra/telemetry/container.py | 112 ++ src/infra/telemetry/core.py | 368 ++---- src/infra/telemetry/db.py | 22 +- src/infra/telemetry/messaging.py | 200 ++++ src/infra/telemetry/metrics.py | 204 ++++ src/infra/telemetry/sdk.py | 222 ++++ src/infra/telemetry/setup.py | 28 +- src/relay/main.py | 91 +- src/schemas/dataclasses/__init__.py | 8 + src/schemas/dataclasses/attachment.py | 60 + src/schemas/jobs/attachment.py | 15 +- src/utils/constants.py | 62 + src/worker/main.py | 108 +- student-tests/failures.compose.yml | 3 + student-tests/run_isolated.py | 4 + 64 files changed, 4699 insertions(+), 552 deletions(-) create mode 100644 migrations/versions/2026_11_11_1200-e4b8c2d17f90_added_job_trace_context.py create mode 100644 service-tests/db/test_pool_counts.py create mode 100644 src/infra/telemetry/container.py create mode 100644 src/infra/telemetry/messaging.py create mode 100644 src/infra/telemetry/metrics.py create mode 100644 src/infra/telemetry/sdk.py diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index d107d53..c8d6ca8 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -179,7 +179,11 @@ change `s3-storage`, решение 9): старт стенда перечисл требует при разборе — его, как секреты S3, генерирует `compose_env`. Новые ключи окружения реплик (`TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`) попадают в `stand.app_env`: метки до лабы 6 с новыми не сравниваются (их в этом репозитории нет). Профиль трека 1 с - телеметрией включает её явно своим окружением; + телеметрией включает её явно своим окружением. С design change `job-trace-propagation` + (решение 7) так же и у `relay`; при выключенной телеметрии модули SDK, экспортёра и + `requests` процессы не загружают (ленивый импорт), поэтому память реплики в метках снова + сравнима с кодом лабы 5, кроме модулей метрик SDK, которые грузит сам redis-py. Пул engine + — `CountingQueuePool` (два счётчика вокруг `connect()`): поведение и цена выдачи прежние; - **PostgreSQL `max_connections`:** 100, как у образа (`-c max_connections` в override); у серий — из конфигурации ячейки, лимиты конфигурации в паспорте (`limits.<конфигурация>`); diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index f3f7043..f9fa5eb 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -313,7 +313,9 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t completed successfully; реплики его не ждут. Healthcheck образа (HTTP) выключен (`healthcheck: disable: true`): уборщик HTTP не слушает и стал бы `unhealthy`, живость — журнал. `stop_grace_period: 10s`, - лимиты 0,25 CPU / 256 МБ (простой ~90 MiB). В консоли (`make run_dev`) + лимиты 0,25 CPU / 256 МБ (простой — `memory.current` ~105 MiB после ленивого импорта SDK, + пик — плановая сверка при старте; числа — раздел change `job-trace-propagation` в + `evidence/telemetry/budget.md`). В консоли (`make run_dev`) уборщика нет; разовый проход — `docker compose run --rm --no-deps cleaner --once`. Стенд отказов запускает его с grace 20 с, интервалом 1 с и без плановой сверки (`RECONCILER__INTERVAL_SECONDS: "0"`, @@ -404,8 +406,15 @@ Design change `otel-telemetry`, решения 1, 7, 14–20; правила к - **Healthcheck** — `wget` у Prometheus (`/-/ready`) и Grafana (`/api/health`); у Collector, Loki и Tempo оболочки в образе нет — healthcheck нет, живость — цели `up` в Prometheus. - **Секреты:** `GRAFANA_ADMIN_PASSWORD` (`:?` «run make env_setup») — только `grafana`; у - Collector, Prometheus, Loki и Tempo секретов нет; `api` и `worker` получают только якорь - `x-telemetry-env` (`TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT` — адрес, не секрет). + Collector, Prometheus, Loki и Tempo секретов нет; `api`, `worker` и с design change + `job-trace-propagation` (решение 7) `relay` получают только якорь `x-telemetry-env` + (`TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT` — адрес, не секрет). У `bench/`, стенда + отказов и `make test_isolated` relay — с `TELEMETRY__ENABLED: "false"`. +- **Без сокета Docker** (design change `job-trace-propagation`, решение 12): CPU и память + контейнеров `api`, `worker`, `relay` процессы читают из своей cgroup v2 (`/sys/fs/cgroup`, + `ro` от UID 10001). Монтирование `docker.sock` никому не добавлять: API Docker — root на ВМ, а + Collector принимает OTLP без аутентификации. cAdvisor, `docker_stats` и `hostmetrics` тоже не + ставятся. - **Брокер** (решение 19): healthcheck — exec-форма `gosu rabbitmq rabbitmq-diagnostics -q check_port_connectivity`: CLI от root на пустом volume создавал `.erlang.cookie` (0400, root) раньше сервера, тот падал на `eacces`. Стенд с нуля проверяет `driver.py stand-from-scratch` diff --git a/.claude/rules/dto.md b/.claude/rules/dto.md index 2104bc2..051d363 100644 --- a/.claude/rules/dto.md +++ b/.claude/rules/dto.md @@ -21,6 +21,14 @@ paths: `AttachmentJobReason` — ещё лимиты, `render_killed`, `render_crashed`, `lease_expired`; `ReconcileFinding.ORPHAN_STAGING`. +С design change `job-trace-propagation` (решения 3, 4, 8, 9): `AttachmentJobDTO.traceparent`, +`tracestate` — последними, `None` по умолчанию (колонки задания); `TraceContextDTO` +(`traceparent`, `tracestate=None` — значения W3C, без baggage; слой API передаёт его сервису +значением), `JobPublicationDTO` (элемент публикации relay: `job_id`, тело, номер попытки +сообщения, `replayed`, `retry_reason`, контекст), `JobDeliveryResultDTO` (итог доставки worker: +исход, попытка, причина, код ошибки, `time_to_ready_seconds`), `QueueSnapshotDTO` (снимок +очереди: время, четыре стадии, `oldest_created_at`). + `src/schemas/dataclasses/.py` — DTO между repo → service → api; `src/schemas/enums/.py` — `StrEnum` доменов. HTTP-модели (pydantic) лежат не здесь, а в `src/api/schemas/` (`api-layer.md`). diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 9a82ed8..0306b24 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -24,7 +24,11 @@ paths: `ImageRenderer`, см. `worker.md`. Потребитель — своё соединение: блокировка публикации не должна останавливать ack. Строка URL -с паролем не собирается, `aio_pika` и `aiormq` на `WARNING`. +с паролем не собирается, `aio_pika` и `aiormq` на `WARNING`. С design change +`job-trace-propagation` (решения 1, 3, 6): `publish_many` принимает `JobPublicationDTO`, +`_publish_one` — span producer и заголовки `traceparent` / `tracestate` сообщения (тело +прежнее); `JobDelivery.trace_context` — из заголовков (`trace_context_from_headers`: `str` или +ASCII `bytes`, шаблон W3C версии `00`, `tracestate` до 512 символов, иначе `None`). Всё, что не содержит бизнес-логики и может смениться от лабы к лабе: логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), S3 (`s3/`), дальше — @@ -301,6 +305,16 @@ paths: `skipped`), `ImageRenderer.render`, `SqlAlchemyUnitOfWork._commit` (`COMMIT`), запросы — слушатели `instrument_engine` (фабрика engine о телеметрии не знает). Span не меняет ни перевода ошибок, ни сроков; новое чтение из хранилища — внутри уже обёрнутого вызова. + С design change `job-trace-propagation` (решения 7, 10, 12): пакет на уровне модуля + импортирует только API OpenTelemetry, SDK — `sdk.py` из `core.start()`; публикация брокера + — span producer (`messaging.py`); `instrument_engine` ещё регистрирует + `db.client.connection.*` (`metrics.py`), метрики контейнера — `container.py` по cgroup v2. +- Пул engine — `CountingQueuePool` (`db/engine.py`, `poolclass=`; design change + `job-trace-propagation`, решение 10): `AsyncAdaptedQueuePool`, у которого публичный + `connect()` считает ожидающих и отказы по сроку (`pending()`, `timeouts()`). `dispose()` + пересоздаёт пул того же класса (`recreate`), метрики читают текущий + `engine.sync_engine.pool`. Опирается на `Pool.connect()`, SQLAlchemy закреплён `<2.2`; смену + ловит `service-tests/db/test_pool_counts.py`. - Клиенты внешних сервисов: адреса и секреты из `settings` (`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки переводятся в доменные исключения. Логи — по `logging.md`, без diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index 7b10275..6ee5b23 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -67,7 +67,11 @@ paths: `uvicorn.error` — `INFO` без своего handler, пишет через `uvicorn` (свой handler дал бы дубли); `uvicorn.access` — выключен; - шумные библиотеки (`sqlalchemy.engine`, драйвер Postgres, `httpx`, - `httpcore`) — `WARNING`: SQL с параметрами в лог не попадает; + `httpcore`) — `WARNING`: SQL с параметрами в лог не попадает; логгер пула + engine `src.infra.db.engine.CountingQueuePool` (`DB_POOL_LOGGER`: SQLAlchemy + называет его по классу пула, а класс живёт в `src`) — тоже `WARNING`, иначе + «Pool recreating» шло бы INFO (design change `job-trace-propagation`, + «Уточнения apply», п. 11); - клиент S3 (с лабы 4): `botocore`, `aiobotocore`, `aiohttp` — явно `WARNING`, даже если кто-то опустит уровень root: на `DEBUG` botocore пишет заголовки запроса с подписью (`Authorization`). @@ -108,7 +112,13 @@ Design change `otel-telemetry`, решения 2 и 12; правило `telemetr `opentelemetry.*` не экспортируются, а handler пропускает в stdout не больше одной в минуту на логгер (`RateLimitFilter`, `TELEMETRY_SDK_LOG_WINDOW_SECONDS`). «Started API» и «Started worker» — `telemetry_enabled`, `telemetry_endpoint`, `telemetry_environment`; `warning` «Ignored -OpenTelemetry environment variables» — `names` без значений. Запрет содержимого раздела ниже +OpenTelemetry environment variables» — `names` без значений. С design change +`job-trace-propagation` (решения 2, 7, 12): то же у relay — его записи идут в Loki +(`service_name` `messenger-relay`), «Started relay» называет телеметрию, «Stopped relay» — после +закрытия SDK, только stdout; проходы relay идут вне span — без `trace_id`. Записи доставки +worker с контекстом — с `trace_id` трассы загрузки. `warning` «Container metrics are +unavailable» (модуль `telemetry`, `cgroup_root`) — один раз при старте и до хуков журнала: +только stdout. Запрет содержимого раздела ниже действует и на отправленные записи: в Loki — те же записи, что в stdout. ### Исключение: запись ранней остановки diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 6f9159d..e9e6247 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -111,6 +111,14 @@ paths: выражение не видит. У `ix_attachment_jobs_published` условие `published_at IS NOT NULL` запрос называет явно: без него общий план на пробе — Seq Scan. Прежний образ на новой схеме работает: новых статусов и `error_code` нет. + - Ревизия `e4b8c2d17f90` (лаба 6, design change `job-trace-propagation`, решение 4): + `attachment_jobs.traceparent` и `tracestate` (`text NULL`) — контекст W3C загрузки, + CHECK `ck_attachment_jobs_traceparent` (шаблон `jobs.schema.json` версии `00`) и + `ck_attachment_jobs_tracestate` (1–512 символов и только вместе с `traceparent`) — оба `NOT + VALID`, как `ck_attachment_jobs_attempt_base`. Первой строкой `SET LOCAL lock_timeout = '2s'`, + `downgrade` — зеркально. Прежний код колонок не пишет и не читает. Проверено на временной + базе: с нуля, повтор, `downgrade -1`, снова `upgrade`, `--sql`, `alembic check` — изменений + нет. - **INVALID-индекс.** Прерванная `CREATE INDEX CONCURRENTLY` (сбой, `lock_timeout`, Ctrl+C) оставляет индекс с `pg_index.indisvalid = false`, и `IF NOT EXISTS` его не пересоздаст: повтор миграции diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index 47dd231..d979368 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -80,7 +80,12 @@ paths: `track1-queue-overload`, решение 3), `mark_published` пакета, `recover_expired_leases`, `has_published_before`, `reset_published_before`; `replay_job`, `list_failed` — состояние в выборках relay константой - `literal_execute`), `attachment_job_replay.py` (`insert_replay`, + `literal_execute`; с design change `job-trace-propagation`, решения 4 и 9: + `insert_job` пишет `traceparent` и `tracestate`, `_JOB_COLUMNS` их читает; + `queue_snapshot(now)` — одно выражение из подзапросов по условиям частичных + индексов outbox (по выражению срока — `scheduled` и `outbox`), опубликованных и + аренды, `LEAST` трёх `min(created_at)`, состояния константой, иначе Seq Scan), + `attachment_job_replay.py` (`insert_replay`, `get_job_replays`) и `attachment_variant.py` (`insert_variant` — `ON CONFLICT DO NOTHING`, `get_variants`, `get_variant`); diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index f582b06..09c586f 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -99,9 +99,13 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n ## Телеметрия (с лабы 6) -Design change `otel-telemetry`, решения 8, 13, 20. Консоль (`make run_dev`, `make -run_worker`) — без телеметрии: «Started API» говорит `telemetry_enabled: false`, к -`127.0.0.1:4318` обращений нет. На стенде compose её включает окружение `api` и `worker`. +Design change `otel-telemetry`, решения 8, 13, 20, и `job-trace-propagation`, решения 7, 15. +Консоль (`make run_dev`, `make run_worker`, `make run_relay`) — без телеметрии: «Started API», +«Started worker» и «Started relay» говорят `telemetry_enabled: false`, к `127.0.0.1:4318` +обращений нет, модулей SDK в процессе нет. На стенде compose её включает окружение `api`, +`worker` и `relay`; `make test_isolated`, стенд отказов и `bench/` выключают её у всех трёх. +Relay закрывает SDK в окне `gather` закрытия клиентов (0,5 с), «Stopped relay» — после него: +худший случай остановки прежний. Остановка: API закрывает SDK после «Stopped API» и ждёт не дольше `TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с; 8 с дренажа + 1 с < 10 с; дренаж 9 с с телеметрией — ошибка настроек, `settings.md`), worker — в окне `gather` diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 701b07e..b93e930 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -245,12 +245,14 @@ run_relay` — те же мосты. Имена skeleton: `BROKER_URL_FILE` → ### Телеметрия (с лабы 6) `[telemetry]` (класс `Telemetry`, design change `otel-telemetry`, решение 8) читают только -процессы API и worker: `enabled` (`False`), `otlp_endpoint` (`http://127.0.0.1:4318`, +процессы API, worker и с design change `job-trace-propagation` (решение 7) relay; уборщик, +миграции и команда replay — нет: `enabled` (`False`), `otlp_endpoint` (`http://127.0.0.1:4318`, валидатор: схема `http`/`https`, хост, порт, без пути, query и учётных данных), `environment` (`lab`, `^[a-z0-9._-]{1,32}$`), `metric_export_interval_seconds` (15), `export_timeout_seconds` (2), `max_queue_size` (2048), `max_export_batch_size` (512, не больше очереди), `schedule_delay_seconds` (1); `float` — `allow_inf_nan=False`. Включает стенд -compose (`x-telemetry-env`: `TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`), в `.env` и +compose у `api`, `worker` и `relay` (`x-telemetry-env`: `TELEMETRY__ENABLED`, +`TELEMETRY__OTLP_ENDPOINT`), в `.env` и `config_example.toml` включения нет: файл монтируется и в консоль. Разовая подмена — `TELEMETRY__*`. **`OTEL_*` — не настройки**, как любые переменные без секции: процесс с включённой телеметрией удаляет их из окружения и пишет `warning` с именами; прокси окружения @@ -259,7 +261,7 @@ compose (`x-telemetry-env`: `TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`), TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` = 8 (валидатор поля `telemetry` в `Settings`, ошибка называет `app.graceful_shutdown_seconds`), без неё — прежние 9 (design change `otel-telemetry`, «Уточнения apply», п. 13). Имена skeleton: -`OTEL_SERVICE_NAME` → константы `TELEMETRY_SERVICE_API` / `_WORKER`, +`OTEL_SERVICE_NAME` → константы `TELEMETRY_SERVICE_API` / `_WORKER` / `_RELAY`, `OTEL_EXPORTER_OTLP_ENDPOINT` → `otlp_endpoint`, `OTEL_EXPORTER_OTLP_PROTOCOL` — постоянно `http/protobuf`, `OTEL_RESOURCE_ATTRIBUTES` → `environment` (`service.*` вычисляет код). `GRAFANA_ADMIN_PASSWORD` (секрет, `ENV_SECRETS` и `ENV_FILLED` Makefile) и `GRAFANA_OUT_PORT` diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 8d437c8..e21857b 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -439,8 +439,10 @@ paths: телеметрии они не запускают (старт списком), а `GRAFANA_ADMIN_PASSWORD` compose требует только при разборе — его даёт `make env_setup`. «Started API» их API называет `telemetry_enabled: false`. Сценарии `observability` по HTTP-тестам не проверяются: их проверяют быстрые тесты -`service-tests/` и команды драйвера `telemetry-check`, `telemetry-outage`, `stand-from-scratch` -на рабочем стенде. +`service-tests/` и команды драйвера `telemetry-check`, `telemetry-outage`, `trace-chain`, +`stand-from-scratch` на рабочем стенде. С design change `job-trace-propagation` (решение 7) и +relay тестовых стендов без телеметрии: `-e TELEMETRY__ENABLED=false` у `<проект>-test-relay` +(`run_isolated.py`), `TELEMETRY__ENABLED: "false"` у `relay` в `failures.compose.yml`. Проверки отказов реплик (остановка, kill, зависание, rolling update) — не pytest, а `make test-failover`, профиль `failover` стенда `bench/` diff --git a/.claude/rules/telemetry.md b/.claude/rules/telemetry.md index 2a33b20..4d755ae 100644 --- a/.claude/rules/telemetry.md +++ b/.claude/rules/telemetry.md @@ -8,28 +8,52 @@ paths: Спеки `observability`, `service-logging` («Связь записей с трассой», «Журнал в хранилище логов»), `service-configuration` («Параметры телеметрии»), `graceful-shutdown` («Остановка при -недоступном Collector»); решения — design change `otel-telemetry` (номера ниже). Здесь то, что -легко нарушить. +недоступном Collector»); решения — design change `otel-telemetry` (номера ниже без пометки) и +`job-trace-propagation` («JTP-n»). Здесь то, что легко нарушить. ## SDK в процессе (`src/infra/telemetry/`) -- **Только API и worker** (решение 5): `start_process_telemetry(<имя>)` после - `early_stop.disarm()`, затем `instrument_engine(engine)`. Relay, уборщик, миграции и процесс - обработки SDK не запускают; окружение процесса обработки — прежнее, без `OTEL_*` и адреса. +- **API, worker и relay** (решение 5, JTP-7): `start_process_telemetry(<имя>)` после + `early_stop.disarm()`, затем `instrument_engine(engine)`. Уборщик, миграции, команда replay и + процесс обработки SDK не запускают; окружение процесса обработки — прежнее, без `OTEL_*` и + адреса. +- **Ленивый SDK** (JTP-7): SDK, экспортёр и `requests` импортирует только `sdk.py`, его — только + `core.start()`; остальные модули пакета — только `opentelemetry-api` (типы SDK — под + `TYPE_CHECKING`). Новый модуль пакета SDK на уровне модуля не импортирует. Исключение вне + пакета — redis-py 8.1 сам грузит `opentelemetry.sdk.metrics` (проба «установлен ли SDK»): + тест сравнивает с `import redis.asyncio` (design JTP, «Уточнения apply»). - **Настройки — только `[telemetry]`** (решение 8): ресурс конструктором без детекторов, sampler - `ALWAYS_ON`, лимиты span, очереди и сроки процессоров, `headers={}`, без сжатия, cumulative, - exemplars выключены, `shutdown_on_exit=False`. Новый параметр SDK — поле секции, а не - переменная `OTEL_*` и не значение по умолчанию SDK. `OTEL_*` удаляются из окружения до + `ParentBased(ALWAYS_ON)` (JTP-5: корни выбираются всегда, удалённый родитель из задания + передаёт свой флаг), лимиты span, очереди и сроки процессоров, `headers={}`, без сжатия, + cumulative, exemplars выключены, `shutdown_on_exit=False`. Новый параметр SDK — поле секции, а + не переменная `OTEL_*` и не значение по умолчанию SDK. `OTEL_*` удаляются из окружения до провайдеров (их читает конструктор: `OTEL_SDK_DISABLED`) и называются в `warning` без значений — только при включённой телеметрии. - **Выключено — ничего**: ни провайдеров, ни хуков журнала, ни обращений к Collector, ни полей - трассы. Все функции пакета при выключенной телеметрии — no-op; глобальные провайдеры - OpenTelemetry не ставятся. -- **Правило корня** (решения 4, 12): трассу начинают только server span запроса (кроме health) и - consumer span доставки. Дочерний span (`child_span`, слушатели engine, `COMMIT`, Valkey, S3, - процесс обработки) — только под записывающим родителем: проверка готовности, проходы уборщика - и relay трасс не создают. Входящие `traceparent` и `tracestate` не извлекаются (`Context()` - корня). + трассы. Все функции пакета при выключенной телеметрии — no-op; глобальные провайдеры и + глобальный propagator OpenTelemetry не ставятся. +- **Правило корня** (решения 4, 12; JTP-2, 3): трассу начинают только server span запроса (кроме + health) и consumer span доставки без контекста. Дочерний span (`child_span`, слушатели engine, + `COMMIT`, Valkey, S3, процесс обработки) — только под записывающим родителем: проверка + готовности, проходы уборщика и relay трасс не создают. Входящие `traceparent` и `tracestate` + HTTP не извлекаются (`Context()` корня). +- **Перенос контекста** (JTP-1–4, 6): только W3C Trace Context (`TraceContextTextMapPropagator`, + `core.PROPAGATOR`), без baggage. Загрузка сохраняет контекст server span в + `attachment_jobs.traceparent` / `tracestate` (`current_trace_context` → `TraceContextDep`); + relay — span `PRODUCER` `publish <очередь>` дочерним к сохранённому контексту + (`messaging.producer_span` в `JobPublisher._publish_one`), его контекст — заголовки AMQP + `traceparent` и `tracestate` (поля тела не заполняются); worker — span `CONSUMER` дочерним к + контексту заголовков и с link на него (`messaging.consumer_span`). Нет контекста или он не по + W3C — ни span producer, ни заголовков, consumer span — корень; relay без телеметрии кладёт + сохранённый контекст как есть. Заголовок разбирает клиент брокера + (`trace_context_from_headers`), тело — сервис: контекст на обработку не влияет. +- **Метрики уровня 4** (JTP-8–13): `messaging.JobObservation.finish(result=…)` — атрибуты попытки, + причины, кода ошибки и `messenger.job.time_to_ready` (только у `ready` без replay); `metrics.py` + — `db.client.connection.*` по текущему пулу engine (`CountingQueuePool`), насыщение worker + (`WorkerLoad`), gauge очереди по последнему снимку relay (старше 30 с — ничего); + `container.py` — cgroup v2 изнутри, без сокета Docker (`start_process_telemetry(..., + cgroup_root=…)`; нет файлов — одна запись `warning` до хуков журнала). Имена и атрибуты — + константы `src/utils/constants.py`, таблица — design JTP, решение 13. - **Атрибуты** (решения 10–12): метки метрик — только метод (стандартный или `_OTHER`), полный шаблон маршрута, код статуса, тип и исход задания. Ни `url.path`, `url.query` (в ней `filename`), заголовков, `client.address`, ключа объекта S3 и кэша (в них id), ни значений @@ -49,8 +73,8 @@ paths: (`begin_shutdown`), ожидание не дольше срока (`wait_closed`), не `asyncio.to_thread` и не `force_flush`: при замороженном Collector `shutdown()` ждёт до 6 с. API — после «Stopped API», `TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с) внутри `API_STOP_BUDGET_SECONDS` (9 с) вместе с - дренажом — сочетание проверяет `Settings`; worker — в окне `gather` закрытия (0,5 с). Новый срок - в остановке — в этот бюджет, а не сверх него. + дренажом — сочетание проверяет `Settings`; worker и relay — в окне `gather` закрытия (0,5 с). + Новый срок в остановке — в этот бюджет, а не сверх него. - **Отправка только в Collector:** экспортёры получают свою `requests.Session` с `trust_env=False` (`_export_session`): прокси, `NO_PROXY` и `.netrc` окружения на неё не действуют, как и `OTEL_*`. @@ -76,8 +100,10 @@ paths: - **Grafana** (решение 16): uid источников `prometheus`, `loki`, `tempo` постоянны, dashboard ссылается на них; `allowUiUpdates: false`, состояние — tmpfs; запросы панелей — имена и метки, которые есть в Prometheus (`http_server_request_duration_seconds_*`, - `messenger_job_duration_seconds_*`, `job` = `service.name`). Квантили — из суммы buckets всех - реплик. Встроенные источники с backend, кроме трёх, выключены (`GF_PLUGINS_DISABLE_PLUGINS`), + `messenger_job_duration_seconds_*`, `job` = `service.name`; с JTP — ряды таблицы решения 13). + Квантили — из суммы buckets всех реплик. Панели уровня 4 — в том же JSON (строки «Pipeline» и + «Saturation», JTP-14); после правки файла — `docker compose restart grafana`: bind mount файла + после замены редактором может показывать прежний inode. Встроенные источники с backend, кроме трёх, выключены (`GF_PLUGINS_DISABLE_PLUGINS`), установка плагинов из сети — тоже. - **Сети и порты** (решение 17): хранилища и Grafana — только в сети `telemetry`, Collector — в обеих; наружу — только Grafana на `127.0.0.1`. Сервисы приложения не ждут сервисов @@ -91,7 +117,8 @@ paths: ## Проверки -`driver.py --port telemetry-check`, `telemetry-outage`, `stand-from-scratch` (решение 21; -`SKILL.md` скилла `run-mtusi-messenger`), быстрые тесты `service-tests/unit/test_telemetry.py`, -`service-tests/db/test_telemetry_db.py`. Консоль, `make test_isolated`, стенд отказов и `bench/` -— без телеметрии (`TELEMETRY__ENABLED: "false"`, решение 20). +`driver.py --port telemetry-check`, `telemetry-outage`, `trace-chain` (JTP-16), +`stand-from-scratch` (решение 21; `SKILL.md` скилла `run-mtusi-messenger`), быстрые тесты +`service-tests/unit/test_telemetry.py`, `service-tests/db/test_telemetry_db.py`, +`service-tests/db/test_pool_counts.py`. Консоль, `make test_isolated`, стенд отказов и `bench/` — +без телеметрии у API, worker и relay (`TELEMETRY__ENABLED: "false"`, решение 20). diff --git a/.claude/rules/worker.md b/.claude/rules/worker.md index e6b20f6..f57b693 100644 --- a/.claude/rules/worker.md +++ b/.claude/rules/worker.md @@ -110,10 +110,23 @@ change `async-attachments` (2, 6–8) и `pipeline-reliability` (1–9, 19). З `dropped`; `error` — непредвиденное исключение в `_handle`), действие с сообщением — его свойство `action`. Новая ветка `handle` возвращает исход, а не `JobOutcome`. Span `CONSUMER` `process <очередь>` и histogram `messenger.job.duration` — в `_handle` после места - конкуренции (ожидание места — не работа), подтверждение внутри span; корень трассы — span - доставки (контекст из сообщения переносит change 2). Span процесса обработки пишет - `ImageRenderer.render` в worker: сам процесс SDK не запускает, его окружение прежнее. Relay - SDK не запускает. Закрытие SDK — в окне `gather` 0,5 с. + конкуренции (ожидание места — не работа), подтверждение внутри span. Span процесса обработки + пишет `ImageRenderer.render` в worker: сам процесс SDK не запускает, его окружение прежнее. + Закрытие SDK — в окне `gather` 0,5 с. +- **Сквозная трасса и уровень 4** (design change `job-trace-propagation`, решения 2, 3, 7–9, + 11): `handle` возвращает `JobDeliveryResultDTO` — исход, взятая попытка (у `skipped` — из + сообщения), причина у `retry` и `failed`, код у `failed`, `time_to_ready_seconds` только у + `ready` с `attempt_base == 0` (от `attachment_jobs.created_at` до фиксации); новая ветка + `handle` отдаёт DTO, а не исход. Consumer span — дочерний к `delivery.trace_context` + (заголовки AMQP, разбор — клиент брокера) с link на него, без контекста — корень; точка входа + пишет атрибуты итога и `messenger.job.time_to_ready` (`observation.finish(result=…)`). Счётчики + `WorkerLoad` «ждут места» и «заняты» — вокруг `async with slots` в `_handle`, снимаются в + `finally`. Relay: SDK по `[telemetry]` (`messenger-relay`), span producer — в + `JobPublisher._publish_one` под сохранённым контекстом (`JobPublicationDTO` из строки + задания: номер попытки, replay `attempt_base > 0`, причина — `last_error_code`), проходы span + не создают; снимок очереди `queue_snapshot()` после успешного прохода не чаще 5 с, отказ + PostgreSQL — пропуск; закрытие SDK — в окне `gather` 0,5 с, «Stopped relay» после него. Команда + replay SDK не запускает: replay в трассе — следующая пара producer / consumer. - **Сообщение** — `src/schemas/jobs/attachment.py`, по `contracts/jobs.schema.json`: только id и служебные поля. Ключи, размер, SHA-256 и тип worker берёт из PostgreSQL. Не по схеме — `error` без содержимого, `reject(requeue=False)`. diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 7be6803..f2b1283 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -466,17 +466,45 @@ Gotchas: ## Лаба 6: телеметрия -Design change `otel-telemetry`, решение 21; правило `.claude/rules/telemetry.md`. На стенде -compose телеметрия включена у `api` и `worker`; Grafana — `http://127.0.0.1:${GRAFANA_OUT_PORT}` -(по умолчанию 3000), пользователь `admin`, пароль — `GRAFANA_ADMIN_PASSWORD` в `.env` (не -печатать). Консольный `driver.py start` — без телеметрии. +Design change `otel-telemetry`, решение 21, и `job-trace-propagation`, решение 16; правило +`.claude/rules/telemetry.md`. На стенде compose телеметрия включена у `api`, `worker` и `relay`; +Grafana — `http://127.0.0.1:${GRAFANA_OUT_PORT}` (по умолчанию 3000), пользователь `admin`, +пароль — `GRAFANA_ADMIN_PASSWORD` в `.env` (не печатать). Консольный `driver.py start` — без +телеметрии. ```sh python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 telemetry-check # ~2 мин -python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 telemetry-outage # ~2,5 мин +python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 telemetry-outage # ~3 мин +python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 trace-chain # ~5 мин python3 .claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2 # ~1 мин на прогон ``` +- **`trace-chain`** — сквозная трасса загрузки и сигналы уровня 4, всё через HTTP API Grafana: + 1) `docker compose stop worker`, три загрузки — `outbox` + `published` в + `messenger_queue_depth{job="messenger-relay"}` = 3, возраст старейшего не меньше времени с + первой загрузки минус 35 с и растёт; `docker start` worker — все `ready`, глубина и возраст 0; + 2) worker остановлен, загрузка F (её `X-Request-Id` R), задание опубликовано (PostgreSQL, + только чтение), `pause s3`, worker запущен, «Retrying job» F в stdout worker, `unpause s3`, F + `ready`; Loki «Uploaded attachment» R → `trace_id` T, записи worker F — с T; трасса T: корень + — server span загрузки `messenger-api`, два span producer `messenger-relay` — дети корня, + попытки 1 и 2, у второго `retry_reason` `storage_unavailable`, `service.instance.id` = relay; + два consumer span `messenger-worker` — parent и link на свой producer, `retry` (попытка 1, + span S3 с ошибкой) и `ready` (попытка 2, `S3.PutObject` ≥ 4, процесс обработки, `COMMIT`); + 3) недекодируемый JPEG → `failed`, `docker compose run --rm --no-deps relay replay + --attachment-id … --apply` → снова `failed`; в трассе загрузки producer с + `messenger.job.replayed` и второй consumer span `failed`; 4) `docker compose stop relay`, + загрузка, `UPDATE attachment_jobs SET traceparent = NULL, tracestate = NULL` по + `attachment_id` (одна строка своего вложения), `docker start` relay — `ready`, у worker другой + `trace_id`, корень — consumer span, span producer нет; 5) пулы (10 у реплик, 2 у worker, 1 у + relay; занятых не больше), ёмкость worker 2, ряды очереди только у relay, пределы контейнеров + = `docker inspect` (`NanoCpus`, `Memory`), память меньше предела, нет `docker.sock` в + `docker compose config`, запросы панелей уровня 4 без ошибок и с данными, время до `ready` + выросло на число загрузок без replay (счётчики двух процессов worker: после перезапуска + Prometheus не видит сброса, если новый процесс насчитал больше), сумма — не меньше 3 × время + остановки worker. В `finally` — `unpause s3`, worker и relay запущены. Код 0 / 1, 2 — нет + стенда или Grafana. Рабочий стенд, ~5 мин; `docker start`, а не `compose start`: тот поднял + бы зависимости, в том числе замороженный S3. + - **`telemetry-check`** — всё через HTTP API Grafana (источники-прокси Prometheus, Loki, Tempo): вход 401 / 401 / 200, порт только на `127.0.0.1`, источники по uid и их проверка, dashboard provisioned и отказ его сохранения, цели Prometheus `up`; затем «тихая» база счётчиков (35 с без @@ -485,21 +513,29 @@ python3 .claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2 только 400 парсера, ограничение), `traceparent`, загрузка и недекодируемый JPEG (12 бит, генератор тестов в образе API). Сверяет stdout ↔ Loki ↔ Tempo по `X-Request-Id`, переходы лог ↔ трасса источников Grafana (derived field Loki → `tempo`; запрос `tracesToLogsV2` источника - Tempo с подстановкой span трассы возвращает её записи), трассу worker по `attachment_id` и - `service.instance.id` worker = `instance_id` его stdout, рост счётчиков ровно на свои запросы + Tempo с подстановкой span трассы возвращает её записи), трассу worker по `attachment_id` — + это трасса загрузки (`trace_id` записи «Uploaded attachment»; с change `job-trace-propagation` + шаги задания — по consumer span `ready` в ней, а не по корню: его родитель — span producer + `messenger-relay`, `service.instance.id` = `instance_id` relay; запись прохода relay в Loki = + stdout, без `trace_id`; корней-span relay в Tempo нет), `service.instance.id` worker = + `instance_id` его stdout, рост счётчиков ровно на свои запросы и задания по обеим репликам, нет рядов `http_route=~"/health.*"` за срок хранения, span S3 с ошибкой при `docker compose pause s3` (`unpause` в `finally`), отсутствие трасс health и чужих корней, сети - хранилищ из `api` и `worker`, разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом, + хранилищ из `api`, `worker` и `relay`, разовый контейнер API с `OTEL_SDK_DISABLED=true` и + чужим адресом, пробу приватности (U, P, T, M, K, F, `Bearer `, `Basic ` по всем записям Loki, трассам Tempo и меткам Prometheus окна), затем `docker compose restart` Collector и хранилищ — те же запись, трасса и значение ряда. Код 0 / 1, 2 — нет стенда или Grafana. - **`telemetry-outage`** — Collector `stop`, затем `pause`: `make test`, загрузка до `ready`, число записей логгеров `opentelemetry.*` в stdout за окно (не больше одной на логгер в минуту), `docker stop` одной реплики и `docker compose stop worker` (время, код, «Stopped API», «Stopped - worker»), `make replicas`, возврат Collector — новые запись, трасса и ряды; затем все сервисы - телеметрии остановлены — `docker compose restart api worker`, `make test`, возврат. В `finally` - — `unpause`, `start` телеметрии, `make replicas`, worker и relay. + worker»), с change `job-trace-propagation` — relay без перезапусков (`StartedAt`, + `RestartCount`) и `docker stop` relay (быстрее 10 с, код 0, «Stopped relay»), `make replicas`, + worker и relay снова запущены, возврат Collector — новые запись, трасса (и span producer + relay) и ряды API, worker и relay; затем все сервисы телеметрии остановлены — `docker compose + restart api worker relay` («Started relay» с телеметрией), `make test`, возврат. В `finally` — + `unpause`, `start` телеметрии, `make replicas`, worker и relay. - **`stand-from-scratch`** — только свой одноразовый проект: `--project` принимает лишь имя `^mtusi-lab6-scratch(-[a-z0-9]+)?$` (по умолчанию `mtusi-lab6-scratch`), иное — `mtusi-lab6`, `mtusi-lab5`, `mtusi-lab6-failures` — код 2 до любых вызовов docker: команда сама делает `down diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index fcfc662..0d609d7 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -232,19 +232,41 @@ PostgreSQL и COMMIT), ссылки лог ↔ трасса источников Grafana, traceparent, PROPFIND и GET к неизвестному пути (BREW — ограничение), 401, 404, нет рядов health; загрузка → - ready → Loki и трасса worker; недекодируемый JPEG → failed; рост + ready → Loki и трасса загрузки (change job-trace-propagation: + трасса задания — трасса загрузки, consumer span ready в ней, span + producer relay с ресурсом messenger-relay, запись прохода relay + в Loki без trace_id); недекодируемый JPEG → failed; рост счётчиков по обеим репликам и по исходам; S3 заморожен → 503 и - span S3 с ошибкой; нет трасс health и чужих корней; сети - хранилищ из api и worker; разовый контейнер с OTEL_*; проба - приватности; рестарт Collector и хранилищ → те же наблюдения; - unpause s3 в finally; код 1 при расхождении, 2 — нет стенда + span S3 с ошибкой; нет трасс health и чужих корней (и корней + relay); сети хранилищ из api, worker и relay; разовый контейнер + с OTEL_*; проба приватности; рестарт Collector и хранилищ → те же + наблюдения; unpause s3 в finally; код 1 при расхождении, 2 — нет + стенда telemetry-outage только стенд с LB и телеметрией: Collector stop, затем pause — make test, загрузка до ready, записи SDK в stdout за окно, - docker stop реплики и docker compose stop worker (время, код, - запись об остановке), make replicas, возврат Collector и новые - сигналы; все сервисы телеметрии остановлены — restart api worker, - make test, возврат; в finally — unpause и start телеметрии, make - replicas, worker и relay; код 1 при расхождении, 2 — нет стенда + relay без перезапусков, docker stop реплики, docker compose stop + worker и relay (время, код, запись об остановке), make replicas, + возврат Collector и новые сигналы (и relay); все сервисы + телеметрии остановлены — restart api worker relay, make test, + возврат; в finally — unpause и start телеметрии, make replicas, + worker и relay; код 1 при расхождении, 2 — нет стенда + trace-chain только стенд с LB и телеметрией (design change + job-trace-propagation, решение 16), всё через HTTP API Grafana с + паролем из .env: 1) worker остановлен, 3 загрузки — глубина + outbox + published 3, возраст растёт; worker запущен — ready, 0; + 2) worker остановлен, загрузка F, S3 заморожен, worker запущен — + «Retrying job», S3 разморожен — ready; трасса F: server span API, + два span producer relay (попытки 1 и 2, причина), два consumer + span worker (parent и link на свой producer, retry со span S3 с + ошибкой, ready с записью S3, процессом обработки и COMMIT), + записи worker с trace_id F; 3) недекодируемый JPEG → failed, + replay --apply → failed; в трассе — producer с replayed и второй + consumer; 4) relay остановлен, загрузка, контекст задания снят + UPDATE, relay запущен — ready, корень трассы worker — consumer + span; 5) время до ready, пулы, ёмкость worker, пределы + контейнеров = docker inspect, нет сокета Docker, один источник + очереди, панели уровня 4 с данными; в finally — unpause s3, start + worker relay; код 1 при расхождении, 2 — нет стенда stand-from-scratch [--project P] [--runs 2] свой проект compose (по умолчанию mtusi-lab6-scratch; имя не по шаблону ^mtusi-lab6-scratch(-[a-z0-9]+)?$ — код 2 до вызовов docker: @@ -9481,6 +9503,7 @@ PROMETHEUS_JOBS = ( ) API_SERVICE_NAME = "messenger-api" WORKER_SERVICE_NAME = "messenger-worker" +RELAY_SERVICE_NAME = "messenger-relay" # SDK отправляет метрики раз в 15 с, Prometheus забирает раз в 15 с: изменение # доходит не позже ~30 с; «тихо» — 35 с без изменения METRIC_QUIET_S = 35 @@ -9786,6 +9809,15 @@ def trace_spans(payload: object) -> list[dict[str, object]]: "status": (span.get("status") or {}).get("code", ""), "attrs": otlp_attrs(span.get("attributes")), "resource": resource, + # link — (trace id, span id) в hex + "links": [ + ( + b64_hex(link.get("traceId", "")), + b64_hex(link.get("spanId", "")), + ) + for link in span.get("links") or [] + ], + "trace": b64_hex(span.get("traceId", "")), "duration": ( int(span["endTimeUnixNano"]) - int(span["startTimeUnixNano"]) @@ -9964,6 +9996,136 @@ def root_span(spans: list[dict[str, object]]) -> dict[str, object]: return roots[0] if len(roots) == 1 else {} +# сквозная трасса загрузки (design change job-trace-propagation, решение 16): +# span relay и worker приходят в Tempo позже корня и отдельными пакетами +TCH_TRACE_WAIT_S = 90 + + +def chain_trace( + grafana: Grafana, + trace_id: str, + complete: Callable[[list[dict[str, object]]], bool], + *, + timeout: float = TCH_TRACE_WAIT_S, +) -> list[dict[str, object]]: + """Span трассы, как только `complete` их принимает; срок вышел — последние + полученные (проверки ниже назовут, чего нет).""" + last: list[dict[str, object]] = [] + + def fetch() -> list[dict[str, object]]: + nonlocal last + status, payload = grafana.trace(trace_id) + spans = trace_spans(payload) if status == 200 else [] + if spans: + last = spans + return spans if complete(spans) else [] + + return poll(fetch, timeout=timeout) or last # type: ignore[return-value] + + +def consumer_spans( + spans: list[dict[str, object]], + *, + outcome: str | None = None, +) -> list[dict[str, object]]: + """Consumer span worker, по номеру попытки; `outcome` — только этого + исхода.""" + found = [ + span + for span in spans + if span["kind"] == "SPAN_KIND_CONSUMER" + and ( + outcome is None + or span["attrs"].get("messenger.job.outcome") == outcome + ) + ] + return sorted( + found, + key=lambda s: int(s["attrs"].get("messenger.job.attempt", 0)), + ) + + +def producer_spans(spans: list[dict[str, object]]) -> list[dict[str, object]]: + """Span producer relay, по номеру попытки сообщения.""" + found = [span for span in spans if span["kind"] == "SPAN_KIND_PRODUCER"] + return sorted( + found, + key=lambda s: int(s["attrs"].get("messenger.job.attempt", 0)), + ) + + +def descendants( + spans: list[dict[str, object]], + span_id: str, +) -> list[dict[str, object]]: + """Все потомки span (без него самого).""" + out: list[dict[str, object]] = [] + frontier = {span_id} + while frontier: + level = [span for span in spans if span["parent"] in frontier] + out.extend(level) + frontier = {str(span["id"]) for span in level} + return out + + +def relay_pass_records( + grafana: Grafana, + since: float, +) -> list[tuple[str, str, str]]: + """Сценарии `service-logging` «Записи relay в Loki» и «Проход relay без + полей трассы»: запись прохода с публикацией — в stdout и в Loki с тем же + `event` и числом опубликованных, без `trace_id` и `span_id`.""" + stdout = [ + record + for record in service_records("relay", since) + if record.get("event") == "Relay pass" + and int(str(record.get("published", 0))) > 0 + ] + + def fetch() -> list[tuple[int, str, dict[str, str]]]: + return [ + item + for item in grafana.loki( + f'{{service_name="{RELAY_SERVICE_NAME}"}}', + since, + time.time() + 5, + ) + if item[1] == "Relay pass" + ] + + loki = poll(fetch) or [] + seen = { + (str(labels.get("published")), str(labels.get("duration_ms"))) + for _, _, labels in loki # type: ignore[misc] + } + wanted = { + (str(r.get("published")), str(r.get("duration_ms"))) for r in stdout + } + return [ + ( + "relay pass record with publication in stdout", + "yes", + yes(bool(stdout)), + ), + ( + "same relay pass records in Loki (event, published)", + "yes", + yes(bool(wanted) and wanted <= seen), + ), + ( + "relay pass records without trace_id in stdout and Loki", + "yes", + yes( + not any("trace_id" in r or "span_id" in r for r in stdout) + and not any( + "trace_id" in labels or "span_id" in labels + for _, _, labels in loki # type: ignore[misc] + ), + ), + ), + ] + + def cmd_telemetry_check(port: int) -> int: """Спеки `observability`, `service-logging`, `service-configuration` на рабочем стенде (design change `otel-telemetry`, решение 21). Всё — через @@ -10191,7 +10353,7 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: step("request with traceparent", 200, status) filename = f"tc-file-{secrets.token_hex(6)}.png" data = FIXTURE_PNG.read_bytes() - status, _, accepted = upload_bytes( + status, upload_hdrs, accepted = upload_bytes( port, token, chat_id, @@ -10200,6 +10362,7 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: filename=filename, ) step("upload sample.png", ATTACHMENT_ACCEPTED, status) + upload_request = upload_hdrs.get("x-request-id", "") attachment_id = ( str(accepted["id"]) if isinstance(accepted, dict) else "missing" ) @@ -10377,6 +10540,19 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: ) step("Loki worker record of the attachment", "1", len(worker_found)) job_trace = worker_found[0][2].get("trace_id", "") if worker_found else "" + # change job-trace-propagation: трасса задания — трасса загрузки + uploaded = loki_request( + grafana, + upload_request, + started, + event="Uploaded attachment", + ) + upload_trace = uploaded[0][2].get("trace_id", "") if uploaded else "" + step( + "job trace = upload trace (trace_id of Uploaded attachment)", + upload_trace or "upload trace", + job_trace, + ) worker_stdout = [ r for r in service_records("worker", started) @@ -10392,10 +10568,22 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: and all(r.get("trace_id") == job_trace for r in worker_stdout), ), ) - job_spans = tempo_trace(grafana, str(job_trace)) if job_trace else [] - job_root = root_span(job_spans) + job_all = ( + chain_trace( + grafana, + str(job_trace), + lambda spans: bool( + consumer_spans(spans, outcome="ready") + and producer_spans(spans), + ), + ) + if job_trace + else [] + ) + ready_consumers = consumer_spans(job_all, outcome="ready") + job_root = ready_consumers[0] if ready_consumers else {} step( - "Tempo consumer span", + "Tempo consumer span in the upload trace", "SPAN_KIND_CONSUMER ready", f"{job_root.get('kind')} " f"{(job_root.get('attrs') or {}).get('messenger.job.outcome')}", @@ -10411,6 +10599,29 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: next(iter(worker_instances)) if len(worker_instances) == 1 else "one", (job_root.get("resource") or {}).get("service.instance.id"), ) + producers = producer_spans(job_all) + producer = next( + (p for p in producers if p["id"] == job_root.get("parent")), + {}, + ) + step( + "consumer span parent: relay producer span", + "SPAN_KIND_PRODUCER", + producer.get("kind"), + ) + relay_instance = (short_ids("relay") or [""])[0] + step( + "producer resource service.name", + RELAY_SERVICE_NAME, + (producer.get("resource") or {}).get("service.name"), + ) + step( + "producer service.instance.id = instance_id of relay stdout", + relay_instance, + (producer.get("resource") or {}).get("service.instance.id"), + ) + rows.extend(relay_pass_records(grafana, started)) + job_spans = descendants(job_all, str(job_root.get("id", ""))) names = [str(span["name"]) for span in job_spans] step( "job spans: PostgreSQL", @@ -10519,9 +10730,17 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: step("trace roots other than requests and deliveries", "0", len(odd_roots)) if odd_roots: print(f" odd roots: {sorted(set(odd_roots))[:10]}") + step( + "traces whose root is a relay span", + "0", + sum( + str(item.get("rootServiceName")) == RELAY_SERVICE_NAME + for item in roots + ), + ) # --- сети: хранилища недоступны приложению ----------------------------- - for service in ("api", "worker"): + for service in ("api", "worker", "relay"): ids = service_ids(service) if not ids: step(f"{service} container", "running", "missing") @@ -10970,7 +11189,11 @@ def timed_stop(container: str) -> tuple[float, str, bool, str]: ) events = [str(r.get("event")) for r in json_records(logs.stdout)] stopped = next( - (e for e in events if e in ("Stopped API", "Stopped worker")), + ( + e + for e in events + if e in ("Stopped API", "Stopped worker", "Stopped relay") + ), "", ) return took, code, bool(stopped), stopped @@ -10997,8 +11220,8 @@ def signals_back( chat_id: str, since: float, ) -> list[tuple[str, str, str]]: - """После возврата Collector: новый запрос в Loki, новая трасса задания, - свежие ряды API и worker в Prometheus.""" + """После возврата Collector: новый запрос в Loki, новая трасса задания + (с span producer relay), свежие ряды API, worker и relay в Prometheus.""" rows: list[tuple[str, str, str]] = [] _, hdrs, _ = call(port, "GET", f"{USERS}/me", token=token) found = loki_request(grafana, hdrs.get("x-request-id", ""), since) @@ -11011,7 +11234,7 @@ def signals_back( yes(bool(trace_id) and bool(tempo_trace(grafana, str(trace_id)))), ), ) - status, _, ready = upload_ready( + status, upload_hdrs, ready = upload_ready( port, token, chat_id, @@ -11029,7 +11252,40 @@ def signals_back( ), ) rows.append(("worker record reaches Loki again", "yes", yes(bool(worker)))) + uploaded = loki_request( + grafana, + upload_hdrs.get("x-request-id", ""), + since, + event="Uploaded attachment", + ) + upload_trace = uploaded[0][2].get("trace_id", "") if uploaded else "" + spans = ( + chain_trace( + grafana, + str(upload_trace), + lambda found: bool(producer_spans(found)), + ) + if upload_trace + else [] + ) + rows.append( + ( + "relay producer span reaches Tempo again", + "yes", + yes( + any( + (p.get("resource") or {}).get("service.name") + == RELAY_SERVICE_NAME + for p in producer_spans(spans) + ), + ), + ), + ) for name, expr in ( + ( + "relay", + f'db_client_connection_max{{job="{RELAY_SERVICE_NAME}"}}', + ), ( "API", f'http_server_request_duration_seconds_count{{job="{API_SERVICE_NAME}"}}', @@ -11097,6 +11353,7 @@ def telemetry_outage(port: int, grafana: Grafana) -> int: for mode in ("stop", "pause"): prefix = f"[collector {mode}] " since = time.time() + relay_before = relay_state() action = "stop" if mode == "stop" else "pause" compose(action, "otel-collector") print(f"{prefix}docker compose {action} otel-collector", flush=True) @@ -11215,13 +11472,40 @@ def telemetry_outage(port: int, grafana: Grafana) -> int: ), ], ) + # relay только что опубликовал задание загрузки (design change + # job-trace-propagation, решение 15): без перезапусков, остановка в срок + add( + [ + ( + prefix + "relay start time and restarts unchanged", + "yes", + yes( + bool(relay_before) and relay_state() == relay_before, + ), + ), + ], + ) + relay = service_ids("relay")[0] + took, exit_code, stopped, _ = timed_stop(relay) + print(f"{prefix}docker stop relay: {took:.2f} s", flush=True) + add( + [ + ( + prefix + f"stop relay faster than {TO_STOP_LIMIT_S} s", + "yes", + yes(took < TO_STOP_LIMIT_S), + ), + (prefix + "relay exit code", "0", exit_code), + (prefix + "Stopped relay in stdout", "yes", yes(stopped)), + ], + ) detached("make", "replicas", timeout=180) add( [ ( - prefix + "worker started again", + prefix + "worker and relay started again", "yes", - yes(ensure_running("worker")), + yes(ensure_running("worker", "relay")), ), ], ) @@ -11258,9 +11542,12 @@ def telemetry_outage(port: int, grafana: Grafana) -> int: "restart", "api", "worker", + "relay", timeout=180, ) - add([(prefix + "docker compose restart api worker", "0", str(code))]) + add( + [(prefix + "docker compose restart api worker relay", "0", str(code))], + ) add([(prefix + "LB ready", "yes", yes(wait_lb_ready(port)))]) starts = [ r @@ -11286,6 +11573,17 @@ def telemetry_outage(port: int, grafana: Grafana) -> int: interval=1, ) add([(prefix + "worker started", "yes", yes(bool(worker_start)))]) + relay_start = poll( + lambda: [ + r + for r in service_records("relay", since) + if r.get("event") == "Started relay" + and r.get("telemetry_enabled") is True + ], + timeout=30, + interval=1, + ) + add([(prefix + "relay started", "yes", yes(bool(relay_start)))]) code, last = make_test(port) add([(prefix + "make test", "0 PASS", f"{code} {last.split(':')[0]}")]) back = time.time() @@ -11318,11 +11616,692 @@ def telemetry_outage(port: int, grafana: Grafana) -> int: ) return report_reconcile( rows, - passed="API and worker work and stop in time without the Collector, " - "signals come back without restarts", + passed="API, worker and relay work and stop in time without the " + "Collector, signals come back without restarts", ) +def relay_state() -> tuple[str, str] | None: + """`StartedAt` и `RestartCount` работающего relay; нет — `None`.""" + ids = service_ids("relay") + if not ids: + return None + out = subprocess.run( + [ + "docker", + "inspect", + "-f", + "{{.State.StartedAt}} {{.RestartCount}}", + ids[0], + ], + capture_output=True, + text=True, + check=False, + ).stdout.split() + return (out[0], out[1]) if len(out) == 2 else None + + +# --- trace-chain (design change job-trace-propagation, решение 16) ---------- + +# загрузок при остановленном worker: глубина очереди +TCH_QUEUE_UPLOADS = 3 +# снимок relay раз в 5 с + отправка SDK 15 с + scrape 15 с +TCH_METRIC_LAG_S = 35 +# пауза между двумя чтениями возраста очереди +TCH_AGE_GAP_S = 20 +TCH_RETRY_WAIT_S = 60 +TCH_REPLAY_WAIT_S = 60 +QUEUE_DEPTH = f'messenger_queue_depth{{job="{RELAY_SERVICE_NAME}"}}' +QUEUE_WAITING = ( + "sum(messenger_queue_depth" + f'{{job="{RELAY_SERVICE_NAME}",messenger_queue_stage=~"outbox|published"}})' +) +QUEUE_AGE = ( + f'max(messenger_queue_oldest_age_seconds{{job="{RELAY_SERVICE_NAME}"}})' +) +TIME_TO_READY_COUNT = ( + f'messenger_job_time_to_ready_seconds_count{{job="{WORKER_SERVICE_NAME}"}}' +) +TIME_TO_READY_SUM = ( + f'messenger_job_time_to_ready_seconds_sum{{job="{WORKER_SERVICE_NAME}"}}' +) + + +def job_row(attachment_id: str) -> dict[str, str]: + """Состояние задания вложения в PostgreSQL: состояние, попытка, отметка + публикации, контекст есть ли. Только чтение; `id` — UUID из ответа API.""" + safe = str(uuid.UUID(attachment_id)) + out = stand_psql( + "SELECT state, attempt, published_at IS NOT NULL, " + "traceparent IS NOT NULL FROM attachment_jobs " + f"WHERE attachment_id = '{safe}';\n", + ).strip() + parts = out.split("|") if out else [] + keys = ("state", "attempt", "published", "traced") + if len(parts) != len(keys): + return {} + return {key: parts[index] for index, key in enumerate(keys)} + + +def cmd_trace_chain(port: int) -> int: + """Спек `observability`, «Цепочка и сигналы уровня 4 находятся» (design + change `job-trace-propagation`, решение 16) на рабочем стенде. Всё — через + HTTP API Grafana с паролем из `.env`; секретов и токенов в выводе нет. + Стенд возвращается в `finally`: S3 разморожен, worker и relay запущены.""" + if not stand_answers(port, "trace-chain"): + return 2 + grafana = Grafana() + if not grafana_ready(grafana): + print(f"trace-chain: no Grafana on 127.0.0.1:{grafana.port}") + return 2 + + def body() -> int: + try: + return trace_chain(port, grafana) + finally: + with signals_ignored(): + detached("docker", "compose", "unpause", "s3") + running = ensure_running("worker", "relay") + print( + f"restored: s3 unpaused, worker and relay running: " + f"{yes(running)}", + flush=True, + ) + + return rc_signals(body) + + +def trace_chain(port: int, grafana: Grafana) -> int: + started = time.time() + rows: list[tuple[str, str, str]] = [] + + def step(name: str, expected: object, got: object) -> None: + rows.append((name, str(expected), str(got))) + mark = "" if str(expected) == str(got) else " <- differs" + print(f"{name}: {got}{mark}", flush=True) + + people = attachment_people(port, "tch") + if people is None: + return 1 + _, tokens, chat_id = people + token = tokens["alice"] + data = FIXTURE_PNG.read_bytes() + ready_uploads = 0 + histogram = {"count": TIME_TO_READY_COUNT, "sum": TIME_TO_READY_SUM} + + def upload(name: str, payload: bytes = data, kind: str = "image/png"): + status, hdrs, accepted = upload_bytes( + port, + token, + chat_id, + payload, + content_type=kind, + filename=f"tch-{name}-{secrets.token_hex(4)}", + ) + step(f"upload {name}", ATTACHMENT_ACCEPTED, status) + accepted_id = str(accepted["id"]) if isinstance(accepted, dict) else "" + return accepted_id, hdrs.get("x-request-id", ""), time.time() + + def upload_trace(request_id: str) -> str: + found = loki_request( + grafana, + request_id, + started, + event="Uploaded attachment", + ) + return str(found[0][2].get("trace_id", "")) if found else "" + + # --- 1. очередь при остановленном worker ------------------------------- + depth_base = grafana.prom_sum(QUEUE_DEPTH) + step("queue depth before (no unfinished jobs)", "0", f"{depth_base:g}") + compose("stop", "worker", timeout=60) + print("docker compose stop worker", flush=True) + queued = [upload(f"queue{n}") for n in range(TCH_QUEUE_UPLOADS)] + first_at = queued[0][2] + waiting = QUEUE_WAITING + depth = poll( + lambda: grafana.prom_sum(waiting) == TCH_QUEUE_UPLOADS, + timeout=METRIC_WAIT_S, + interval=3, + ) + step( + "outbox + published with worker stopped", + str(TCH_QUEUE_UPLOADS), + f"{grafana.prom_sum(waiting):g}" if depth else "not reached", + ) + age_first = grafana.prom_sum(QUEUE_AGE) + since_first = time.time() - first_at + step( + f"oldest age not less than time since first upload - " + f"{TCH_METRIC_LAG_S} s", + "yes", + yes(age_first >= since_first - TCH_METRIC_LAG_S), + ) + time.sleep(TCH_AGE_GAP_S) + age_second = poll( + lambda: grafana.prom_sum(QUEUE_AGE) > age_first, + timeout=METRIC_WAIT_S, + interval=3, + ) + step("oldest age grows", "yes", yes(bool(age_second))) + worker_started = time.time() + # docker start того же контейнера: compose start поднимал бы зависимости + # (и замороженный позже S3) + start_service("worker") + print("docker start worker", flush=True) + statuses = [ + wait_attachment(port, token, item[0]).get("status") for item in queued + ] + step( + "all queued attachments ready after worker start", + "yes", + yes(all(s == "ready" for s in statuses)), + ) + ready_uploads += sum(s == "ready" for s in statuses) + drained = poll( + lambda: ( + grafana.prom_sum(QUEUE_DEPTH) == 0 + and grafana.prom_sum(QUEUE_AGE) == 0 + and bool(grafana.prom(QUEUE_AGE)) + ), + timeout=METRIC_WAIT_S, + interval=3, + ) + step("queue depth and age 0 after ready", "yes", yes(bool(drained))) + least_wait = worker_started - queued[-1][2] + + # --- 2. повторная попытка в той же трассе ------------------------------ + # счётчик процесса worker части 1 до его остановки: Prometheus не видит + # сброса, если новый процесс насчитает больше прежнего + print("waiting for the time-to-ready histogram to settle", flush=True) + process_two, _ = settled(grafana, histogram) + compose("stop", "worker", timeout=60) + print("docker compose stop worker", flush=True) + retry_id, retry_request, _ = upload("retry") + published = poll( + lambda: job_row(retry_id).get("published") == "t", + timeout=30, + interval=0.5, + ) + step("job of F published with worker stopped", "yes", yes(bool(published))) + compose("pause", "s3") + print("docker compose pause s3", flush=True) + retry_since = time.time() + start_service("worker") + print("docker start worker", flush=True) + retried = poll( + lambda: [ + r + for r in service_records("worker", retry_since) + if r.get("event") == "Retrying job" + and r.get("attachment_id") == retry_id + ], + timeout=TCH_RETRY_WAIT_S, + interval=0.3, + ) + compose("unpause", "s3") + print("docker compose unpause s3", flush=True) + step( + "worker stdout: Retrying job of F (storage_unavailable)", + "storage_unavailable", + retried[0].get("reason") if retried else "missing", + ) + final = wait_attachment(port, token, retry_id) + step("F becomes ready after S3 is back", "ready", final.get("status")) + ready_uploads += final.get("status") == "ready" + trace_f = upload_trace(retry_request) + step( + "Loki: Uploaded attachment of R has trace_id T", + "yes", + yes(bool(re.fullmatch("[0-9a-f]{32}", trace_f))), + ) + worker_records = [ + r + for r in service_records("worker", retry_since) + if r.get("attachment_id") == retry_id + and r.get("event") + in ("Started job attempt", "Retrying job", "Attachment became ready") + ] + step( + "worker records of F carry trace_id T", + "yes", + yes( + len(worker_records) >= 3 + and all(r.get("trace_id") == trace_f for r in worker_records), + ), + ) + spans = ( + chain_trace( + grafana, + trace_f, + lambda found: ( + bool(root_span(found)) + and len(producer_spans(found)) >= 2 + and len(consumer_spans(found)) >= 2 + and bool(consumer_spans(found, outcome="ready")) + ), + ) + if trace_f + else [] + ) + rows.extend(retry_chain_rows(spans)) + + # --- 3. replay в той же трассе ----------------------------------------- + jpeg = undecodable_jpeg() + step("undecodable JPEG generated", "yes", yes(jpeg is not None)) + if jpeg is not None: + failed_id, failed_request, _ = upload("replay", jpeg, "image/jpeg") + failed = wait_attachment(port, token, failed_id) + step("undecodable JPEG becomes failed", "failed", failed.get("status")) + first_attempt = job_row(failed_id).get("attempt", "") + code, _ = df_replay("--attachment-id", failed_id, "--apply") + step("replay --apply exit code", "0", code) + again = poll( + lambda: ( + job_row(failed_id).get("state") == "failed" + and job_row(failed_id).get("attempt") != first_attempt + ), + timeout=TCH_REPLAY_WAIT_S, + interval=1, + ) + step("replayed job failed again", "yes", yes(bool(again))) + trace_r = upload_trace(failed_request) + replay_spans = ( + chain_trace( + grafana, + trace_r, + lambda found: ( + len(consumer_spans(found, outcome="failed")) >= 2 + and any( + p["attrs"].get("messenger.job.replayed") is True + for p in producer_spans(found) + ) + ), + ) + if trace_r + else [] + ) + replayed = [ + p + for p in producer_spans(replay_spans) + if p["attrs"].get("messenger.job.replayed") is True + ] + step("producer span with messenger.job.replayed", "1", len(replayed)) + after_replay = [ + c + for c in consumer_spans(replay_spans) + if replayed and c["parent"] == replayed[0]["id"] + ] + step( + "consumer span of the replayed attempt (failed)", + "failed", + after_replay[0]["attrs"].get("messenger.job.outcome") + if after_replay + else "missing", + ) + step( + "two consumer spans failed in the upload trace", + "2", + len(consumer_spans(replay_spans, outcome="failed")), + ) + + # --- 4. задание без контекста ------------------------------------------ + compose("stop", "relay", timeout=60) + print("docker compose stop relay", flush=True) + plain_id, plain_request, _ = upload("plain") + safe = str(uuid.UUID(plain_id)) if plain_id else str(uuid.uuid4()) + updated = stand_psql( + "UPDATE attachment_jobs SET traceparent = NULL, tracestate = NULL " + f"WHERE attachment_id = '{safe}' RETURNING 1;\n", + ).strip() + step("context of one job removed (UPDATE rows)", "1", updated or "0") + start_service("relay") + print("docker start relay", flush=True) + plain = wait_attachment(port, token, plain_id) + step("job without context becomes ready", "ready", plain.get("status")) + ready_uploads += plain.get("status") == "ready" + trace_p = upload_trace(plain_request) + plain_records = poll( + lambda: [ + r + for r in service_records("worker", started) + if r.get("attachment_id") == plain_id + and r.get("event") == "Attachment became ready" + ], + timeout=10, + interval=0.5, + ) + trace_w = ( + str(plain_records[0].get("trace_id", "")) if plain_records else "" + ) + step( + "worker trace_id differs from the upload trace", + "yes", + yes(bool(trace_w) and bool(trace_p) and trace_w != trace_p), + ) + worker_spans = ( + chain_trace(grafana, trace_w, lambda found: bool(root_span(found))) + if trace_w + else [] + ) + plain_root = root_span(worker_spans) + step( + "its root is the consumer span", + f"SPAN_KIND_CONSUMER {WORKER_SERVICE_NAME}", + f"{plain_root.get('kind')} " + f"{(plain_root.get('resource') or {}).get('service.name')}", + ) + step( + "producer spans in the worker trace", + "0", + len(producer_spans(worker_spans)), + ) + upload_only = chain_trace(grafana, trace_p, lambda found: bool(found)) + step( + "producer and consumer spans in the upload trace", + "0", + len(producer_spans(upload_only)) + len(consumer_spans(upload_only)), + ) + + # --- 5. сигналы уровня 4 ----------------------------------------------- + rows.extend(level4_rows(grafana)) + print("waiting for the time-to-ready histogram to settle", flush=True) + final, _ = settled(grafana, histogram) + # счётчики процессов worker, запущенных в частях 1 и 2: оба начинали с 0 + counts = {name: process_two[name] + final[name] for name in final} + step( + "time to ready count grew by the uploads without replay", + str(ready_uploads), + f"{round(counts['count'])}", + ) + grown = counts["sum"] + step( + f"time to ready sum grew by at least " + f"{TCH_QUEUE_UPLOADS} x {least_wait:.0f} s (worker stopped)", + "yes", + yes(grown >= TCH_QUEUE_UPLOADS * least_wait), + ) + return report_reconcile( + rows, + passed="one upload is one trace: producer and consumer per attempt, " + "retry and replay in it, level 4 signals found", + ) + + +def retry_chain_rows( + spans: list[dict[str, object]], +) -> list[tuple[str, str, str]]: + """Трасса загрузки с вынужденной повторной попыткой: корень, два span + producer relay и два consumer span worker со связями parent и link.""" + rows: list[tuple[str, str, str]] = [] + root = root_span(spans) + rows.append( + ( + "root: server span of the upload", + f"POST /api/v1/chats/{{chat_id}}/attachments {API_SERVICE_NAME}", + f"{root.get('name')} " + f"{(root.get('resource') or {}).get('service.name')}", + ), + ) + producers = producer_spans(spans) + consumers = consumer_spans(spans) + rows.append(("producer spans", "2", str(len(producers)))) + rows.append(("consumer spans", "2", str(len(consumers)))) + relay_instance = (short_ids("relay") or [""])[0] + rows.append( + ( + "producers: messenger-relay, children of the root", + "yes", + yes( + bool(producers) + and all( + (p.get("resource") or {}).get("service.name") + == RELAY_SERVICE_NAME + and p["parent"] == root.get("id") + for p in producers + ), + ), + ), + ) + rows.append( + ( + "producer service.instance.id = relay instance_id", + relay_instance, + str( + (producers[0].get("resource") or {}).get( + "service.instance.id", + ), + ) + if producers + else "missing", + ), + ) + rows.append( + ( + "producer attempts", + "[1, 2]", + str([p["attrs"].get("messenger.job.attempt") for p in producers]), + ), + ) + rows.append( + ( + "retry reason of the second producer", + "storage_unavailable", + str(producers[1]["attrs"].get("messenger.job.retry_reason")) + if len(producers) > 1 + else "missing", + ), + ) + by_id = {str(p["id"]): p for p in producers} + rows.append( + ( + "consumers: messenger-worker, parent and link = own producer", + "yes", + yes( + bool(consumers) + and all( + (c.get("resource") or {}).get("service.name") + == WORKER_SERVICE_NAME + and str(c["parent"]) in by_id + and any( + link[1] == c["parent"] for link in c.get("links", []) + ) + for c in consumers + ), + ), + ), + ) + rows.append( + ( + "consumer outcomes and attempts", + "[('retry', 1), ('ready', 2)]", + str( + [ + ( + c["attrs"].get("messenger.job.outcome"), + c["attrs"].get("messenger.job.attempt"), + ) + for c in consumers + ], + ), + ), + ) + first = consumers[0] if consumers else {} + second = consumers[1] if len(consumers) > 1 else {} + rows.append( + ( + "retry consumer reason", + "storage_unavailable", + str((first.get("attrs") or {}).get("messenger.job.reason")), + ), + ) + first_spans = descendants(spans, str(first.get("id", ""))) + rows.append( + ( + "retry consumer: S3 span with error", + "yes", + yes( + any( + str(s["name"]).startswith("S3.") + and s["status"] == "STATUS_CODE_ERROR" + for s in first_spans + ), + ), + ), + ) + names = [ + str(s["name"]) for s in descendants(spans, str(second.get("id", ""))) + ] + rows.append( + ( + "ready consumer: S3.PutObject >= 4, render, COMMIT", + "yes", + yes( + names.count("S3.PutObject") >= 4 + and "render attachment variants" in names + and "COMMIT" in names, + ), + ), + ) + for check, expected, got in rows: + mark = "" if expected == got else " <- differs" + print(f"{check}: {got}{mark}", flush=True) + return rows + + +def level4_rows(grafana: Grafana) -> list[tuple[str, str, str]]: + """Пулы, насыщение worker, контейнеры = `docker inspect`, нет сокета + Docker, один источник очереди, панели уровня 4 с данными.""" + rows: list[tuple[str, str, str]] = [] + limits = grafana.prom("db_client_connection_max") + by_job: dict[str, list[str]] = {} + for item in limits: + job = str(item["metric"].get("job")) + by_job.setdefault(job, []).append(f"{float(item['value'][1]):g}") + rows.append( + ( + "pool max: API replicas, worker, relay", + "['10', '10'] ['2'] ['1']", + f"{sorted(by_job.get(API_SERVICE_NAME, []))} " + f"{by_job.get(WORKER_SERVICE_NAME, [])} " + f"{by_job.get(RELAY_SERVICE_NAME, [])}", + ), + ) + over = grafana.prom( + 'sum by (job, instance) (db_client_connection_count{db_client_connection_state="used"}) ' + "> sum by (job, instance) (db_client_connection_max)", + ) + rows.append(("pools with used above max", "0", str(len(over)))) + rows.append( + ( + "worker capacity", + "2", + f"{grafana.prom_sum('sum(messenger_worker_capacity)'):g}", + ), + ) + sources = sorted( + { + str(item["metric"].get("job")) + for item in grafana.prom( + "count by (job) ({__name__=~" + '"messenger_queue_depth|messenger_queue_oldest_age_seconds"})', + ) + }, + ) + rows.append( + ( + "queue series only from relay", + f"['{RELAY_SERVICE_NAME}']", + str(sources), + ), + ) + cpu = { + str(i["metric"].get("instance")): float(i["value"][1]) + for i in grafana.prom("messenger_container_cpu_limit") + } + memory = { + str(i["metric"].get("instance")): float(i["value"][1]) + for i in grafana.prom("messenger_container_memory_limit_bytes") + } + usage = { + str(i["metric"].get("instance")): float(i["value"][1]) + for i in grafana.prom("container_memory_usage_bytes") + } + for service in ("api", "worker", "relay"): + for item in service_containers(service): + short = str(item["Id"])[:12] + host = item["HostConfig"] + nano = int(host.get("NanoCpus") or 0) + want_cpu = f"{nano / 1e9:g}" + want_mem = str(int(host.get("Memory") or 0)) + rows.append( + ( + f"{service} {short} limits = docker inspect", + f"{want_cpu} {want_mem}", + f"{cpu.get(short, 0):g} {memory.get(short, 0):.0f}", + ), + ) + rows.append( + ( + f"{service} {short} memory below the limit", + "yes", + yes(0 < usage.get(short, 0) < memory.get(short, 0)), + ), + ) + config = compose("config") + rows.append( + ( + "Docker socket mounted by any service", + "no", + yes("docker.sock" in config), + ), + ) + status, dashboard = grafana.request( + "GET", + f"/api/dashboards/uid/{DASHBOARD_UID}", + ) + model = ( + dashboard.get("dashboard", {}) if isinstance(dashboard, dict) else {} + ) + expressions = [ + str(target["expr"]) + for panel in model.get("panels", []) + if panel.get("id", 0) >= LEVEL4_FIRST_PANEL + or "0.99" in json.dumps(panel) + for target in panel.get("targets", []) + if (target.get("datasource") or {}).get("uid") == "prometheus" + ] + failed = [] + empty = [] + for expr in expressions: + result_status, result = grafana.proxy( + "prometheus", + "/api/v1/query", + {"query": expr}, + ) + if result_status != 200 or not isinstance(result, dict): + failed.append(expr[:60]) + elif not result.get("data", {}).get("result"): + empty.append(expr[:60]) + rows.append(("dashboard loaded", "200", str(status))) + rows.append( + ( + f"level 4 panel queries ({len(expressions)}) without error", + "[]", + str(failed), + ), + ) + rows.append(("level 4 panel queries with data", "[]", str(empty))) + for check, expected, got in rows: + mark = "" if expected == got else " <- differs" + print(f"{check}: {got}{mark}", flush=True) + return rows + + +# первая панель уровня 4 в messenger-overview.json (строка Pipeline) +LEVEL4_FIRST_PANEL = 14 + + SCRATCH_PROJECT = "mtusi-lab6-scratch" # имена проекта, которые команда принимает: она сама удаляет его volumes SCRATCH_PROJECT_NAME = re.compile(r"^mtusi-lab6-scratch(-[a-z0-9]+)?$") @@ -11650,6 +12629,7 @@ def main() -> int: ) sub.add_parser("telemetry-check") sub.add_parser("telemetry-outage") + sub.add_parser("trace-chain") scratch = sub.add_parser("stand-from-scratch") scratch.add_argument("--project", default=SCRATCH_PROJECT) scratch.add_argument("--runs", type=int, default=2) @@ -11778,6 +12758,8 @@ def main() -> int: return cmd_telemetry_check(port) if args.cmd == "telemetry-outage": return cmd_telemetry_outage(port) + if args.cmd == "trace-chain": + return cmd_trace_chain(port) if args.cmd == "stand-from-scratch": return cmd_stand_from_scratch(args.project, args.runs) if args.cmd == "stop-at-start": diff --git a/.env.example b/.env.example index 7ac9e90..5cde228 100644 --- a/.env.example +++ b/.env.example @@ -24,12 +24,12 @@ # С lab6 — имена OTEL_* skeleton настройками не являются, SDK их не читает # (процесс с включённой телеметрией удаляет их из окружения и пишет warning): # OTEL_SERVICE_NAME — константа точки входа (messenger-api, -# messenger-worker); OTEL_EXPORTER_OTLP_ENDPOINT — [telemetry] otlp_endpoint, -# в compose — TELEMETRY__OTLP_ENDPOINT у api и worker; +# messenger-worker, messenger-relay); OTEL_EXPORTER_OTLP_ENDPOINT — [telemetry] +# otlp_endpoint, в compose — TELEMETRY__OTLP_ENDPOINT у api, worker и relay; # OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf — постоянно (установлен только # экспортёр OTLP/HTTP protobuf); OTEL_RESOURCE_ATTRIBUTES — [telemetry] # environment (deployment.environment.name), service.* вычисляет код. -# Включает телеметрию compose (TELEMETRY__ENABLED у api и worker), в .env её +# Включает телеметрию compose (TELEMETRY__ENABLED у api, worker и relay), в .env её # нет: консоль — без телеметрии. # порт сервиса ([app] port): на нём слушает приложение, его же diff --git a/AGENTS.md b/AGENTS.md index 1e91f22..4ded1b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,19 @@ contrib, Prometheus, Loki, Tempo и Grafana в compose (`infra/otel/`, сеть `telemetry`, наружу — только Grafana на `127.0.0.1:GRAFANA_OUT_PORT`), сигналы уровня 3, healthcheck брокера от его пользователя (стенд с нуля одной командой), команды драйвера `telemetry-check`, `telemetry-outage`, -`stand-from-scratch` (правило `telemetry.md`). Код перенесён из лабы 5 (репозиторий +`stand-from-scratch` (правило `telemetry.md`). Второе изменение лабы, первая +часть уровня 4 — change `job-trace-propagation` (активный, +`openspec/changes/job-trace-propagation/`, capability `observability`): +контекст W3C загрузки в `attachment_jobs.traceparent` / `tracestate` +(ревизия `e4b8c2d17f90`), SDK в relay (`messenger-relay`), span producer +relay и consumer span worker (parent и link) — одна трасса на загрузку, с +повторами и replay; заголовки AMQP — carrier, тело сообщения прежнее; +`ParentBased(ALWAYS_ON)`; ленивый импорт SDK; метрики уровня 4 — время до +`ready`, очередь и возраст (снимок relay), пул `db.client.connection.*` +(`CountingQueuePool`), насыщение worker, CPU и память контейнеров из cgroup +(без `docker.sock`); панели уровня 4 в том же dashboard; команда драйвера +`trace-chain`. Следующий — `slo-alerts` (SLO, alerts, runbooks, инциденты). +Код перенесён из лабы 5 (репозиторий `mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit `046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5 остались в её репозитории. Дальше — что досталось от лабы 5: брокер @@ -105,7 +117,8 @@ 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` лабы 6 — в `openspec/changes/archive/`, активных нет (новые +`otel-telemetry` лабы 6 — в `openspec/changes/archive/`, активный — +`job-trace-propagation` (новые capability: с `s3-storage` — `object-storage`, с `attachments` — `attachments`, с `upload-consistency` — `storage-consistency`, с `async-attachments` — @@ -517,7 +530,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `driver.py --port worker-memory` | память контейнера worker (~35 с): на девять случаев в пределах контракта два одинаковых файла разом, новая cgroup на случай; `memory.peak`, `VmHWM`, `render_peak`, OOM, сумма пиков меньше 1 ГБ; worker и relay запускаются при любом исходе; `evidence/worker/memory.md` | | `driver.py freeze-sessions [--rounds 6] [--settle 15]` | сессии PostgreSQL и журнал пула после заморозки (~2,5 мин), работает и на рабочем стенде: приложение в процессе одноразового контейнера `api`, PostgreSQL только через TCP-прокси пробы, заморожен прокси, а не сервер; режимы — между блоками и до запросов при пуле 2 и 4; `evidence/storage/freeze-sessions.md` | | `driver.py --port telemetry-check` | телеметрия рабочего стенда через HTTP API Grafana с паролем из `.env` (~2 мин, change `otel-telemetry`): вход, порт, источники, dashboard provisioned и неизменяем, цели Prometheus; свой запрос → stdout → Loki → Tempo, traceparent, нестандартный метод, 401, 404; загрузка → трасса worker, недекодируемый JPEG → `failed`; рост счётчиков по репликам и исходам; S3 заморожен → span S3 с ошибкой (`unpause` в `finally`); сети хранилищ из api и worker, разовый контейнер с `OTEL_*`, проба приватности, рестарт Collector и хранилищ; `evidence/telemetry/check.md` | -| `driver.py --port telemetry-outage` | Collector `stop` и `pause` (~2,5 мин): `make test`, загрузка до `ready`, записи SDK в stdout, `docker stop` реплики и worker быстрее 10 с с кодом 0; все сервисы телеметрии остановлены — рестарт api и worker, `make test`; сигналы снова приходят; стенд возвращается в `finally`; `evidence/telemetry/collector-outage.md` | +| `driver.py --port telemetry-outage` | Collector `stop` и `pause` (~3 мин): `make test`, загрузка до `ready`, записи SDK в stdout, relay без перезапусков, `docker stop` реплики, worker и relay быстрее 10 с с кодом 0; все сервисы телеметрии остановлены — рестарт api, worker и relay, `make test`; сигналы (и span producer relay) снова приходят; стенд возвращается в `finally`; `evidence/telemetry/collector-outage.md` | +| `driver.py --port trace-chain` | сквозная трасса и сигналы уровня 4 на рабочем стенде (~5 мин, change `job-trace-propagation`), через HTTP API Grafana: очередь и её возраст при остановленном worker и спад до 0; загрузка с повтором при замороженном S3 — одна трасса: server span API, два span producer relay, два consumer span worker (parent и link, span S3 с ошибкой, запись оригинала и вариантов); replay в той же трассе; задание без контекста (`UPDATE` колонок своей строки) — корень worker; время до `ready`, пулы, ёмкость worker, пределы контейнеров = `docker inspect`, нет сокета Docker, панели уровня 4 с данными; `unpause s3`, worker и relay — в `finally`; `evidence/telemetry/trace-chain.md` | | `driver.py stand-from-scratch [--runs 2]` | `make run_docker` на пустых volumes своим проектом `mtusi-lab6-scratch` (рабочий — код 2) на свободных портах (~1 мин на прогон): код 0, состояния, `RestartCount` брокера и телеметрии 0, нет `eacces`, provisioning, `make test`; проект удаляется с volumes при любом исходе, ID контейнеров рабочего стенда прежние; `evidence/stand/from-scratch.md` | | `driver.py freeze-lb [--rounds 3]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME`, по умолчанию `mtusi-lab6-freeze`; `mtusi-lab6` — код 2): сама поднимает стенд с данными в tmpfs (volumes нет) на образе `mtusi-messenger:lab6` и убирает его при любом исходе; `docker pause` PostgreSQL, шесть запросов через LB — 503 за ~8 с, 504 нет, `unpause` в `finally`, сессий не больше пулов (~1,5 мин); раздел `evidence/storage/freeze-sessions.md` | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | @@ -566,10 +580,10 @@ src/ __main__.py # python -m src: early_stop.install() до импорта приложения → main.main() main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run worker/__main__.py # python -m src.worker: early_stop.install("worker") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце - worker/main.py # worker обработки вложений: свои engine, S3 и потребитель; цикл соединений с паузой, задачи доставок (prefetch) под семафором concurrency, сервис и SqlAlchemyUnitOfWork на доставку, ack / requeue / drop по итогу, SIGTERM — начатые ждут в срок, закрытие клиентов одним gather; с лабы 6 — телеметрия messenger-worker, consumer span и histogram по исходу доставки (JobDeliveryOutcome, error — на исключении) после места конкуренции, закрытие SDK в окне gather + worker/main.py # worker обработки вложений: свои engine, S3 и потребитель; цикл соединений с паузой, задачи доставок (prefetch) под семафором concurrency, сервис и SqlAlchemyUnitOfWork на доставку, ack / requeue / drop по итогу, SIGTERM — начатые ждут в срок, закрытие клиентов одним gather; с лабы 6 — телеметрия messenger-worker, consumer span и histogram по исходу доставки (JobDeliveryOutcome, error — на исключении) после места конкуренции, закрытие SDK в окне gather; с change job-trace-propagation — consumer span дочерний к delivery.trace_context с link, итог handle — JobDeliveryResultDTO (атрибуты попытки и причины, messenger.job.time_to_ready), счётчики WorkerLoad «ждут места» и «заняты» вокруг семафора и observe_worker worker/render.py # процесс обработки: python -m src.worker.render, лимиты первыми строками (RLIMIT_AS, RLIMIT_CPU, RLIMIT_CORE), затем Pillow; stdin — байты, stdout — строка JSON и варианты, коды 0/3/4/5 relay/__main__.py # python -m src.relay: early_stop.install("relay") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце - relay/main.py # relay: свои engine, SqlAlchemyUnitOfWork и издатель, цикл проходов с паузами, отказ брокера и PostgreSQL не роняет, SIGTERM — текущий шаг и выход 0; replay — разовая команда реестра, коды 0/3/1/2 + relay/main.py # relay: свои engine, SqlAlchemyUnitOfWork и издатель, цикл проходов с паузами, отказ брокера и PostgreSQL не роняет, SIGTERM — текущий шаг и выход 0; replay — разовая команда реестра, коды 0/3/1/2 (без SDK); с change job-trace-propagation — телеметрия messenger-relay после disarm, instrument_engine, QueueSnapshots и observe_queue (снимок после успешного прохода не чаще 5 с, отказ PostgreSQL — пропуск), закрытие SDK в окне gather 0,5 с cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2 cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine, SqlAlchemyUnitOfWork на сервис и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R] — разовая сверка, коды 0/3/1/2; плановая — batch, поверхностная, предел скорости из настроек config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), max_unfinished_jobs 250 (предел незавершённых заданий стенда; 0 — без него), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100, max_objects_per_second 2000 (предел скорости сверки; 0 — без него) @@ -577,7 +591,7 @@ src/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse schemas/.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста - dependencies.py # get_uow (SqlAlchemyUnitOfWork на запрос), request_deadline (общий срок JSON-запроса), фабрики сервисов на UowDep (с кэшем; вложения — ещё S3 и места), разбор Basic, текущая сессия по Bearer, пагинация + dependencies.py # get_uow (SqlAlchemyUnitOfWork на запрос), request_deadline (общий срок JSON-запроса), фабрики сервисов на UowDep (с кэшем; вложения — ещё S3 и места), разбор Basic, текущая сессия по Bearer, пагинация; TraceContextDep — контекст W3C server span для задания загрузки (change job-trace-propagation) errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; RETRY_AFTER — Retry-After у 429 занятых мест загрузки и предела заданий (UploadBacklogFull, 5 с); у 500 — X-Request-Id и X-Instance-Id middlewares/ # X-Request-Id, X-Instance-Id и access-лог; с лабы 6 — server span и histogram http.server.request.duration (не для health), итоговая запись внутри span core/ @@ -586,7 +600,7 @@ src/ repos/.py # SqlAlchemyRepository: одна атомарная операция на метод; chat_cache и attachment_object — модульные функции над клиентом repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO - repos/attachment_job.py # задание вложения: вставка, lock_job FOR UPDATE, start_attempt, return_to_queued своей попытки, finish_job; count_unfinished (предел принятой работы: сумма трёх count с LIMIT по частичным индексам); relay — lock_due_jobs (SKIP LOCKED, порядок срока), count_published, mark_published пакета, recover_expired_leases, has_published_before, reset_published_before; replay_job, list_failed + repos/attachment_job.py # задание вложения: вставка, lock_job FOR UPDATE, start_attempt, return_to_queued своей попытки, finish_job; count_unfinished (предел принятой работы: сумма трёх count с LIMIT по частичным индексам); relay — lock_due_jobs (SKIP LOCKED, порядок срока), count_published, mark_published пакета, recover_expired_leases, has_published_before, reset_published_before; replay_job, list_failed; с change job-trace-propagation — колонки traceparent и tracestate во вставке и выборках, queue_snapshot (стадии scheduled / outbox / published / processing и LEAST трёх min(created_at) одним выражением по частичным индексам) repos/attachment_job_replay.py # журнал replay: вставка записи аудита, чтение по заданию repos/attachment_variant.py # варианты: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один по имени repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_queued (pending и непомеченная → queued RETURNING), mark_processing, return_to_queued, return_group_to_queued, replay_failed, lock_attachment (FOR NO KEY UPDATE), commit_ready, commit_failed, чтение одной и до 10; очистке staging — get_staging_candidates, lock_staging_candidate, clear_staging_key; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at) @@ -594,8 +608,8 @@ src/ repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service(uow, …): логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем, require_member внутри чужого блока; отправка — ключ, сообщение и связи с вложениями одним блоком services/attachment.py # AttachmentService(uow, cache, storage, slots): загрузка (проверки в первом блоке и там же предел заданий count_unfinished, 429 UploadBacklogFull → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT в staging тем же BytesIO → queued и задание, ответ 202; сбой до COMMIT или пропавшая строка — удаление объекта и 503; брокера в пути нет; место — до ответа), метаданные с вариантами, отдача потоком - services/attachment_processing.py # AttachmentProcessingService(uow, storage, renderer, stop): разбор сообщения, claim с арендой и бюджетом, GET staging и сверка, PUT оригинала, варианты через ImageRenderer, PUT вариантов, фиксация ready с fencing одной транзакцией; временные ошибки — queued со сроком (retry_delay, jitter) и ACK, постоянные — failed; JobOutcome - services/attachment_relay.py # AttachmentRelayService(uow, publisher): проход — истёкшие аренды, потерянные сообщения, публикация с подтверждением и отметка пакета внутри транзакции SKIP LOCKED, предел опубликованных; RelayPassDTO + services/attachment_processing.py # AttachmentProcessingService(uow, storage, renderer, stop): разбор сообщения, claim с арендой и бюджетом, GET staging и сверка, PUT оригинала, варианты через ImageRenderer, PUT вариантов, фиксация ready с fencing одной транзакцией; временные ошибки — queued со сроком (retry_delay, jitter) и ACK, постоянные — failed; JobOutcome; итог handle — JobDeliveryResultDTO (исход, попытка, причина, код, время до ready без replay) + services/attachment_relay.py # AttachmentRelayService(uow, publisher): проход — истёкшие аренды, потерянные сообщения, публикация с подтверждением и отметка пакета внутри транзакции SKIP LOCKED, предел опубликованных; RelayPassDTO; элементы JobPublicationDTO (publication: попытка, replay, причина, контекст задания), queue_snapshot — один блок services/attachment_replay.py # AttachmentReplayService(uow): реестр failed, replay одной транзакцией с аудитом и новым бюджетом, отказы not_found / already_ready / not_failed / source_gone; ReplayPassDTO services/attachment_cleanup.py # AttachmentCleanupService(uow, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO; clean_staging — очистка staging ready и failed по сроку под FOR NO KEY UPDATE SKIP LOCKED, StagingCleanupPassDTO services/attachment_reconcile.py # AttachmentReconcileService(uow, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD; строка с ключом /original другого вложения — HEAD её объекта, verify W2), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → объекты staging без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change pipeline-reliability: шаг _list_staging, orphan_staging, listed_staging. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с; сигнал прекращает паузу, останавливает следующий check_stop — verify W1), ранний отказ по пределу (unchecked), счёт сеансов — uow.blocks_opened, стоимость в итоге (storage_objects, s3_requests, read_bytes, db_sessions, phase_ms) @@ -603,12 +617,12 @@ src/ infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи; с лабы 6 — хуки телеметрии (export_to_telemetry, add_trace_fields: trace_id и span_id активного span) в обеих цепочках и RateLimitFilter записей opentelemetry.* (одна в минуту на логгер); SDK не импортирует - telemetry/ # change otel-telemetry (telemetry.md): core.py — start (провайдеры только из [telemetry], ресурс из четырёх атрибутов, ALWAYS_ON, cumulative, View границ, без exemplars и atexit), remove_otel_environment, begin_shutdown / wait_closed / shutdown (daemon-потоки и срок), child_span (правило корня, ошибка — класс без текста), server_span / finish_request (span SERVER и histogram http.server.request.duration), consumer_span / JobObservation (span CONSUMER и messenger.job.duration по исходу), Exporters (in-memory для тестов); db.py — instrument_engine (слушатели before/after_cursor_execute, handle_error), commit_span; logs.py — экспорт записи structlog в логгер SDK и trace_ids, install_log_hooks; setup.py — start_process_telemetry(): OTEL_* с warning, провайдеры, хуки + telemetry/ # change otel-telemetry и job-trace-propagation (telemetry.md): core.py — только opentelemetry-api: start (SDK загружает модуль sdk.py, ресурс из четырёх атрибутов), remove_otel_environment, begin_shutdown / wait_closed / shutdown (daemon-потоки и срок), child_span (правило корня, ошибка — класс без текста), server_span / finish_request (span SERVER и histogram http.server.request.duration), PROPAGATOR (W3C без baggage), current_trace_context, remote_context, Exporters (in-memory для тестов); sdk.py — единственный импорт SDK, экспортёра и requests: провайдеры только из [telemetry], ParentBased(ALWAYS_ON), cumulative, View границ трёх histogram, без exemplars и atexit, otlp_exporters; messaging.py — producer_span (PRODUCER publish <очередь> под сохранённым контекстом, заголовки), consumer_span (CONSUMER дочерний к контексту сообщения с link, без него — корень) и JobObservation (итог доставки: атрибуты, messenger.job.duration и time_to_ready); metrics.py — observe_pool (db.client.connection.* по текущему пулу engine), WorkerLoad / observe_worker, observe_queue (gauge по последнему снимку, старше 30 с — ничего); container.py — cgroup v2 (cpu.stat, memory.current, cpu.max, memory.max); db.py — instrument_engine (слушатели before/after_cursor_execute, handle_error, метрики пула), commit_span; logs.py — экспорт записи structlog в логгер SDK и trace_ids, install_log_hooks; setup.py — start_process_telemetry(, cgroup_root=…): OTEL_* с warning, провайдеры, метрики контейнера (нет cgroup — одна запись), хуки password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username - broker/client.py # aio-pika: JobPublisher relay (соединение лениво, publish_many с confirm и общим сроком, ready_messages, сброс после любой ошибки), JobConsumer worker (своё соединение, prefetch), JobDelivery, queue_name <база>.attachment.process.v1 + broker/client.py # aio-pika: JobPublisher relay (соединение лениво, publish_many с confirm и общим сроком, ready_messages, сброс после любой ошибки), JobConsumer worker (своё соединение, prefetch), JobDelivery, queue_name <база>.attachment.process.v1; с change job-trace-propagation — span producer и заголовки traceparent / tracestate в _publish_one, JobDelivery.trace_context из заголовков (trace_context_from_headers) render/client.py # ImageRenderer: процесс обработки на задание, окружение без секретов, срок и kill в finally, разбор вывода, коды в ImageRejected / RenderInterrupted; span render attachment variants (размер входа, исход, код выхода, пик) upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py - db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping; _ping_once — проверка соединения при выдаче одним обменом + db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping; _ping_once — проверка соединения при выдаче одним обменом; CountingQueuePool (poolclass engine, change job-trace-propagation): connect() со счётом ожидающих и отказов по сроку, pending(), timeouts() db/session.py # глобалы engine и session_factory процесса API db/scope.py # session_scope(factory, timeout_seconds): сессия на блок, срок вместе с откатом, отмена и отказ БД → invalidate, warning, ServiceUnavailable; deadline_scope — общий срок JSON-запроса без сессии, внутри него таймер блока той же задачи не взводится db/uow.py # SqlAlchemyUnitOfWork(factory, timeout_seconds) поверх session_scope, repo на блок; импортируют только точки входа; span COMMIT в _commit @@ -650,8 +664,8 @@ service-tests/ # быстрые тесты сервисов (вн builders.py # DTO для тестов: явное время, PASSWORD_HASH по виду CHECK repo_contract.py # один набор условий repo: на фейке и на настоящем SQL fakes/ # FakeDatabase (таблицы, снимок, events, held, fail_on), FakeUnitOfWork на базовом классе порта, фейки девяти repo, FakeCache, FakeObjectStorage, FakeJobPublisher, FakeImageRenderer - unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_ на каждый сервис, test_worker_deliveries (одновременные доставки), test_telemetry (in-memory экспортёры SDK: выключено, OTEL_*, ресурс, middleware, журнал, правило корня, Valkey и S3, закрытие со сроком, исход доставки); conftest подставляет поля settings - db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow, test_telemetry_db (span запросов и COMMIT под родителем, без родителя — ни одного) + unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_ на каждый сервис, test_worker_deliveries (одновременные доставки), test_telemetry (in-memory экспортёры SDK: выключено, OTEL_*, ресурс, middleware, журнал, правило корня, Valkey и S3, закрытие со сроком, исход доставки; с change job-trace-propagation — контекст загрузки, span producer и consumer, невыбранный контекст, время до готовности, пул, насыщение, очередь, cgroup, ресурс relay, заголовки доставки, модули SDK без телеметрии в отдельном интерпретаторе); conftest подставляет поля settings + db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow, test_telemetry_db (span запросов и COMMIT под родителем, без родителя — ни одного), test_pool_counts (CountingQueuePool: ожидающий и отказ по сроку, класс после dispose) bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3) run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel; профиль reconcile (S3 с портом метрик через .work/s3-metrics.compose.yml, наполнение \copy и загрузчиком, разовые проходы mtusi-bench-reconcile- с лимитом CPU варианта, «до» — .work/cleaner-before.compose.yml, метрики шлюза и pg_stat_database до и после, блок H4 с k6 background.js, отказ по пределу S4) scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest @@ -672,7 +686,7 @@ bench/ # нагрузочный стенд на HAProxy + k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка), background (профили reconcile и queue: constant-arrival-rate скачиваний, записи и чтения истории, строка bg на запрос, остановка SIGINT), queue (окна constant-arrival-rate загрузок, VU заранее, ответ не повторяется, строка q на загрузку; WARM — разогрев) и queue_sweep (метаданные каждого принятого вложения, SHA-256 выборки, строки qs и qv); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1 -migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout); c7e2f1a04b56 — attempt_base и attachment_job_replays; d3f9a6b2c1e7 — индексы outbox, аренды и очистки staging CONCURRENTLY +migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout); c7e2f1a04b56 — attempt_base и attachment_job_replays; d3f9a6b2c1e7 — индексы outbox, аренды и очистки staging CONCURRENTLY; e4b8c2d17f90 — attachment_jobs.traceparent и tracestate (NULL, CHECK NOT VALID, SET LOCAL lock_timeout) infra/ # конфигурации сервисов стенда; README.md — skeleton valkey/valkey.conf # лимит памяти и LRU, persistence выключен rabbitmq/rabbitmq.conf # предел памяти брокера 400 МиБ: лимит контейнера он не видит @@ -680,7 +694,7 @@ infra/ # конфигурации сервисов сте otel/prometheus/prometheus.yml # scrape Collector (honor_labels), Collector, Loki, Tempo и себя раз в 15 с; срок и объём — флаги compose otel/loki/loki.yaml # монолит filesystem, schema v13, compactor, срок 168h, без отчётов otel/tempo/tempo.yaml # монолит 3.1, OTLP HTTP :4318, local, block_retention 168h у scheduler и worker, без отчётов - otel/grafana/ # datasources.yaml (uid prometheus, loki, tempo; лог ↔ трасса), dashboards.yaml (папка Messenger, без правок из UI), dashboards/messenger-overview.json (панели уровня 3) + otel/grafana/ # datasources.yaml (uid prometheus, loki, tempo; лог ↔ трасса), dashboards.yaml (папка Messenger, без правок из UI), dashboards/messenger-overview.json (панели уровня 3; с change job-trace-propagation — p99 и строки «Pipeline» и «Saturation» уровня 4) rollback/broker.compose.yml # override отката реплик на образ до pipeline-reliability (прежний код публикует сам): адрес и пароль брокера только на время отката s3/bootstrap.sh # bootstrap S3 (ещё пользователь worker: чтение и запись объектов; сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects (у уборщика — ещё список только с префиксом S3_CLEANER_LIST_PREFIX = <база>/attachments/), пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта (400, 502, 503, 504), timeout server 30 с пути загрузки (set-timeout, остальные 10 с), tune.sndbuf.server 256 KiB и tune.rcvbuf.client 128 KiB, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) @@ -697,7 +711,7 @@ evidence/attachments/ # change async-attachments: defense.md (driver.py d evidence/s3/ # privacy.md — make s3_check на текущем коде; change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT); change upload-consistency: cleaner-key.md (пользователь уборщика в bootstrap, смена секрета, make s3_check с ключом уборщика, секреты по сервисам); change track2-reconciler: cleaner-list.md (bootstrap с политикой списка по префиксу, неверный префикс, make s3_check со строками списка уборщика, окружение s3-bootstrap) evidence/reconcile/ # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0; с change track2-reconcile-cost — остановка во время паузы предела скорости, driver.py reconcile-signal --pace) evidence/reconcile/<метка>/ # результаты make bench_reconcile (change track2-reconcile-cost): meta.json (раздел reconcile: план, этапы и модели, commit и образы «до», аргументы S3), passes.csv, windows.csv, summary.md (H1–H4 и S4), cost-by-n.svg, requests-by-n.svg, background-p95.svg, raw/ (записи уборщика по проходам, итог k6 блока H4) -evidence/telemetry/ # change otel-telemetry: check.md (driver.py telemetry-check), collector-outage.md (driver.py telemetry-outage), budget.md (пики и лимиты сервисов телеметрии, реплик и worker с телеметрией и без) +evidence/telemetry/ # change otel-telemetry: check.md (driver.py telemetry-check), collector-outage.md (driver.py telemetry-outage), budget.md (пики и лимиты сервисов телеметрии, реплик и worker с телеметрией и без); change job-trace-propagation (снимаются после коммита кода): trace-chain.md (driver.py trace-chain), queue-snapshot.md (EXPLAIN снимка очереди), раздел change в budget.md (relay с SDK, уборщик после ленивого импорта); evidence/migrations/job-trace-context.md — ревизия e4b8c2d17f90 evidence/stand/ # change otel-telemetry: from-scratch.md (driver.py stand-from-scratch --runs 2) evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга; freeze-sessions.md — change unit-of-work: сессии и журнал пула после заморозки PostgreSQL (driver.py freeze-sessions и freeze-lb) evidence/migrations/ # миграции с нуля и повторно, ошибка миграции; лаба 4: pending-index.md (ревизия 739b8f04d5fb с нуля, повтор, откат, EXPLAIN общего плана кандидатов уборщика на рабочей базе с откатом, rollout_quick), lost-at.md (ревизия 5c3e1f0a9b7d колонки lost_at: с нуля, повтор, откат, --sql с lock_timeout, make rolling_update с ревизией до и после) diff --git a/PLAN.md b/PLAN.md index bf01caf..d9c3fe8 100644 --- a/PLAN.md +++ b/PLAN.md @@ -18,7 +18,7 @@ | 2 | Хранилища | **принято 2026-11-11:** Prometheus (метрики), Loki (логи), Tempo (трассы), отдельными сервисами | все три принимают OTLP, у каждого понятная роль и свой volume; `grafana/otel-lgtm` одним контейнером прячет Collector и хранилища, а рубрика требует отдельный Collector и объяснить каждое хранилище | | 3 | Уровень 4 — один change или два | **принято 2026-11-11:** два — связь и насыщение, затем SLO, alerts и устойчивость | verify каждого уже; второй опирается на метрики первого. Цена — ещё один цикл из четырёх стадий | | 4 | Что можно без пользователя | **принято 2026-11-11:** как в лабе 5: коммиты на `feat/`, ff-merge в `solution/bvt2301-safronov`, архивация, зависимости и образы, стенд и замеры; push — в конце; PR не открывать | без разрешения на коммиты цикл идёт без них (скилл `openspec-cycle`) | -| 5 | Длинные замеры исключений (`bench_uploads` ~50 мин, `bench_queue` ~2 ч 10 мин) | **принято 2026-11-11:** в последнем шаге, на коде лабы 6 с телеметрией | доказывают, что свойства лаб 4 и 5 сохранились вместе с телеметрией; снятые раньше пришлось бы снимать заново | +| 5 | Длинные замеры исключений (`bench_uploads` ~50 мин, `bench_queue` ~2 ч 10 мин) | **принято 2026-11-11:** в последнем шаге, на коде лабы 6 с **включённой** телеметрией на стенде `mtusi-bench` (уточнено 2026-11-11, вопрос 5 `## otel-telemetry`) | доказывают, что свойства лаб 4 и 5 сохранились вместе с телеметрией; снятые раньше пришлось бы снимать заново. Выключатель телеметрии `bench/` — из change 4 | ## Шаг 0. Перенос (без OpenSpec) @@ -185,7 +185,9 @@ RAM API, worker, Collector и хранилищ, объём ingest (метрик хранилищ), потери spans. Редкие ошибки и медленные запросы вносятся с известным числом — по ним видно, что теряет каждый вариант. Гипотезы закоммичены до метки, повторы, A/A, сбалансированная конфигурация предложена и проверена, ограничения -названы (`bench.md`). +названы (`bench.md`). Включение телеметрии на стенде `mtusi-bench` (SDK, Collector, +хранилища) делается не только для профиля `telemetry`: им пользуются `bench_uploads` +и `bench_queue` последнего шага (решение 5), бюджет ВМ — с ним. Трек 2 «SLO и обнаружение инцидентов» не выбран (решение 1): burn-rate alerts с несколькими окнами в changes не входят, alerts уровня 4 — пороговые @@ -198,7 +200,8 @@ RAM API, worker, Collector и хранилищ, объём ingest (метрик --require-test-keys`, `auth-storage`, `make test-persistence`, повтор после `--force-recreate api`, `attachment-failover` оба режима, `attachment-storage`, `broker-check` и `--require-test-queue`, `make bench_uploads`, `make - bench_queue`) и новые исключения changes лабы 6. Метка очереди: исключение + bench_queue` — оба с включённой телеметрией, решение 5) и новые исключения + changes лабы 6. Метка очереди: исключение называет `baseline4` — новая метка с тем же именем или правка текста исключения на новую (решить там, назвать в `QUESTIONS.md`). - Полные `make failure_checks`, `make test_isolated`, `make student_test` через diff --git a/QUESTIONS.md b/QUESTIONS.md index 4073115..26ed59d 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -17,6 +17,14 @@ fork. PR не открывать. Разрешения — `.claude/settings.local.json`. - Длинные замеры исключений (`make bench_uploads`, `make bench_queue`) — в последнем шаге, на коде лабы 6 с телеметрией. +- Ответ на вопрос 5 `## otel-telemetry` (2026-11-11): эти замеры — с + **включённой** телеметрией (SDK в реплике, worker и relay, Collector и + хранилища на стенде `mtusi-bench`), как на рабочем стенде. Мерит по-прежнему + внешний прибор (k6, сэмплер cgroup), телеметрия — часть измеряемой системы. + Выключатель в `bench/` делает `track1-telemetry-cost`: он годится и для + профилей `uploads` и `queue`. Вариант «до» `bench_uploads` (образ + `9cc6c0c` без SDK) — смешанное сравнение, назвать в сводке; сумму лимитов + `bench_queue` с телеметрией проверить до прогона. ## Перенос из лабы 5 @@ -157,7 +165,7 @@ Change `openspec/changes/archive/2026-11-11-otel-telemetry/` (propose и арх (design, решение 9). 4. Преподавателю: ответы, которые генерирует HAProxy (502, 503, 504), в метрики API не попадают, метрик HAProxy на уровне 3 нет. Для SLO уровня 4 это решает change `slo-alerts`. -5. Пользователю: метки последнего шага (`make bench_uploads`, `make bench_queue`) по методике `bench/` снимаются с +5. **Отвечено 2026-11-11: с включённой телеметрией** («Ответы пользователя перед прогоном»). Пользователю: метки последнего шага (`make bench_uploads`, `make bench_queue`) по методике `bench/` снимаются с выключенным SDK: «код лабы 6 с телеметрией» — код есть, телеметрия выключена. Если нужны метки с включённой телеметрией — это профиль трека 1 (change `track1-telemetry-cost`) и другая методика. 6. Преподавателю (apply): сценарий `observability` «Необычный метод и неизвестный путь» назван методом `BREW`, а его @@ -225,6 +233,11 @@ Change `openspec/changes/job-trace-propagation/` (propose 2026-11-11). Номе - Новых параметров `[telemetry]` нет: интервал и срок свежести снимка очереди, границы времени до готовности — константы. - Dashboard уровня 4 — тот же `messenger-overview.json` (без нового bind mount и `configs` CI) (14); проверка — одна команда драйвера `trace-chain` (16). +- Apply (design, «Уточнения apply»): redis-py 8.1 сам грузит модули метрик SDK — тест ленивого импорта сравнивает с `import + redis.asyncio` (п. 1); запись о недоступных метриках контейнера — только stdout (п. 3); раскладка модулей пакета (п. 4); + поля итога у `skipped` и `requeued` (п. 5); снимок после полного пакета (п. 6); Tempo собирает трассу повтора и replay — решение + 2 прежнее (п. 7); `trace-chain` складывает счётчики двух процессов worker и запускает их `docker start` (п. 8); relay в + `telemetry-outage` (п. 9); память уборщика (п. 10); логгер пула на WARNING (п. 11); бюджет relay без изменения лимита (п. 12). ### Вопросы @@ -239,3 +252,12 @@ Change `openspec/changes/job-trace-propagation/` (propose 2026-11-11). Номе 3. Преподавателю: «Queue depth» — логическая очередь заданий по стадиям из PostgreSQL (outbox, отложенные повторы, в брокере, в обработке), а не счётчик очереди RabbitMQ: очередь брокера — стадия `published`. Достаточно ли? Иначе — плагин `rabbitmq_prometheus` и доступ к брокеру из сети телеметрии (решение 9). +4. Пользователю (apply): сценарий `observability` «Модули SDK без телеметрии не загружаются» буквально не выполним, пока + установлен SDK: redis-py 8.1 при импорте сам грузит `opentelemetry.sdk.metrics` (35 модулей). Экспортёра, провайдеров + трасс и логов, protobuf и `requests` нет; экономия ленивого импорта — ~6,5 МиБ и ~200 модулей. Принять как есть (тест + сравнивает с `import redis.asyncio`) или уточнить сценарий в archive («кроме модулей, которые загружают сторонние + библиотеки»)? Ответ меняет только формулировку сценария и докстринг теста (design, «Уточнения apply», п. 1). +5. Пользователю (apply): `memory.peak` уборщика на рабочем стенде — 176 МиБ при лимите 256 (плановая сверка при старте); + правило «лимит ≥ 1,5 × пика» для него не выполнено (264). Поднять лимит до 288 МиБ (сумма стенда +32 МиБ, до ВМ остаётся + 222 МиБ) или оставить: пик — сверка, а не этот change? Ответ — правка `docker-compose.yml`, `docker.md` и `REPORT.md` + (design, «Уточнения apply», п. 10). diff --git a/REPORT.md b/REPORT.md index f36818d..ebe0e5a 100644 --- a/REPORT.md +++ b/REPORT.md @@ -67,22 +67,23 @@ scratch.md` ещё снят на рабочем дереве поверх `9b35c | Атрибут ресурса | Значение | Prometheus | Loki | | --- | --- | --- | --- | -| `service.name` | `messenger-api` / `messenger-worker` (константы точки входа) | `job` | метка `service_name` | +| `service.name` | `messenger-api` / `messenger-worker` / `messenger-relay` (константы точки входа) | `job` | метка `service_name` | | `service.instance.id` | `[app] instance_id` = `X-Instance-Id` (короткий id контейнера) | `instance` | метка `service_instance_id` | | `service.version` | `1.6.0` — `info.version` контракта (9) | `target_info{service_version}` | `service_version` | | `deployment.environment.name` | `[telemetry] environment` = `lab` | `target_info{deployment_environment_name}` | метка `deployment_environment_name` | | Имя skeleton | У нас (8) | | --- | --- | -| `OTEL_SERVICE_NAME` | константа точки входа: `messenger-api`, `messenger-worker` | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | `[telemetry] otlp_endpoint`; на стенде — `TELEMETRY__OTLP_ENDPOINT=http://otel-collector:4318` у `api` и `worker` | +| `OTEL_SERVICE_NAME` | константа точки входа: `messenger-api`, `messenger-worker`, `messenger-relay` | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | `[telemetry] otlp_endpoint`; на стенде — `TELEMETRY__OTLP_ENDPOINT=http://otel-collector:4318` у `api`, `worker` и `relay` | | `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` | постоянно: установлен только экспортёр OTLP/HTTP protobuf | | `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=lab` | `[telemetry] environment`; `service.*` вычисляет код | Переменные `OTEL_*` настройками не являются: процесс с включённой телеметрией удаляет их из окружения и пишет `warning` с именами (проверка — разовый контейнер с `OTEL_SDK_DISABLED=true` и -чужим адресом в `evidence/telemetry/check.md`). Включает телеметрию `TELEMETRY__ENABLED` у `api` -и `worker` стенда; консоль, `make test_isolated`, стенд отказов и `bench/` — без неё (20). +чужим адресом в `evidence/telemetry/check.md`). Включает телеметрию `TELEMETRY__ENABLED` у `api`, +`worker` и (change `job-trace-propagation`) `relay` стенда; консоль, `make test_isolated`, стенд +отказов и `bench/` — без неё (20). ### Инфраструктура наблюдаемости @@ -126,12 +127,147 @@ Tempo 253, Grafana 248 МиБ, правило выполнено и для на отклоняется до приложения 400 текстом — ни span, ни ряда (`KNOWN_ISSUES.md`). - **OTLP без аутентификации и TLS** — до лабы 7: Collector принимает от любого контейнера сети `default`; хранилища отделены сетью. -- Trace-id клиента не продолжается (публичная точка входа); перенос контекста через брокер, relay - с SDK, метрики пула, очереди и насыщения — следующие changes уровня 4. +- Trace-id клиента не продолжается (публичная точка входа); контекст внутри стенда переносит + задание (раздел «Сквозная трасса загрузки» ниже). - `service.version` не различает сборки одной версии контракта. - Tempo 3.1 в простое пишет `level=error` «no jobs found» (backend-worker опрашивает scheduler без заданий) — шум журнала, не отказ. +### Сквозная трасса загрузки (уровень 4) + +Change `job-trace-propagation` (design — `openspec/changes/job-trace-propagation/design.md`, +номера решений «JTP-n»). Одна загрузка — одна трасса: server span `POST +/api/v1/chats/{chat_id}/attachments` (`messenger-api`) → на каждую публикацию её задания span +`PRODUCER` `publish <очередь>` (`messenger-relay`) → под ним span `CONSUMER` `process <очередь>` +этой доставки (`messenger-worker`) с дочерними PostgreSQL, S3 (`S3.GetObject` staging, +`S3.PutObject` оригинала и трёх вариантов), `render attachment variants` и `COMMIT`. Повторная +попытка, повторная доставка брокером и replay — новые пары producer / consumer в той же трассе +с `messenger.job.attempt`, `messenger.job.retry_reason`, `messenger.job.replayed`, +`messenger.job.reason`, `messenger.job.error_code` (значения enum, без `id` и текста ошибок). + +| Где | Значение | Кто пишет | Кто читает | +| --- | --- | --- | --- | +| колонки `attachment_jobs.traceparent`, `tracestate` (`text NULL`, CHECK `NOT VALID`, ревизия `e4b8c2d17f90`) | контекст W3C server span загрузки (JTP-4) | реплика API той же транзакцией, что `queued` и задание | relay при каждой публикации | +| заголовки сообщения AMQP `traceparent`, `tracestate` (carrier, JTP-1) | контекст span producer этой публикации | relay (`JobPublisher._publish_one`) | worker (`JobDelivery.trace_context`) | +| поля `traceparent`, `tracestate` тела `contracts/jobs.schema.json` | не заполняются | — | — | + +Отображение на схему задания: заголовок `traceparent` = поле `traceparent` = значение W3C +версии `00` (`^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`, тот же шаблон у CHECK колонки и +разбора заголовка), `tracestate` — то же, до 512 символов. Carrier — native headers брокера +(`contracts/attachment-states.md` это допускает): тело проверяет `AttachmentJobMessage` +(`extra="forbid"`, `pattern`), неверное значение в теле сделало бы сообщение «не по схеме» и +задание `dropped`, а заголовок не по W3C просто игнорируется — новая трасса, исход тот же. +Переносится только W3C Trace Context (`TraceContextTextMapPropagator`), baggage — нет; +глобального propagator нет (JTP-5). + +**Почему consumer span — дочерний и с link (JTP-2).** Semantic conventions messaging по умолчанию +связывают обработку с созданием сообщения link, но «exclusively for single messages» разрешают +сделать контекст создания родителем, и требуют link на него («SHOULD link») и описание выбора +(«SHOULD document» — этот раздел). Worker обрабатывает сообщения по одному, объемлющего span у +задачи доставки нет. Родитель даёт одну трассу на загрузку (цепочка до S3 и БД, включая повтор, +находится по одному trace-id) и цельную выборку цепочки при head sampling трека 1: sampler — +`ParentBased(ALWAYS_ON)`, флаг выборки загрузки доходит до worker. Цена — длинные трассы: +повторы растягивают трассу на минуты, replay — на часы. + +**Без контекста и смесь версий (JTP-6).** Строка без контекста (прежняя реплика во время `make +rolling_update`, реплика с выключенной телеметрией): relay публикует без заголовков и без span +producer, consumer span — корень, как на уровне 3. Прежний relay колонок не знает, прежний worker +заголовки игнорирует, тело прежнее: ни одна комбинация версий не даёт ошибки, рвутся только +цепочки заданий, которых коснулся прежний код. Relay с выключенной телеметрией кладёт +сохранённый контекст как есть: цепочка API → worker не рвётся. Span relay — только span +producer под сохранённым контекстом: проходы relay и его обращения к PostgreSQL трасс не +начинают. Команда replay SDK не запускает: replay виден следующей парой producer / consumer. + +### Сигналы уровня 4 + +| Логический сигнал контракта | Инструмент SDK | Prometheus | Единица | +| --- | --- | --- | --- | +| p50 / p95 / p99 HTTP и обработки | histogram прежние | `histogram_quantile(q, sum by (le) (rate(…_bucket[5m])))` | с | +| время до `ready` (end-to-end time to ready) | histogram `messenger.job.time_to_ready`, границы 0,25…600 с | `messenger_job_time_to_ready_seconds_{bucket,sum,count}{job="messenger-worker", messenger_job_type}` | с | +| глубина очереди | ObservableGauge `messenger.queue.depth` | `messenger_queue_depth{job="messenger-relay", messaging_destination_name, messenger_queue_stage}` (`scheduled`, `outbox`, `published`, `processing`) | задания | +| возраст старейшей job | ObservableGauge `messenger.queue.oldest_age` | `messenger_queue_oldest_age_seconds{job="messenger-relay"}` | с | +| пул БД: соединения | ObservableUpDownCounter `db.client.connection.count` | `db_client_connection_count{db_client_connection_pool_name, db_client_connection_state="used"\|"idle"}` | соединения | +| пул БД: предел | `db.client.connection.max` | `db_client_connection_max` | соединения | +| пул БД: ожидающие | `db.client.connection.pending_requests` | `db_client_connection_pending_requests` | запросы | +| пул БД: отказы по сроку | ObservableCounter `db.client.connection.timeouts` | `db_client_connection_timeouts_total` | отказы | +| насыщение worker | ObservableUpDownCounter `messenger.worker.busy`, `.capacity`, `.waiting` | `messenger_worker_busy`, `messenger_worker_capacity`, `messenger_worker_waiting` | доставки | +| CPU контейнера | ObservableCounter `container.cpu.time` | `container_cpu_time_seconds_total` | с CPU | +| память контейнера | ObservableUpDownCounter `container.memory.usage` | `container_memory_usage_bytes` | байты | +| пределы контейнера | `messenger.container.cpu.limit`, `messenger.container.memory.limit` | `messenger_container_cpu_limit`, `messenger_container_memory_limit_bytes` | ядра, байты | +| трассы upload → publish → consume | span `PRODUCER` relay, `CONSUMER` worker | Tempo: `messaging.*`, `messenger.job.*`; связь parent и link | span | + +Ряды пула, CPU и памяти — у каждого процесса с SDK (`job` = `messenger-api`, `messenger-worker`, +`messenger-relay`, `instance` = `service.instance.id`); имя пула — `postgres:5432/messenger`. +Имена проверены на стенде запросами через Grafana (apply, `trace-chain`). + +Запросы панелей уровня 4 (`messenger-overview.json`, строки «Pipeline» и «Saturation»; единицы +панелей — `s`, `percentunit`, `short`): + +- квантили HTTP: `histogram_quantile(0.5|0.95|0.99, sum by (le) (rate(http_server_request_duration_seconds_bucket{job="messenger-api"}[5m])))`, + обработки — то же над `messenger_job_duration_seconds_bucket{job="messenger-worker",messenger_job_outcome="ready"}` + (с); доля 5xx и доля 4xx — панели уровня 3 (`percentunit`); +- время до `ready`: `histogram_quantile(q, sum by (le) (rate(messenger_job_time_to_ready_seconds_bucket{job="messenger-worker"}[5m])))` (с); +- глубина по стадиям: `max by (messenger_queue_stage) (messenger_queue_depth{job="messenger-relay"})` (`short`); + возраст: `max(messenger_queue_oldest_age_seconds{job="messenger-relay"})` (с) — `max`, а не сумма: два + relay дали бы два ряда одного числа; +- пул: `sum by (job, instance) (db_client_connection_count{db_client_connection_state="used"}) / sum by (job, instance) (db_client_connection_max)` + (`percentunit`), ожидающие — `sum by (job, instance) (db_client_connection_pending_requests)`, отказы — + `sum by (job) (rate(db_client_connection_timeouts_total[5m]))` (`short`); +- worker: `sum(messenger_worker_busy) / sum(messenger_worker_capacity)` и среднее за окно + `sum(rate(messenger_job_duration_seconds_sum{job="messenger-worker"}[5m])) / sum(messenger_worker_capacity)` + (`percentunit`; длительность пишется ровно за время на месте — закон Литтла), ожидающие места — + `sum(messenger_worker_waiting)` (`short`); +- контейнеры: `sum by (job, instance) (rate(container_cpu_time_seconds_total[5m])) / sum by (job, instance) (messenger_container_cpu_limit)` + и `sum by (job, instance) (container_memory_usage_bytes) / sum by (job, instance) (messenger_container_memory_limit_bytes)` (`percentunit`). + +**Источник очереди (JTP-9)** — один процесс, relay: после успешного прохода, не чаще 5 с, снимок +по PostgreSQL одним выражением, каждый подзапрос — по условию своего частичного индекса +(`ix_attachment_jobs_outbox`, `_published`, `_lease`; состояния константой). Не реплики API (N +копий одного числа), не worker (его может быть два, outbox он не видит), не приёмник Collector +(пароль PostgreSQL у Collector без секретов и SQL вне кода приложения) и не метрики брокера (только +стадия `published`, без outbox, обработки и возраста). Возраст — от устойчивого приёма (задание +вместе с `queued`, до 202): «время до `ready` до сих пор» старейшего незавершённого. + +**CPU и память — cgroup изнутри, без `docker.sock` (JTP-12).** Процессы с SDK читают свою +cgroup v2 (`cpu.stat`, `memory.current`, `cpu.max`, `memory.max`; файлы `r--r--r--` от UID +10001). Сокет Docker у Collector (`docker_stats`) отвергнут: доступ к API Docker — root на ВМ +(`:ro` у сокета API не ограничивает), а Collector принимает OTLP без аутентификации из сети +приложения; cAdvisor требует привилегированных монтирований `/`, `/sys`, `/var/lib/docker`; +`hostmetrics` видит ВМ целиком, а не контейнеры. В `docker compose config` монтирования сокета +Docker нет ни у одного сервиса (`trace-chain`). + +**Ресурс relay:** `service.name` = `messenger-relay` (константа `TELEMETRY_SERVICE_RELAY`, в +таблице `OTEL_SERVICE_NAME` — третья точка входа), `service.instance.id` = `instance_id` журнала +relay (короткий id контейнера), остальное — как у API и worker; `TELEMETRY__ENABLED` и +`TELEMETRY__OTLP_ENDPOINT` — якорем `x-telemetry-env` и у `relay`. Модули SDK, экспортёра, +protobuf и `requests` загружаются только при включённой телеметрии (JTP-7): уборщик, команда +replay, консоль, `make test_isolated`, стенд отказов и `bench/` их не держат; исключение — +модули метрик SDK, которые сам загружает redis-py 8.1 при импорте. + +**Бюджет (JTP-15).** Новых сервисов и портов нет, лимиты прежние, соединений PostgreSQL не +прибавляется; пики relay с SDK и уборщика после ленивого импорта — раздел change в +`evidence/telemetry/budget.md` (снимается после коммита кода). + +**Ограничения уровня 4:** + +- пул и насыщение worker — мгновенные значения раз в интервал отправки (15 с): короткие всплески + пропускаются; отказы пула — счётчик, насыщение — ещё и среднее по сумме длительностей; +- снимок очереди, который relay не обновил дольше 30 с, не отдаётся, но экспортёр Collector держит + последнюю точку до `metric_expiration` (5 мин) — панель может показать прежнее значение до + 5 мин; у остановленного relay очереди на панели нет; +- PostgreSQL, S3, брокер, LB и уборщик в метриках CPU и памяти не представлены (нет SDK, сокета + Docker нет); у worker в его cgroup — и процессы обработки; +- время до `ready` не учитывает задания после replay (их приём — действие оператора) и повторную + доставку готового; +- трасса без корня, если Collector был недоступен при загрузке («root span not yet received»); + длинные трассы повторов и replay искажают длительность трассы в поиске Tempo — искать по + атрибутам span (`messenger.job.outcome`); +- при перезапуске процесса counter начинается с нуля под тем же `instance`: если новый процесс + насчитал больше прежнего, Prometheus сброса не видит (`increase()` занижает) — проверка + `trace-chain` складывает счётчики процессов; +- без `messaging.message.id` (решение 12 change `otel-telemetry`: `id` задания не в span) и без + span Create и Settle: подтверждение — внутри consumer span. + ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | @@ -142,7 +278,11 @@ Tempo 253, Grafana 248 МиБ, правило выполнено и для на | Телеметрия не меняет ответы и остановку | `driver.py --port 8080 telemetry-outage` | код 0: `make test` PASS и остановка < 10 с при остановленном и замороженном Collector | `evidence/telemetry/collector-outage.md` | | Стенд с нуля одной командой | `driver.py stand-from-scratch --runs 2` | код 0 оба раза, `RestartCount` брокера и телеметрии 0 | `evidence/stand/from-scratch.md` | | Лимиты и бюджет телеметрии | замер `docker stats` и `memory.peak` | лимит ≥ 1,5 × пика у всех сервисов телеметрии | `evidence/telemetry/budget.md` | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | +| Уровень 4: контекст W3C API → relay → worker, producer и consumer span (parent и link), цепочка одной загрузки до S3 и БД с повтором и replay | `driver.py --port 8080 trace-chain` | код 0: одна трасса, две пары producer / consumer, span S3 с ошибкой и запись оригинала и вариантов, replay в той же трассе, задание без контекста — корень worker | `evidence/telemetry/trace-chain.md` (после коммита кода) | +| Уровень 4: dashboard — p50 / p95 / p99, доля ошибок, глубина и возраст очереди, пул БД, насыщение worker, контейнеры | `driver.py --port 8080 trace-chain`, `telemetry-check` | запросы панелей уровня 4 без ошибок и с данными; ряды очереди только у relay; пределы = `docker inspect`; нет сокета Docker | `evidence/telemetry/trace-chain.md`, `evidence/telemetry/check.md` | +| Уровень 4: relay с SDK не меняет остановку | `driver.py --port 8080 telemetry-outage` | `docker stop` relay < 10 с, код 0, «Stopped relay» при остановленном и замороженном Collector | `evidence/telemetry/collector-outage.md` | +| Уровень 4: схема контекста задания | миграция с нуля, повтор, откат, `--sql`, `make rolling_update`; план снимка очереди | `lock_timeout`, `NOT VALID`; без Seq Scan | `evidence/migrations/job-trace-context.md`, `evidence/telemetry/queue-snapshot.md` | +| Остальные пункты уровня 4 (SLO, alerts, runbooks, инциденты) | change `slo-alerts` | TODO | TODO | | Выбранный трек 5, если заявлен | TODO | TODO | TODO | TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 8b77f6d..da9f96a 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -106,6 +106,10 @@ services: image: mtusi-messenger:bench restart: "no" volumes: !reset [] + environment: + # телеметрия выключена, как у api и worker (design change + # job-trace-propagation, решение 7) + TELEMETRY__ENABLED: "false" deploy: resources: limits: diff --git a/config_example.toml b/config_example.toml index d70d41f..ead3b72 100644 --- a/config_example.toml +++ b/config_example.toml @@ -186,10 +186,11 @@ republish_after_seconds = 300 failure_pause_seconds = 2 [telemetry] -# Телеметрия API и worker (OpenTelemetry SDK → Collector). Включение и адрес -# Collector здесь не задаются: файл монтируется и в консольный запуск, а -# телеметрию включает compose у api и worker (TELEMETRY__ENABLED, -# TELEMETRY__OTLP_ENDPOINT). Переменные OTEL_* настройками не являются. +# Телеметрия API, worker и relay (OpenTelemetry SDK → Collector). Включение и +# адрес Collector здесь не задаются: файл монтируется и в консольный запуск, а +# телеметрию включает compose у api, worker и relay (TELEMETRY__ENABLED, +# TELEMETRY__OTLP_ENDPOINT). Уборщик, миграции и команда replay секцию не +# применяют. Переменные OTEL_* настройками не являются. # deployment.environment.name ресурса environment = "lab" # секунды между отправками метрик diff --git a/docker-compose.yml b/docker-compose.yml index d11e802..479839a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -457,8 +457,9 @@ services: entrypoint: ["python", "-m", "src.relay"] restart: unless-stopped environment: - # только PostgreSQL и брокер: ни ключей S3, ни пароля Valkey - <<: [*db-env, *broker-env] + # только PostgreSQL и брокер: ни ключей S3, ни пароля Valkey; адрес + # Collector — не секрет (design change job-trace-propagation, решение 7) + <<: [*db-env, *broker-env, *telemetry-env] # проход последовательный: второе соединение не нужно DATABASE__POOL_SIZE: "1" volumes: diff --git a/infra/otel/grafana/dashboards/messenger-overview.json b/infra/otel/grafana/dashboards/messenger-overview.json index 49a859b..25c28e1 100644 --- a/infra/otel/grafana/dashboards/messenger-overview.json +++ b/infra/otel/grafana/dashboards/messenger-overview.json @@ -1,13 +1,13 @@ { "uid": "messenger-overview", "title": "Messenger overview", - "description": "Level 3 signals of contracts/observability.md: API RPS, errors and duration, worker jobs and duration, logs and traces (design change otel-telemetry, decision 16). Provisioned from git, UI changes are not saved.", + "description": "Signals of contracts/observability.md, levels 3 and 4: API RPS, errors and duration, worker jobs and duration, queue depth and age, time to ready, PostgreSQL pools, worker and container saturation, logs and traces (design changes otel-telemetry, decision 16, and job-trace-propagation, decision 14). Provisioned from git, UI changes are not saved.", "tags": ["messenger", "lab6"], "timezone": "utc", "editable": false, "graphTooltip": 1, "schemaVersion": 39, - "version": 1, + "version": 2, "refresh": "30s", "time": {"from": "now-1h", "to": "now"}, "annotations": {"list": []}, @@ -79,7 +79,7 @@ { "id": 5, "type": "timeseries", - "title": "Request duration p50 and p95 (all replicas)", + "title": "Request duration p50, p95 and p99 (all replicas)", "description": "Quantiles from the sum of buckets of all replicas, not averages of replicas.", "datasource": {"type": "prometheus", "uid": "prometheus"}, "gridPos": {"h": 8, "w": 12, "x": 0, "y": 9}, @@ -97,6 +97,12 @@ "datasource": {"type": "prometheus", "uid": "prometheus"}, "expr": "histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket{job=\"messenger-api\"}[5m])))", "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "histogram_quantile(0.99, sum by (le) (rate(http_server_request_duration_seconds_bucket{job=\"messenger-api\"}[5m])))", + "legendFormat": "p99" } ] }, @@ -169,8 +175,8 @@ { "id": 10, "type": "timeseries", - "title": "Job duration p50 and p95 (ready)", - "description": "Handling of one delivery after the concurrency slot, outcome ready.", + "title": "Job duration p50, p95 and p99 (ready)", + "description": "Handling of one delivery after the concurrency slot, outcome ready; quantiles from the sum of buckets of all workers.", "datasource": {"type": "prometheus", "uid": "prometheus"}, "gridPos": {"h": 8, "w": 8, "x": 16, "y": 18}, "fieldConfig": {"defaults": {"unit": "s", "min": 0}, "overrides": []}, @@ -187,6 +193,214 @@ "datasource": {"type": "prometheus", "uid": "prometheus"}, "expr": "histogram_quantile(0.95, sum by (le) (rate(messenger_job_duration_seconds_bucket{job=\"messenger-worker\",messenger_job_outcome=\"ready\"}[5m])))", "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "histogram_quantile(0.99, sum by (le) (rate(messenger_job_duration_seconds_bucket{job=\"messenger-worker\",messenger_job_outcome=\"ready\"}[5m])))", + "legendFormat": "p99" + } + ] + }, + { + "id": 14, + "type": "row", + "title": "Pipeline (messenger-relay, messenger-worker)", + "collapsed": false, + "gridPos": {"h": 1, "w": 24, "x": 0, "y": 26}, + "panels": [] + }, + { + "id": 15, + "type": "timeseries", + "title": "Queue depth by stage", + "description": "Unfinished jobs from one source, the relay snapshot of PostgreSQL every 5 s: scheduled (waits for the next attempt), outbox (due, not published), published (not taken), processing. A snapshot older than 30 s is not reported; the Collector keeps the last point up to 5 min.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 8, "x": 0, "y": 27}, + "fieldConfig": {"defaults": {"unit": "short", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "table", "placement": "bottom", "calcs": ["lastNotNull"]}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "max by (messenger_queue_stage) (messenger_queue_depth{job=\"messenger-relay\"})", + "legendFormat": "{{messenger_queue_stage}}" + } + ] + }, + { + "id": 16, + "type": "timeseries", + "title": "Age of the oldest unfinished job", + "description": "Seconds since the oldest unfinished job was accepted (queued with its job, before 202): accumulation, not handling time; 0 without unfinished jobs.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 8, "x": 8, "y": 27}, + "fieldConfig": {"defaults": {"unit": "s", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "single"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "max(messenger_queue_oldest_age_seconds{job=\"messenger-relay\"})", + "legendFormat": "oldest age" + } + ] + }, + { + "id": 17, + "type": "timeseries", + "title": "Time to ready p50, p95 and p99", + "description": "From accepted upload (queued with its job) to committed ready, including waiting in the queue, retries and lease returns; jobs after replay are not counted.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 8, "x": 16, "y": 27}, + "fieldConfig": {"defaults": {"unit": "s", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "histogram_quantile(0.5, sum by (le) (rate(messenger_job_time_to_ready_seconds_bucket{job=\"messenger-worker\"}[5m])))", + "legendFormat": "p50" + }, + { + "refId": "B", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "histogram_quantile(0.95, sum by (le) (rate(messenger_job_time_to_ready_seconds_bucket{job=\"messenger-worker\"}[5m])))", + "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "histogram_quantile(0.99, sum by (le) (rate(messenger_job_time_to_ready_seconds_bucket{job=\"messenger-worker\"}[5m])))", + "legendFormat": "p99" + } + ] + }, + { + "id": 18, + "type": "row", + "title": "Saturation (pools, worker, containers)", + "collapsed": false, + "gridPos": {"h": 1, "w": 24, "x": 0, "y": 35}, + "panels": [] + }, + { + "id": 19, + "type": "timeseries", + "title": "PostgreSQL pool: used of max", + "description": "db.client.connection.count{state=used} to db.client.connection.max per process with the SDK (API replicas, worker, relay); instantaneous value once per export interval.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 6, "x": 0, "y": 36}, + "fieldConfig": {"defaults": {"unit": "percentunit", "min": 0, "max": 1}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum by (job, instance) (db_client_connection_count{db_client_connection_state=\"used\"}) / sum by (job, instance) (db_client_connection_max)", + "legendFormat": "{{job}} {{instance}}" + } + ] + }, + { + "id": 20, + "type": "timeseries", + "title": "PostgreSQL pool: waiting and timeouts", + "description": "Requests waiting for a pool connection (instantaneous) and pool checkouts that timed out per second.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 6, "x": 6, "y": 36}, + "fieldConfig": {"defaults": {"unit": "short", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum by (job, instance) (db_client_connection_pending_requests)", + "legendFormat": "waiting {{job}} {{instance}}" + }, + { + "refId": "B", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum by (job) (rate(db_client_connection_timeouts_total[5m]))", + "legendFormat": "timeouts/s {{job}}" + } + ] + }, + { + "id": 21, + "type": "timeseries", + "title": "Worker saturation", + "description": "Busy concurrency slots to capacity of all workers (instantaneous) and the window average: sum of delivery durations per second to capacity.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 6, "x": 12, "y": 36}, + "fieldConfig": {"defaults": {"unit": "percentunit", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum(messenger_worker_busy) / sum(messenger_worker_capacity)", + "legendFormat": "busy / capacity" + }, + { + "refId": "B", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum(rate(messenger_job_duration_seconds_sum{job=\"messenger-worker\"}[5m])) / sum(messenger_worker_capacity)", + "legendFormat": "average over 5m" + } + ] + }, + { + "id": 22, + "type": "timeseries", + "title": "Worker deliveries waiting for a slot", + "description": "Deliveries received from the broker (prefetch) that wait for a concurrency slot.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 6, "x": 18, "y": 36}, + "fieldConfig": {"defaults": {"unit": "short", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "single"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum(messenger_worker_waiting)", + "legendFormat": "waiting" + } + ] + }, + { + "id": 23, + "type": "timeseries", + "title": "Container CPU of limit", + "description": "CPU of the container from its cgroup v2 (cpu.stat) to the CPU limit (cpu.max), API replicas, worker with render processes, relay. PostgreSQL, S3, broker, load balancer and cleaner are not in these metrics.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 12, "x": 0, "y": 44}, + "fieldConfig": {"defaults": {"unit": "percentunit", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum by (job, instance) (rate(container_cpu_time_seconds_total[5m])) / sum by (job, instance) (messenger_container_cpu_limit)", + "legendFormat": "{{job}} {{instance}}" + } + ] + }, + { + "id": 24, + "type": "timeseries", + "title": "Container memory of limit", + "description": "memory.current of the container to memory.max, same processes as CPU.", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "gridPos": {"h": 8, "w": 12, "x": 12, "y": 44}, + "fieldConfig": {"defaults": {"unit": "percentunit", "min": 0}, "overrides": []}, + "options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}}, + "targets": [ + { + "refId": "A", + "datasource": {"type": "prometheus", "uid": "prometheus"}, + "expr": "sum by (job, instance) (container_memory_usage_bytes) / sum by (job, instance) (messenger_container_memory_limit_bytes)", + "legendFormat": "{{job}} {{instance}}" } ] }, @@ -195,16 +409,16 @@ "type": "row", "title": "Logs and traces", "collapsed": false, - "gridPos": {"h": 1, "w": 24, "x": 0, "y": 26}, + "gridPos": {"h": 1, "w": 24, "x": 0, "y": 52}, "panels": [] }, { "id": 12, "type": "logs", - "title": "API and worker logs", + "title": "API, worker and relay logs", "description": "Records of stdout exported through the Collector; trace_id opens the trace in Tempo.", "datasource": {"type": "loki", "uid": "loki"}, - "gridPos": {"h": 12, "w": 24, "x": 0, "y": 27}, + "gridPos": {"h": 12, "w": 24, "x": 0, "y": 53}, "options": {"showTime": true, "showLabels": false, "wrapLogMessage": true, "sortOrder": "Descending", "enableLogDetails": true, "dedupStrategy": "none", "prettifyLogMessage": false}, "targets": [ { @@ -219,9 +433,9 @@ "id": 13, "type": "table", "title": "Recent traces", - "description": "TraceQL search of API requests and worker deliveries; a trace opens with links to its logs.", + "description": "TraceQL search of API requests and worker deliveries; an upload trace holds its relay publications and worker deliveries; a trace opens with links to its logs.", "datasource": {"type": "tempo", "uid": "tempo"}, - "gridPos": {"h": 10, "w": 24, "x": 0, "y": 39}, + "gridPos": {"h": 10, "w": 24, "x": 0, "y": 65}, "options": {"showHeader": true}, "targets": [ { diff --git a/migrations/versions/2026_11_11_1200-e4b8c2d17f90_added_job_trace_context.py b/migrations/versions/2026_11_11_1200-e4b8c2d17f90_added_job_trace_context.py new file mode 100644 index 0000000..125af4d --- /dev/null +++ b/migrations/versions/2026_11_11_1200-e4b8c2d17f90_added_job_trace_context.py @@ -0,0 +1,63 @@ +"""added job trace context + +Revision ID: e4b8c2d17f90 +Revises: d3f9a6b2c1e7 +Create Date: 2026-11-11 12:00:00.000000 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "e4b8c2d17f90" +down_revision: str | Sequence[str] | None = "d3f9a6b2c1e7" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + # expand (design change job-trace-propagation, решение 4): прежний код + # колонки не пишет и не читает, у прежних строк — NULL. ACCESS EXCLUSIVE + # на attachment_jobs — lock_timeout (migrations.md). CHECK NOT VALID: + # прежние строки условию отвечают, просмотр таблицы под блокировкой не + # нужен, а новые строки условие проверяет сразу + op.execute("SET LOCAL lock_timeout = '2s'") + op.add_column( + "attachment_jobs", + sa.Column("traceparent", sa.Text(), nullable=True), + ) + op.add_column( + "attachment_jobs", + sa.Column("tracestate", sa.Text(), nullable=True), + ) + op.execute( + "ALTER TABLE attachment_jobs ADD CONSTRAINT " + "ck_attachment_jobs_traceparent " + "CHECK (traceparent ~ '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$') " + "NOT VALID", + ) + op.execute( + "ALTER TABLE attachment_jobs ADD CONSTRAINT " + "ck_attachment_jobs_tracestate " + "CHECK (tracestate IS NULL OR (traceparent IS NOT NULL " + "AND char_length(tracestate) BETWEEN 1 AND 512)) NOT VALID", + ) + + +def downgrade() -> None: + op.execute("SET LOCAL lock_timeout = '2s'") + op.drop_constraint( + op.f("ck_attachment_jobs_tracestate"), + "attachment_jobs", + type_="check", + ) + op.drop_constraint( + op.f("ck_attachment_jobs_traceparent"), + "attachment_jobs", + type_="check", + ) + op.drop_column("attachment_jobs", "tracestate") + op.drop_column("attachment_jobs", "traceparent") diff --git a/openspec/changes/job-trace-propagation/design.md b/openspec/changes/job-trace-propagation/design.md index 7aba8b2..863d022 100644 --- a/openspec/changes/job-trace-propagation/design.md +++ b/openspec/changes/job-trace-propagation/design.md @@ -432,3 +432,49 @@ evidence. `REPORT.md` — «Наблюдаемость»: сквозная тр Блокирующих нет. Решения без пользователя и вопросы преподавателю, которые не меняют спеки и задачи, — `QUESTIONS.md`, раздел `## job-trace-propagation`. + +## Уточнения apply + +1. **redis-py сам грузит модули метрик SDK (решение 7).** `redis.observability.providers` (redis-py 8.1) при импорте + делает `from opentelemetry.sdk.metrics import MeterProvider` — проба «установлен ли SDK»; `src.infra.cache` импортируют + все точки входа через `src.core.services`. Поэтому без телеметрии в процессе 35 модулей `opentelemetry.sdk.metrics` + (и `sdk.resources`, `sdk.util`) остаются; провайдеров трасс и логов SDK, экспортёра, protobuf и `requests` нет. Проба + на образе (уборщик): с ленивым импортом 99 МиБ RSS и 1175 модулей против 105,5 МиБ и 1373 — экономия ~6,5 МиБ и ~200 + модулей, а не 10 МиБ и 322 (та проба мерила `import src.infra.db.uow` поверх уже загруженного redis). Тест «модули + SDK без телеметрии» требует: ни экспортёра, ни `opentelemetry.sdk.trace` / `_logs`, ни protobuf, ни `requests`, а + модули SDK — не больше, чем даёт `import redis.asyncio` в отдельном интерпретаторе. Подмена `sys.modules` ради + буквы сценария отвергнута: сломала бы включённую телеметрию в том же процессе. Вопрос — `QUESTIONS.md`. +2. **Флаги W3C.** SDK 1.45 ставит у корня бит «random trace id» (`0x02`): `traceparent` загрузки — `…-03`, а не `…-01`. + CHECK колонки, шаблон контракта и разбор заголовка принимают любые два hex-символа; выборка — бит `0x01`. +3. **Запись «Container metrics are unavailable»** пишется до хуков журнала — только stdout: на хосте без cgroup (macOS) + журнал в хранилище логов и записи быстрых тестов прежние (задача 3.7). +4. **Где код.** Span producer и consumer, `JobObservation` — модуль `messaging.py`, метрики пула, worker и очереди — + `metrics.py`, cgroup — `container.py`, SDK и экспортёры — `sdk.py`; `core.py` — API OpenTelemetry. `_handle` worker + принимает счётчики `load` именованным параметром (без него — свои, тесты прежних сигнатур работают); `upload()` + принимает `trace_context=None` по умолчанию. Предел пула в метрике — `size()` + `[database] max_overflow` из + настроек (`instrument_engine(..., max_overflow=…)` для тестов). +5. **Итог доставки (решение 8).** У `skipped` номер попытки подставляет `handle` из сообщения; у `requeued` — тоже из + сообщения; `failed` из claim при исчерпанном бюджете — причина из `last_error_code`, если это значение enum. +6. **Снимок очереди (решение 9)** снимается и после полного пакета (проход повторяется сразу): интервал 5 с держит + `QueueSnapshots.due`. Сигнал до снимка — снимка нет. +7. **Риск «Tempo делит трассу» не подтвердился (решение 2 прежнее).** Пробные прогоны `trace-chain`: повтор через ~10 с и + replay через ~20 с — span producer и consumer в той же трассе по trace-id, Tempo 3.1 собирает их из разных блоков. +8. **`trace-chain` и счётчик времени до `ready`.** Worker в проверке перезапускается дважды, счётчик процесса начинается + с нуля под тем же `instance`; если новый процесс насчитал больше прежнего, Prometheus сброса не видит, и `increase()` + занижает (пробный прогон: 3 вместо 5). Проверка складывает «тихие» значения двух процессов (до второй остановки и в + конце). Ограничение — в `REPORT.md`. Worker и relay запускаются `docker start` того же контейнера: `docker compose + start worker` поднимал зависимости, в том числе замороженный S3, и падал. +9. **`telemetry-outage`:** relay сверяется по `StartedAt` и `RestartCount` до своей остановки (сценарий «Collector + недоступен для relay»), его `docker stop` — тем же `timed_stop`, что у реплики; в рестарт при остановленных сервисах + телеметрии relay входит вместе с `api` и `worker`. +10. **Память уборщика.** `memory.peak` уборщика на рабочем стенде — 176 МиБ: плановая сверка при старте; в простое после + неё `memory.current` 105 МиБ (anon), VmRSS 112–117 МиБ. Лимит 256 МиБ и сверка — не предмет change; числа и правило + 1,5 × пика — раздел change в `evidence/telemetry/budget.md` (задача 12.4). +11. **Логгер пула (решение 10).** SQLAlchemy называет логгер пула модулем и классом: у `CountingQueuePool` это + `src.infra.db.engine.CountingQueuePool`, потомок логгера `src` уровня INFO — после первого развёртывания в журнале + relay и worker появились записи «Pool recreating» и «Pool disposed» (найдено по журналу консольного relay). Логгер + пула — в конфигурации журнала на WARNING, как прежний пул SQLAlchemy под root (`DB_POOL_LOGGER`), тест + `test_pool_logger_stays_quiet`. +12. **Бюджет relay (решение 15)** проверен до коммита (числа — в scratchpad для 12.4): `memory.peak` relay с SDK 94–99 + МиБ, наибольшая выборка `docker stats` 91 МиБ, CPU до 27 % ядра при лимите 0,25 — лимит 256 МиБ ≥ 1,5 × пика, не + менялся; пики сервисов телеметрии в прежних границах (Tempo до 385 МиБ из 640, Grafana 255 из 512). diff --git a/openspec/changes/job-trace-propagation/tasks.md b/openspec/changes/job-trace-propagation/tasks.md index 4ae335b..e06444a 100644 --- a/openspec/changes/job-trace-propagation/tasks.md +++ b/openspec/changes/job-trace-propagation/tasks.md @@ -8,16 +8,16 @@ ## 1. Правила, константы, DTO -- [ ] 1.1 Прочитать (Read) правила `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, +- [x] 1.1 Прочитать (Read) правила `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, `dto.md`, `repo-layer.md`, `migrations.md`, `service-layer.md`, `api-layer.md`, `service-tests.md`, `bench.md`, `student-tests.md`, `run-modes.md` — до правок файлов их слоёв. Проверка: каждое прочитано через Read в этой сессии. -- [ ] 1.2 Константы `src/utils/constants.py` (13): `TELEMETRY_SERVICE_RELAY = "messenger-relay"`, имена метрик уровня 4, +- [x] 1.2 Константы `src/utils/constants.py` (13): `TELEMETRY_SERVICE_RELAY = "messenger-relay"`, имена метрик уровня 4, атрибуты (`messaging.*`, `messenger.job.attempt`, `.replayed`, `.retry_reason`, `.redelivered`, `.reason`, `.error_code`, `messenger.queue.stage`, `db.client.connection.*`), значения стадий, границы `TIME_TO_READY_BUCKETS` (8), `QUEUE_SNAPSHOT_INTERVAL_SECONDS = 5`, `QUEUE_SNAPSHOT_STALE_SECONDS = 30`, путь cgroup, `TRACEPARENT_PATTERN` и `TRACESTATE_MAX_LENGTH` — им же пользуется `src/schemas/jobs/attachment.py` вместо своих литералов. Проверка: `make lint`; `uv run python -c "import src.schemas.jobs"`. -- [ ] 1.3 DTO `src/schemas/dataclasses/` (`dto.md`): `TraceContextDTO(traceparent, tracestate=None)`, +- [x] 1.3 DTO `src/schemas/dataclasses/` (`dto.md`): `TraceContextDTO(traceparent, tracestate=None)`, `JobPublicationDTO` (id, тело, номер попытки, признак replay, причина повтора, контекст), `JobDeliveryResultDTO` (исход, попытка, причина, код ошибки, время до готовности), `QueueSnapshotDTO` (время снимка, четыре стадии, `oldest_created_at`); `AttachmentJobDTO` — поля `traceparent`, `tracestate` последними со значением `None`; экспорт в `__init__.py` по алфавиту. @@ -25,12 +25,12 @@ ## 2. Схема и repo -- [ ] 2.1 Модель `AttachmentJob` и ревизия alembic поверх `d3f9a6b2c1e7` (4): `traceparent`, `tracestate` (`text NULL`), +- [x] 2.1 Модель `AttachmentJob` и ревизия alembic поверх `d3f9a6b2c1e7` (4): `traceparent`, `tracestate` (`text NULL`), CHECK `ck_attachment_jobs_traceparent` и `ck_attachment_jobs_tracestate` `NOT VALID`, первой строкой `SET LOCAL lock_timeout = '2s'`, `downgrade` зеркально; имя файла по `file_template`, литералы вместо констант. Проверка на временной базе: `upgrade` с нуля, повтор, `downgrade -1`, снова `upgrade`; `alembic upgrade --sql` содержит `lock_timeout` и `NOT VALID`; autogenerate после ревизии изменений не находит. -- [ ] 2.2 Repo заданий (4, 9): `insert_job` пишет `traceparent` и `tracestate`, `_JOB_COLUMNS` их читает; новый метод +- [x] 2.2 Repo заданий (4, 9): `insert_job` пишет `traceparent` и `tracestate`, `_JOB_COLUMNS` их читает; новый метод `queue_snapshot(*, now)` — порт с докстрингом-контрактом, SQL одним выражением по частичным индексам, состояния — `literal_execute`; фейк `FakeAttachmentJobRepository` (вставка с контекстом, снимок по стадиям); строки `service-tests/repo_contract.py` — контекст после вставки и после `lock_due_jobs`, стадии `scheduled` / `outbox` / @@ -39,57 +39,57 @@ ## 3. Пакет телеметрии -- [ ] 3.1 Ленивый импорт (7): SDK, экспортёр и `requests` — новый модуль `src/infra/telemetry/sdk.py`, его импортирует +- [x] 3.1 Ленивый импорт (7): SDK, экспортёр и `requests` — новый модуль `src/infra/telemetry/sdk.py`, его импортирует `start()`; остальные модули пакета — только `opentelemetry-api` (типы SDK — под `TYPE_CHECKING`). Проверка: тест 8.1 «модули SDK без телеметрии» (отдельный интерпретатор: после импорта `src.main`, `src.worker.main`, `src.relay.main`, `src.cleaner.main` нет `opentelemetry.sdk`, `opentelemetry.exporter`, `google.protobuf`, `requests`); прежние тесты `test_telemetry.py` зелёные. -- [ ] 3.2 Sampler `ParentBased(ALWAYS_ON)` (5), propagator `TraceContextTextMapPropagator` без глобального propagator и +- [x] 3.2 Sampler `ParentBased(ALWAYS_ON)` (5), propagator `TraceContextTextMapPropagator` без глобального propagator и baggage; `current_trace_context()` — `TraceContextDTO` текущего валидного span (невыбранный — с флагом `00`), иначе `None`. Проверка: тесты 8.1 (в server span — его `traceparent`, вне span и без телеметрии — `None`, удалённый родитель с флагом `00` — span не записывается). -- [ ] 3.3 Span producer (3): контекстный менеджер с родителем — сохранённым контекстом, `PRODUCER` `publish <очередь>`, +- [x] 3.3 Span producer (3): контекстный менеджер с родителем — сохранённым контекстом, `PRODUCER` `publish <очередь>`, атрибуты решения 13, ошибка и отмена — `ERROR` и класс; отдаёт заголовки для сообщения (контекст span; без телеметрии — сохранённый контекст как есть; без контекста — пусто и без span). Проверка: тесты 8.1. -- [ ] 3.4 Consumer span (2): родитель — контекст из доставки и link на него, без контекста — корень `Context()`, как раньше; +- [x] 3.4 Consumer span (2): родитель — контекст из доставки и link на него, без контекста — корень `Context()`, как раньше; `messaging.operation.name`, повторная доставка; `JobObservation.finish(result=…)` — атрибуты попытки, причины, кода ошибки и запись `messenger.job.time_to_ready` (View с границами решения 8), если в итоге есть время. Проверка: тесты 8.1 и прежний `test_delivery_outcome_span_and_histogram` (без контекста у span нет родителя). -- [ ] 3.5 Пул (10): `CountingQueuePool(AsyncAdaptedQueuePool)` в `src/infra/db/engine.py` (`connect()` со счётом ожидающих и +- [x] 3.5 Пул (10): `CountingQueuePool(AsyncAdaptedQueuePool)` в `src/infra/db/engine.py` (`connect()` со счётом ожидающих и отказов по сроку, методы `pending()`, `timeouts()`), `poolclass=` в `create_engine`; `instrument_engine` регистрирует `db.client.connection.*` с чтением текущего пула engine и именем `server.address:server.port/db.namespace`. Проверка: тесты 8.1 и 8.4. -- [ ] 3.6 Насыщение worker и очередь (9, 11): регистрация наблюдаемых `messenger.worker.busy` / `.capacity` / `.waiting` по +- [x] 3.6 Насыщение worker и очередь (9, 11): регистрация наблюдаемых `messenger.worker.busy` / `.capacity` / `.waiting` по переданным счётчикам и gauge очереди по последнему снимку (стадии, возраст, снимок старше 30 с не отдаётся). Проверка: тесты 8.1. -- [ ] 3.7 Контейнер (12): модуль чтения cgroup v2 (`cpu.stat`, `memory.current`, `cpu.max`, `memory.max`, `max` — без +- [x] 3.7 Контейнер (12): модуль чтения cgroup v2 (`cpu.stat`, `memory.current`, `cpu.max`, `memory.max`, `max` — без точки), регистрация в `start_process_telemetry` с корнем cgroup — параметром (по умолчанию константа), без файлов — одна запись `warning` «Container metrics are unavailable». Проверка: тест 8.1 на временном каталоге; прежние тесты журнала `test_telemetry.py` на macOS не получают лишних записей; на стенде после 10.3 — пределы совпадают с `docker inspect`. ## 4. Загрузка в API -- [ ] 4.1 Зависимость `TraceContextDep` в `src/api/dependencies.py` (4), ручка загрузки передаёт `trace_context=` в +- [x] 4.1 Зависимость `TraceContextDep` в `src/api/dependencies.py` (4), ручка загрузки передаёт `trace_context=` в `AttachmentService.upload` (докстринг ручки — без «брокер подтвердил сообщение»), сервис — до `_mark_queued` и в `AttachmentJobDTO`. Сервис телеметрию не импортирует. Проверка: тесты 8.2 (контекст в строке задания, без него — `None`); `make test` на стенде после 10.3. ## 5. Relay -- [ ] 5.1 `AttachmentRelayService` (3, 9): элементы публикации `JobPublicationDTO` из строк задания (номер попытки, признак +- [x] 5.1 `AttachmentRelayService` (3, 9): элементы публикации `JobPublicationDTO` из строк задания (номер попытки, признак replay `attempt_base > 0`, причина повтора — `last_error_code`, контекст из колонок); метод `queue_snapshot()` — один блок. Проверка: тесты 8.2 (`test_attachment_relay.py`). -- [ ] 5.2 `JobPublisher` (3): `publish_many(items)` принимает `JobPublicationDTO`, `_publish_one` открывает span producer и +- [x] 5.2 `JobPublisher` (3): `publish_many(items)` принимает `JobPublicationDTO`, `_publish_one` открывает span producer и кладёт его заголовки в `aio_pika.Message(headers=…)`; срок пакета и сброс соединения прежние; `FakeJobPublisher` хранит элементы с контекстом. Проверка: тест 8.1 на фейковом канале (заголовки сообщения, span на каждое), `test_architecture` (сигнатуры клиента и фейка). -- [ ] 5.3 `src/relay/main.py` (7, 9, 15): запуск телеметрии после `early_stop.disarm()`, `instrument_engine`, gauge +- [x] 5.3 `src/relay/main.py` (7, 9, 15): запуск телеметрии после `early_stop.disarm()`, `instrument_engine`, gauge очереди; в `_serve` после успешного прохода — снимок не чаще 5 с только при включённой телеметрии, отказ PostgreSQL — пропуск; закрытие SDK в окне `gather` 0,5 с, «Stopped relay» после него; «Started relay» — `telemetry_enabled`, `telemetry_endpoint`, `telemetry_environment`. Команда replay SDK не запускает. Проверка: тест 8.2 (цикл со снимком на фейках); на стенде — запись о старте и `driver.py --port 8080 relay-process` с кодом 0; в консоли `make run_relay` — `telemetry_enabled: false` (сценарий «Телеметрия relay»). -- [ ] 5.4 Окружение: у `relay` в `docker-compose.yml` — `*telemetry-env`; `TELEMETRY__ENABLED: "false"` у relay в +- [x] 5.4 Окружение: у `relay` в `docker-compose.yml` — `*telemetry-env`; `TELEMETRY__ENABLED: "false"` у relay в `bench/bench.compose.yml` и `student-tests/failures.compose.yml`, `-e TELEMETRY__ENABLED=false` у контейнера relay в `student-tests/run_isolated.py`. Проверка: `docker compose config --quiet` рабочего стенда, CI (`-f .github/ci/compose.yml`), `bench/` и стенда отказов; в `docker compose config` у relay рабочего стенда `TELEMETRY__ENABLED: "true"`, у остальных — @@ -97,19 +97,19 @@ ## 6. Worker -- [ ] 6.1 `JobConsumer.deliveries()` (1, 6): `JobDelivery.trace_context` из заголовков `traceparent` и `tracestate` (`str` +- [x] 6.1 `JobConsumer.deliveries()` (1, 6): `JobDelivery.trace_context` из заголовков `traceparent` и `tracestate` (`str` или ASCII `bytes`, шаблон W3C, длина `tracestate`), иначе `None`; разбор тела не меняется. Проверка: тест 8.1 (верный, `bytes`, не по шаблону, длинный `tracestate`, нет заголовков). -- [ ] 6.2 `AttachmentProcessingService.handle()` → `JobDeliveryResultDTO` (8): попытка, причина у `retry` и `failed`, код +- [x] 6.2 `AttachmentProcessingService.handle()` → `JobDeliveryResultDTO` (8): попытка, причина у `retry` и `failed`, код ошибки у `failed`, время до готовности у `ready` без replay — после фиксации `ready` от `job.created_at`. Быстрые тесты сервиса — через `.outcome` и новые поля. Проверка: `make service_test` (`test_attachment_processing.py`). -- [ ] 6.3 `src/worker/main.py` (2, 8, 11): `consumer_span(parent=delivery.trace_context, redelivered=…)`, счётчики «ждут +- [x] 6.3 `src/worker/main.py` (2, 8, 11): `consumer_span(parent=delivery.trace_context, redelivered=…)`, счётчики «ждут места» и «заняты» вокруг `async with slots` (снимаются в `finally`), регистрация насыщения, `observation.finish(result=…)`, действие с сообщением — из `result.outcome`. Проверка: тесты 8.1 и `test_worker_deliveries.py`. ## 7. Dashboard уровня 4 -- [ ] 7.1 `infra/otel/grafana/dashboards/messenger-overview.json` (14): p99 в панелях длительности HTTP и обработки, строки +- [x] 7.1 `infra/otel/grafana/dashboards/messenger-overview.json` (14): p99 в панелях длительности HTTP и обработки, строки «Pipeline» (глубина по стадиям, возраст, время до `ready` p50 / p95 / p99) и «Saturation» (пул, ожидающие и отказы, worker, CPU и память контейнеров к пределам) с запросами и единицами решения 14; uid источников прежние. Проверка: `python3 -m json.tool` без ошибок; после 10.3 и `docker compose restart grafana` — dashboard provisioned, каждый запрос новых панелей к @@ -117,73 +117,73 @@ ## 8. Быстрые тесты -- [ ] 8.1 `service-tests/unit/test_telemetry.py` на in-memory экспортёрах: контекст загрузки; span producer (родитель и trace +- [x] 8.1 `service-tests/unit/test_telemetry.py` на in-memory экспортёрах: контекст загрузки; span producer (родитель и trace id из сохранённого контекста, заголовки — его контекст, атрибуты, ошибка и отмена; без телеметрии — заголовки как есть; без контекста — ни span, ни заголовков); `JobPublisher._publish_one` на фейковом канале; consumer span (родитель и link, корень без контекста и с неверным, флаг `00` — не записан); время до готовности (replay — нет точки); пул на фейковом пуле; насыщение worker в `_handle` при занятом месте; gauge очереди (свежий и устаревший снимок); контейнер на временном каталоге cgroup и без него; ресурс relay; разбор заголовков доставки; модули SDK без телеметрии — в отдельном интерпретаторе. Проверка: `make service_test`. -- [ ] 8.2 Тесты сервисов: `test_attachment_service.py` (контекст в задании и `None`), `test_attachment_relay.py` (элементы +- [x] 8.2 Тесты сервисов: `test_attachment_service.py` (контекст в задании и `None`), `test_attachment_relay.py` (элементы публикации: контекст, номер попытки, replay, причина; снимок очереди), `test_attachment_processing.py` (поля итога по исходам, время до готовности и его отсутствие после replay), `test_worker_deliveries.py` (контекст доставки доходит до span). Проверка: `make service_test`. -- [ ] 8.3 Контракт repo (2.2) на фейке и на SQL — одни условия. Проверка: `make service_test` и `make service_test_db`. -- [ ] 8.4 `service-tests/db/`: настоящий engine с пулом 1 и коротким сроком ожидания — второй блок ждёт (`pending()` 1), +- [x] 8.3 Контракт repo (2.2) на фейке и на SQL — одни условия. Проверка: `make service_test` и `make service_test_db`. +- [x] 8.4 `service-tests/db/`: настоящий engine с пулом 1 и коротким сроком ожидания — второй блок ждёт (`pending()` 1), отказ по сроку увеличивает `timeouts()`; после `engine.dispose()` пул того же класса. Проверка: `make service_test_db`. ## 9. Драйвер скилла `run-mtusi-messenger` -- [ ] 9.1 Команда `driver.py --port trace-chain` (16, спек «Цепочка и сигналы уровня 4 находятся»): пять частей решения +- [x] 9.1 Команда `driver.py --port trace-chain` (16, спек «Цепочка и сигналы уровня 4 находятся»): пять частей решения 16, таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2, в `finally` — `unpause s3`, `start worker relay`; секреты и токены не печатаются; только stdlib и синтаксис 3.9. Проверка: `python3 -m py_compile` системным `python3`; `--help` называет команду; пробный прогон после 10.3 — код 0 (вывод в scratchpad). -- [ ] 9.2 `telemetry-check` (16): шаги задания — по consumer span трассы загрузки, шаг «трасса задания — трасса загрузки», +- [x] 9.2 `telemetry-check` (16): шаги задания — по consumer span трассы загрузки, шаг «трасса задания — трасса загрузки», relay в пробе сетей; ресурс span producer — `messenger-relay` и `service.instance.id` = `instance_id` журнала relay, корней-span relay нет; запись relay о проходе в Loki совпадает со stdout и не содержит `trace_id`. Проверка: пробный прогон после 10.3 — код 0. -- [ ] 9.3 `telemetry-outage` (16): остановки relay при остановленном и замороженном Collector (< 10 с, код 0, «Stopped +- [x] 9.3 `telemetry-outage` (16): остановки relay при остановленном и замороженном Collector (< 10 с, код 0, «Stopped relay»), relay в рестарте при остановленных сервисах телеметрии, сигналы relay снова приходят. Проверка: пробный прогон после 10.3 — код 0. -- [ ] 9.4 `SKILL.md` — `trace-chain` и изменения двух команд. Проверка: `grep -n trace-chain` по `SKILL.md`. +- [x] 9.4 `SKILL.md` — `trace-chain` и изменения двух команд. Проверка: `grep -n trace-chain` по `SKILL.md`. ## 10. Стенд и регрессия (до коммита) -- [ ] 10.1 `make lint`, `make service_test`, `make service_test_db`. Проверка: зелёные; причины падений — в отчёте apply до +- [x] 10.1 `make lint`, `make service_test`, `make service_test_db`. Проверка: зелёные; причины падений — в отчёте apply до правок. -- [ ] 10.2 Сборка и проверка образа: `docker compose build api`; `docker compose config --quiet` (рабочий, CI, `bench/`, +- [x] 10.2 Сборка и проверка образа: `docker compose build api`; `docker compose config --quiet` (рабочий, CI, `bench/`, отказы). Проверка: коды 0. -- [ ] 10.3 Развёртывание без простоя (Migration Plan): `make rolling_update` — ревизия один раз; `docker compose up -d +- [x] 10.3 Развёртывание без простоя (Migration Plan): `make rolling_update` — ревизия один раз; `docker compose up -d --no-deps relay worker cleaner`; `docker compose restart grafana`. Проверка: «Started relay» — `telemetry_enabled: true`; `alembic_version` — новая ревизия; у уборщика в `/proc/1/maps` и списке модулей нет SDK (проба в контейнере); `make lb_stats` — обе реплики `UP`. -- [ ] 10.4 Имена в Prometheus: каждый ряд таблицы решения 13 есть с ожидаемыми метками у ожидаемых `job`; расхождение +- [x] 10.4 Имена в Prometheus: каждый ряд таблицы решения 13 есть с ожидаемыми метками у ожидаемых `job`; расхождение экспортёра Collector — правка запросов панелей и таблицы, запись в «Уточнения apply». Проверка: запросы через API Grafana. -- [ ] 10.5 Регрессия на стенде: `make test`; `make student_test` через LB (красный только `test_exclusion_evidence_exists`); +- [x] 10.5 Регрессия на стенде: `make test`; `make student_test` через LB (красный только `test_exclusion_evidence_exists`); `make test_isolated` и `make failure_checks` — прежние результаты, «Started relay» их relay — телеметрия выключена; `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` с `STOP_MODE` `stop` и `kill`. Проверка: выводы команд; причины падений — до правок. -- [ ] 10.6 Пробные прогоны `trace-chain`, `telemetry-check`, `telemetry-outage` на рабочем дереве (scratchpad). Проверка: +- [x] 10.6 Пробные прогоны `trace-chain`, `telemetry-check`, `telemetry-outage` на рабочем дереве (scratchpad). Проверка: коды 0; если Tempo делит трассу повтора — решение 2 пересматривается (Risks), запись в «Уточнения apply». -- [ ] 10.7 Бюджет (15): `memory.peak` и CPU relay и уборщика (и сервисов телеметрии — проверка, что пики прежние) под `make +- [x] 10.7 Бюджет (15): `memory.peak` и CPU relay и уборщика (и сервисов телеметрии — проверка, что пики прежние) под `make test` + `make load` + `make student_test` + `trace-chain`; лимит relay — не меньше 1,5 × пика, иначе поднять и пересчитать суммы `docker.md` и `REPORT.md`. Проверка: числа в scratchpad для 12.4; `docker inspect` совпадает с суммами. ## 11. Документы -- [ ] 11.1 Правила (17): `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, `dto.md`, +- [x] 11.1 Правила (17): `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, `dto.md`, `repo-layer.md`, `migrations.md`, `bench.md`, `student-tests.md`, `run-modes.md`. Проверка: в каждом — ссылка на design change `job-trace-propagation` и нет пересказа спека; `telemetry.md` больше не говорит «только API и worker» и «sampler `ALWAYS_ON`». -- [ ] 11.2 `config_example.toml` (секция `[telemetry]` — и relay), `.env.example` (`messenger-relay` в соответствии +- [x] 11.2 `config_example.toml` (секция `[telemetry]` — и relay), `.env.example` (`messenger-relay` в соответствии `OTEL_SERVICE_NAME`). Проверка: `git diff` без значений секретов. -- [ ] 11.3 `AGENTS.md`: состояние лабы (второй change), таблица важных файлов, карта кода (`src/infra/telemetry/`, `relay`, +- [x] 11.3 `AGENTS.md`: состояние лабы (второй change), таблица важных файлов, карта кода (`src/infra/telemetry/`, `relay`, `worker`, `engine.py`, миграция, `evidence/telemetry/`), команда `trace-chain`. Проверка: `grep` новых путей и команды. -- [ ] 11.4 `REPORT.md`, раздел «Наблюдаемость», по требованию «Наблюдаемость в отчёте»: сквозная трасса (carrier и +- [x] 11.4 `REPORT.md`, раздел «Наблюдаемость», по требованию «Наблюдаемость в отчёте»: сквозная трасса (carrier и отображение заголовков на поля `jobs.schema.json`, parent и link и почему, без контекста и смесь версий), таблица и запросы сигналов уровня 4 с единицами, источник очереди, отказ от `docker.sock`, ресурс `messenger-relay`, бюджет, ограничения (решения 9–12, Risks); строки «Доказательства критериев» уровня 4. Проверка: сценарий «Отчёт по наблюдаемости». -- [ ] 11.5 `QUESTIONS.md`, раздел `## job-trace-propagation` (создан на propose) — дополнить решениями и вопросами apply; +- [x] 11.5 `QUESTIONS.md`, раздел `## job-trace-propagation` (создан на propose) — дополнить решениями и вопросами apply; design — «Уточнения apply» с отклонениями от решений. Проверка: каждое отклонение названо там. ## 12. Evidence (после коммита кода основной сессией) diff --git a/service-tests/db/test_pool_counts.py b/service-tests/db/test_pool_counts.py new file mode 100644 index 0000000..b307f3c --- /dev/null +++ b/service-tests/db/test_pool_counts.py @@ -0,0 +1,85 @@ +"""`CountingQueuePool` на настоящем engine: ожидающие и отказы по сроку пула +(design change `job-trace-propagation`, решение 10; спек `observability`, +«Пул исчерпан»).""" + +import asyncio +import logging + +import pytest +from sqlalchemy import exc, text + +from conftest import make_engine +from src.infra.db.engine import CountingQueuePool + +pytestmark = pytest.mark.anyio + + +async def test_pool_counts_pending_and_timeouts() -> None: + engine = make_engine( + pool_size=1, + max_overflow=0, + pool_timeout_seconds=0.5, + ) + try: + pool = engine.sync_engine.pool + assert isinstance(pool, CountingQueuePool) + assert (pool.pending(), pool.timeouts()) == (0, 0) + async with engine.connect() as held: + await held.execute(text("SELECT 1")) + + async def second() -> None: + async with engine.connect() as connection: + await connection.execute(text("SELECT 1")) + + waiting = asyncio.create_task(second()) + for _ in range(100): + if pool.pending() == 1: + break + await asyncio.sleep(0.01) + # ждёт места, пока первое соединение занято + assert pool.pending() == 1 + with pytest.raises(exc.TimeoutError): + await waiting + assert pool.pending() == 0 + assert pool.timeouts() == 1 + # место свободно — выдача без ожидания и без отказа + async with engine.connect() as connection: + await connection.execute(text("SELECT 1")) + assert (pool.pending(), pool.timeouts()) == (0, 1) + finally: + await engine.dispose() + + +async def test_pool_logger_stays_quiet() -> None: + """Логгер пула назван по классу в `src`: журнал держит его на WARNING, + как прежний пул SQLAlchemy, — «Pool disposed» и «Pool recreating» INFO не + пишутся (найдено в apply по журналу консольного relay).""" + from src.infra.logger import get_logger + from src.utils.constants import DB_POOL_LOGGER + + get_logger() + engine = make_engine(pool_size=1) + try: + pool_logger = engine.sync_engine.pool.logger + assert pool_logger.name == DB_POOL_LOGGER + assert not pool_logger.isEnabledFor(logging.INFO) + assert pool_logger.isEnabledFor(logging.WARNING) + finally: + await engine.dispose() + + +async def test_pool_class_survives_dispose() -> None: + """`dispose()` создаёт новый пул того же класса: метрики читают его.""" + engine = make_engine(pool_size=1) + try: + before = engine.sync_engine.pool + async with engine.connect() as connection: + await connection.execute(text("SELECT 1")) + await engine.dispose() + after = engine.sync_engine.pool + assert after is not before + assert isinstance(after, CountingQueuePool) + assert after.size() == 1 + assert (after.pending(), after.timeouts()) == (0, 0) + finally: + await engine.dispose() diff --git a/service-tests/db/test_uow.py b/service-tests/db/test_uow.py index ae77c48..0c3adfb 100644 --- a/service-tests/db/test_uow.py +++ b/service-tests/db/test_uow.py @@ -473,6 +473,8 @@ async def _statements(engine, action) -> list[str]: ("count_published", "'queued'"), ("count_unfinished", "'processing'"), ("count_unfinished", "'queued'"), + ("queue_snapshot", "'processing'"), + ("queue_snapshot", "'queued'"), ("lock_stale_pending", "'pending'"), ("get_staging_candidates", "'ready'"), ], @@ -491,6 +493,8 @@ async def test_status_is_a_constant_in_statement( await uow.jobs.count_published() elif method == "count_unfinished": await uow.jobs.count_unfinished(limit=1) + elif method == "queue_snapshot": + await uow.jobs.queue_snapshot(now=NOW) elif method == "lock_stale_pending": await uow.attachments.lock_stale_pending( attachment_id=user_dto().id, diff --git a/service-tests/fakes/clients.py b/service-tests/fakes/clients.py index d0c3773..d823b9d 100644 --- a/service-tests/fakes/clients.py +++ b/service-tests/fakes/clients.py @@ -18,7 +18,7 @@ from src.infra.s3 import ( StoredObjectInfo, StoredObjectPage, ) -from src.schemas.dataclasses import RenderedVariantsDTO +from src.schemas.dataclasses import JobPublicationDTO, RenderedVariantsDTO from .database import FakeDatabase @@ -207,16 +207,22 @@ class FakeJobPublisher: self.unconfirmed: set[UUID] = set() self.ready = 0 self.published: list[UUID] = [] + # элементы публикаций с контекстом и номером попытки (design change + # job-trace-propagation, решение 3) + self.items: list[JobPublicationDTO] = [] async def publish_many( self, - items: Sequence[tuple[UUID, bytes]], + items: Sequence[JobPublicationDTO], ) -> set[UUID]: self._db.record("publisher.publish_many") confirmed = { - job_id for job_id, _ in items if job_id not in self.unconfirmed + item.job_id + for item in items + if item.job_id not in self.unconfirmed } - self.published.extend(job_id for job_id, _ in items) + self.published.extend(item.job_id for item in items) + self.items.extend(items) return confirmed async def ready_messages(self) -> int: diff --git a/service-tests/fakes/repos.py b/service-tests/fakes/repos.py index 768b14e..e0e0cfc 100644 --- a/service-tests/fakes/repos.py +++ b/service-tests/fakes/repos.py @@ -666,6 +666,8 @@ class FakeAttachmentJobRepository( attempt=job.attempt, created_at=job.created_at, updated_at=job.updated_at, + traceparent=job.traceparent, + tracestate=job.tracestate, ) return job @@ -700,6 +702,39 @@ class FakeAttachmentJobRepository( ) return sum(min(len(group), limit) for group in groups) + async def queue_snapshot( + self, + *, + now: datetime, + ) -> dataclasses.QueueSnapshotDTO: + unfinished = [ + job + for job in self._db.jobs.values() + if job.state + in {AttachmentJobState.QUEUED, AttachmentJobState.PROCESSING} + ] + outbox = [ + job + for job in unfinished + if job.state == AttachmentJobState.QUEUED + and job.published_at is None + ] + return dataclasses.QueueSnapshotDTO( + taken_at=now, + scheduled=sum(1 for job in outbox if _due_at(job) > now), + outbox=sum(1 for job in outbox if _due_at(job) <= now), + published=len(self._published()), + processing=sum( + 1 + for job in unfinished + if job.state == AttachmentJobState.PROCESSING + ), + oldest_created_at=min( + (job.created_at for job in unfinished), + default=None, + ), + ) + async def get_attachment_job( self, *, diff --git a/service-tests/repo_contract.py b/service-tests/repo_contract.py index 8153974..62c9ebb 100644 --- a/service-tests/repo_contract.py +++ b/service-tests/repo_contract.py @@ -938,6 +938,109 @@ async def check_count_unfinished(new_uow: NewUow) -> None: assert await count(1) == 3 +TRACEPARENT = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" + + +async def check_job_trace_context(new_uow: NewUow) -> None: + """Контекст задания сохраняется вставкой и читается выборками, в том + числе relay (design change `job-trace-propagation`, решение 4).""" + world = await _world(new_uow) + attachment = await _attachment( + new_uow, + world, + status=AttachmentStatus.QUEUED, + created_at=at(-10), + ) + traced = replace( + job_dto(attachment_id=attachment.id, created_at=at(-10)), + traceparent=TRACEPARENT, + tracestate="vendor=value", + ) + plain = await _job(new_uow, world, created_at=at(-5)) + async with new_uow() as uow: + await uow.jobs.insert_job(job=traced) + await uow.commit() + row = await _job_row(new_uow, traced.id) + assert row is not None + assert row.traceparent == TRACEPARENT + assert row.tracestate == "vendor=value" + without = await _job_row(new_uow, plain.id) + assert without is not None + assert without.traceparent is None + assert without.tracestate is None + async with new_uow() as uow: + due = await uow.jobs.lock_due_jobs(now=NOW, limit=10) + by_id = {job.id: job for job in due} + assert by_id[traced.id].traceparent == TRACEPARENT + assert by_id[traced.id].tracestate == "vendor=value" + assert by_id[plain.id].traceparent is None + + +async def check_queue_snapshot(new_uow: NewUow) -> None: + world = await _world(new_uow) + + async def snapshot(now: datetime = NOW) -> dataclasses.QueueSnapshotDTO: + async with new_uow() as uow: + return await uow.jobs.queue_snapshot(now=now) + + empty = await snapshot() + assert empty == dataclasses.QueueSnapshotDTO( + taken_at=NOW, + scheduled=0, + outbox=0, + published=0, + processing=0, + oldest_created_at=None, + ) + # завершённые не считаются + await _failed_job(new_uow, world) + # срок наступил, не опубликовано + outbox = await _job(new_uow, world, created_at=at(-30)) + # ещё не наступил срок приёма — тоже ждёт срока + await _job(new_uow, world, created_at=at(20)) + published = await _job(new_uow, world, created_at=at(-20)) + retrying = await _started_job(new_uow, world, lease_expires_at=at(100)) + processing = await _started_job(new_uow, world, lease_expires_at=at(100)) + async with new_uow() as uow: + await uow.jobs.mark_published(job_ids=[published.id], now=at(-1)) + assert await uow.jobs.return_to_queued( + job_id=retrying.id, + attempt=retrying.attempt, + reason=AttachmentJobReason.STORAGE_UNAVAILABLE, + next_attempt_at=at(60), + now=at(-1), + ) + await uow.commit() + result = await snapshot() + assert ( + result.scheduled, + result.outbox, + result.published, + result.processing, + ) == (2, 1, 1, 1) + assert result.taken_at == NOW + assert result.oldest_created_at == outbox.created_at + # срок следующей попытки наступил — стадия outbox + later = await snapshot(at(61)) + assert (later.scheduled, later.outbox) == (0, 3) + # старейший — среди всех незавершённых: в работе раньше других + async with new_uow() as uow: + await uow.jobs.finish_job( + job_id=outbox.id, + state=AttachmentJobState.SUCCEEDED, + reason=None, + now=at(1), + ) + await uow.commit() + rest = await snapshot() + assert rest.oldest_created_at == min( + published.created_at, + processing.created_at, + retrying.created_at, + ) + assert rest.outbox == 0 + + async def check_recover_expired_leases(new_uow: NewUow) -> None: world = await _world(new_uow) expired = await _started_job(new_uow, world, lease_expires_at=at(-5)) diff --git a/service-tests/unit/test_attachment_processing.py b/service-tests/unit/test_attachment_processing.py index d56475a..2be6b96 100644 --- a/service-tests/unit/test_attachment_processing.py +++ b/service-tests/unit/test_attachment_processing.py @@ -102,11 +102,18 @@ def _body(job: dataclasses.AttachmentJobDTO) -> bytes: return build_job_body(job, attempt=job.attempt + 1) +async def _result( + service: AttachmentProcessingService, + job: dataclasses.AttachmentJobDTO, +) -> dataclasses.JobDeliveryResultDTO: + return await service.handle(body=_body(job), redelivered=False) + + async def _handle( service: AttachmentProcessingService, job: dataclasses.AttachmentJobDTO, ) -> JobDeliveryOutcome: - return await service.handle(body=_body(job), redelivered=False) + return (await _result(service, job)).outcome @pytest.mark.parametrize( @@ -186,11 +193,95 @@ async def test_malformed_message_dropped( service: AttachmentProcessingService, database: FakeDatabase, ) -> None: - outcome = await service.handle(body=b"not json", redelivered=False) - assert outcome == Outcome.DROPPED + result = await service.handle(body=b"not json", redelivered=False) + assert result == dataclasses.JobDeliveryResultDTO(outcome=Outcome.DROPPED) assert database.events == [] +# --- итог доставки (design change job-trace-propagation, решение 8) ------- + + +async def test_result_of_ready_has_time_to_ready( + service: AttachmentProcessingService, + database: FakeDatabase, + queued: dataclasses.AttachmentJobDTO, +) -> None: + """Время до готовности — от приёма (`created_at` задания) до фиксации + `ready`: ожидание в очереди входит.""" + _set_job( + database, + queued.id, + created_at=queued.created_at - timedelta(seconds=30), + ) + result = await _result(service, queued) + assert result.outcome == Outcome.READY + assert result.attempt == 1 + assert result.reason is None + assert result.error_code is None + assert result.time_to_ready_seconds is not None + assert 30 <= result.time_to_ready_seconds < 40 + + +async def test_result_after_replay_has_no_time_to_ready( + service: AttachmentProcessingService, + database: FakeDatabase, + queued: dataclasses.AttachmentJobDTO, +) -> None: + """Задание после replay (`attempt_base > 0`) во время до готовности не + входит: его приём — действие оператора.""" + _set_job(database, queued.id, attempt=2, attempt_base=2) + result = await _result(service, queued) + assert result.outcome == Outcome.READY + assert result.attempt == 3 + assert result.time_to_ready_seconds is None + + +async def test_result_of_retry_names_reason( + service: AttachmentProcessingService, + database: FakeDatabase, + queued: dataclasses.AttachmentJobDTO, +) -> None: + database.fail_on["storage.get"] = exceptions.ObjectStorageUnavailable() + result = await _result(service, queued) + assert result == dataclasses.JobDeliveryResultDTO( + outcome=Outcome.RETRY, + attempt=1, + reason=AttachmentJobReason.STORAGE_UNAVAILABLE, + ) + + +async def test_result_of_failed_names_reason_and_code( + service: AttachmentProcessingService, + database: FakeDatabase, + queued: dataclasses.AttachmentJobDTO, +) -> None: + database.fail_on["renderer.render"] = exceptions.ImageRejected( + reason=AttachmentJobReason.UNDECODABLE, + ) + result = await _result(service, queued) + assert result == dataclasses.JobDeliveryResultDTO( + outcome=Outcome.FAILED, + attempt=1, + reason=AttachmentJobReason.UNDECODABLE, + error_code=AttachmentErrorCode.INVALID_IMAGE, + ) + + +async def test_result_of_skipped_has_message_attempt( + service: AttachmentProcessingService, + database: FakeDatabase, + queued: dataclasses.AttachmentJobDTO, +) -> None: + """Повторная доставка готового: без попытки, номер — из сообщения, без + времени до готовности (нового наблюдения нет).""" + await _handle(service, queued) + result = await _result(service, queued) + assert result == dataclasses.JobDeliveryResultDTO( + outcome=Outcome.SKIPPED, + attempt=1, + ) + + async def test_unknown_job_acked_without_attempt( service: AttachmentProcessingService, database: FakeDatabase, diff --git a/service-tests/unit/test_attachment_relay.py b/service-tests/unit/test_attachment_relay.py index a5aa9d2..735d737 100644 --- a/service-tests/unit/test_attachment_relay.py +++ b/service-tests/unit/test_attachment_relay.py @@ -1,5 +1,7 @@ """`AttachmentRelayService`: порядок публикации, предел, аренды, потерянные.""" +import asyncio +import json from dataclasses import replace from datetime import timedelta from uuid import uuid4 @@ -8,8 +10,10 @@ import pytest from builders import attachment_dto, job_dto from fakes import FakeDatabase, FakeJobPublisher, FakeUnitOfWork +from src.config import settings from src.core import exceptions from src.core.services.attachment_relay import AttachmentRelayService +from src.relay import main as relay_main from src.schemas import dataclasses from src.schemas.enums import ( AttachmentJobReason, @@ -281,3 +285,139 @@ async def test_broker_failure_rolls_back_block( stored = database.jobs[job.id] assert stored.published_at is None assert stored.state == AttachmentJobState.QUEUED + + +# --- публикации и снимок очереди (design change job-trace-propagation) --- + +TRACEPARENT = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" + + +async def test_publication_items_carry_context_and_attempt( + service: AttachmentRelayService, + uow: FakeUnitOfWork, + database: FakeDatabase, + publisher: FakeJobPublisher, +) -> None: + """Элемент публикации: номер следующей попытки, признак replay, причина + повтора, контекст из колонок задания; без контекста — `None`.""" + traced, plain, replayed = await _jobs(uow, database, 3) + database.jobs[traced.id] = replace( + database.jobs[traced.id], + attempt=1, + last_error_code=AttachmentJobReason.STORAGE_UNAVAILABLE.value, + traceparent=TRACEPARENT, + tracestate="vendor=value", + ) + database.jobs[replayed.id] = replace( + database.jobs[replayed.id], + attempt=4, + attempt_base=4, + traceparent=TRACEPARENT, + ) + await _pass(service) + items = {item.job_id: item for item in publisher.items} + first = items[traced.id] + assert first.attempt == 2 + assert first.replayed is False + assert first.retry_reason == "storage_unavailable" + assert first.trace_context == dataclasses.TraceContextDTO( + traceparent=TRACEPARENT, + tracestate="vendor=value", + ) + assert json.loads(first.body)["attempt"] == 2 + # тело — по схеме, без полей контекста: carrier — заголовки + assert "traceparent" not in json.loads(first.body) + second = items[plain.id] + assert second.attempt == 1 + assert second.retry_reason is None + assert second.trace_context is None + third = items[replayed.id] + assert third.replayed is True + assert third.attempt == 5 + assert third.trace_context == dataclasses.TraceContextDTO( + traceparent=TRACEPARENT, + ) + + +async def test_queue_snapshot_one_block( + service: AttachmentRelayService, + uow: FakeUnitOfWork, + database: FakeDatabase, +) -> None: + jobs = await _jobs(uow, database, 2) + before = utcnow() + snapshot = await service.queue_snapshot() + assert database.events == ["enter", "jobs.queue_snapshot", "exit"] + assert (snapshot.outbox, snapshot.published, snapshot.processing) == ( + 2, + 0, + 0, + ) + assert snapshot.taken_at >= before + assert snapshot.oldest_created_at == min(job.created_at for job in jobs) + + +class _LoopService: + """Проходы relay для цикла `_serve`: после `passes` проходов — сигнал.""" + + def __init__(self, stop: asyncio.Event, *, passes: int) -> None: + self.stop = stop + self.passes = passes + self.snapshots = 0 + self.fail_snapshot = False + + async def publish_pass(self, **_: object) -> dataclasses.RelayPassDTO: + self.passes -= 1 + if self.passes <= 0: + self.stop.set() + return dataclasses.RelayPassDTO( + published=0, + unconfirmed=0, + recovered=0, + republished=0, + published_backlog=0, + backlog_full=False, + selected=0, + duration_ms=0, + ) + + async def queue_snapshot(self) -> dataclasses.QueueSnapshotDTO: + self.snapshots += 1 + if self.fail_snapshot: + raise exceptions.ServiceUnavailable + return dataclasses.QueueSnapshotDTO( + taken_at=utcnow(), + scheduled=0, + outbox=1, + published=0, + processing=0, + ) + + +async def test_relay_loop_takes_snapshot_not_more_often( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Цикл relay: снимок после успешного прохода, не чаще 5 с; без + телеметрии — снимков нет; отказ PostgreSQL — пропуск.""" + monkeypatch.setattr(settings.relay, "poll_interval_seconds", 0) + stop = asyncio.Event() + loop_service = _LoopService(stop, passes=3) + snapshots = relay_main.QueueSnapshots() + await relay_main._serve(loop_service, stop=stop, snapshots=None) + assert loop_service.snapshots == 0 + stop.clear() + loop_service.passes = 3 + await relay_main._serve(loop_service, stop=stop, snapshots=snapshots) + # первый проход — снимок, следующие в пределах 5 с — нет; последний + # проход видел сигнал + assert loop_service.snapshots == 1 + assert snapshots.latest is not None + assert snapshots.latest.outbox == 1 + stop.clear() + loop_service.passes = 2 + loop_service.fail_snapshot = True + previous = snapshots.latest + failing = relay_main.QueueSnapshots() + await relay_main._serve(loop_service, stop=stop, snapshots=failing) + assert failing.latest is None + assert snapshots.latest is previous diff --git a/service-tests/unit/test_attachment_service.py b/service-tests/unit/test_attachment_service.py index 6a0df71..3bb557f 100644 --- a/service-tests/unit/test_attachment_service.py +++ b/service-tests/unit/test_attachment_service.py @@ -23,6 +23,7 @@ from src.config import settings from src.core import exceptions from src.core.services import AttachmentService from src.infra.upload_slots import UploadSlots +from src.schemas import dataclasses from src.schemas.enums import ( AttachmentErrorCode, AttachmentJobState, @@ -140,6 +141,45 @@ async def test_upload_order_and_events( assert not database.inside_block("storage.put") +async def test_upload_saves_trace_context_in_job( + service: AttachmentService, + database: FakeDatabase, + world: tuple[UUID, UUID, UUID], +) -> None: + """Контекст загрузки — в задании той же транзакцией, что `queued` + (design change `job-trace-propagation`, решение 4).""" + alice, _, chat_id = world + context = dataclasses.TraceContextDTO( + traceparent="00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01", + tracestate="vendor=value", + ) + attachment = await service.upload( + chat_id=chat_id, + owner_id=alice, + filename="a.png", + media_type="image/png", + content_length=None, + body=_body(SAMPLE), + trace_context=context, + ) + (job,) = database.jobs.values() + assert job.attachment_id == attachment.id + assert job.traceparent == context.traceparent + assert job.tracestate == "vendor=value" + + +async def test_upload_without_trace_context( + service: AttachmentService, + database: FakeDatabase, + world: tuple[UUID, UUID, UUID], +) -> None: + """Без телеметрии контекста нет — колонки задания пусты.""" + await _upload(service, world) + (job,) = database.jobs.values() + assert job.traceparent is None + assert job.tracestate is None + + def _fill_backlog(database: FakeDatabase, count: int) -> None: """`count` незавершённых заданий: `queued` и `processing` поровну.""" for number in range(count): diff --git a/service-tests/unit/test_telemetry.py b/service-tests/unit/test_telemetry.py index a549d89..4fdfa50 100644 --- a/service-tests/unit/test_telemetry.py +++ b/service-tests/unit/test_telemetry.py @@ -11,6 +11,7 @@ import time from collections.abc import Iterator from dataclasses import dataclass, field from typing import Any +from uuid import uuid4 import httpx import pytest @@ -43,11 +44,17 @@ from src.config import settings from src.config.settings import Telemetry as TelemetrySettings from src.infra import logger as app_logger from src.infra import telemetry +from src.infra.broker import JobPublisher from src.infra.cache.client import Cache from src.infra.logger import get_logger from src.infra.s3.client import ObjectStorage -from src.infra.telemetry import core -from src.schemas.enums import JobDeliveryOutcome +from src.infra.telemetry import core, metrics, sdk +from src.schemas import dataclasses +from src.schemas.enums import ( + AttachmentErrorCode, + AttachmentJobReason, + JobDeliveryOutcome, +) from src.utils.constants import ( ATTACHMENT_JOB_TYPE, METRIC_HTTP_SERVER_DURATION, @@ -623,7 +630,7 @@ def test_exporters_ignore_proxy_environment( return response monkeypatch.setattr(requests.Session, "send", send) - exporters = core._otlp_exporters( + exporters = sdk.otlp_exporters( TelemetrySettings(otlp_endpoint=COLLECTOR), ) tracer_provider = TracerProvider() @@ -658,6 +665,7 @@ class _Delivery: body: bytes = b"{}" redelivered: bool = False settled: list[str] = field(default_factory=list) + trace_context: dataclasses.TraceContextDTO | None = None async def ack(self) -> None: self.settled.append("ack") @@ -670,13 +678,20 @@ class _Delivery: class _Service: - def __init__(self, outcome: JobDeliveryOutcome | None) -> None: + def __init__( + self, + outcome: JobDeliveryOutcome | None, + result: dataclasses.JobDeliveryResultDTO | None = None, + ) -> None: self.outcome = outcome + self.result = result async def handle(self, *, body: bytes, redelivered: bool) -> Any: + if self.result is not None: + return self.result if self.outcome is None: raise RuntimeError(SECRET_TEXT) - return self.outcome + return dataclasses.JobDeliveryResultDTO(outcome=self.outcome) @pytest.mark.parametrize( @@ -738,3 +753,699 @@ async def test_delivery_without_telemetry_has_no_signals() -> None: ) assert delivery.settled == ["ack"] assert not trace.get_current_span().is_recording() + + +# --- сквозная трасса (design change job-trace-propagation) ---------------- + +QUEUE = "testdb.attachment.process.v1" +SAVED_TRACE = "0af7651916cd43dd8448eb211c80319c" +SAVED_SPAN = "b7ad6b7169203331" +SAVED = dataclasses.TraceContextDTO( + traceparent=f"00-{SAVED_TRACE}-{SAVED_SPAN}-01", + tracestate="vendor=value", +) +UNSAMPLED = dataclasses.TraceContextDTO( + traceparent=f"00-{SAVED_TRACE}-{SAVED_SPAN}-00", +) + + +def _start(**kwargs: Any) -> Signals: + collected = Signals( + spans=InMemorySpanExporter(), + metrics=InMemoryMetricReader(), + logs=InMemoryLogRecordExporter(), + ) + assert telemetry.start_process_telemetry( + kwargs.pop("service", SERVICE), + exporters=telemetry.Exporters( + spans=collected.spans, + metrics=collected.metrics, + logs=collected.logs, + ), + **kwargs, + ) + return collected + + +def _publication( + trace_context: dataclasses.TraceContextDTO | None = SAVED, + *, + attempt: int = 1, + replayed: bool = False, + retry_reason: str | None = None, +) -> dataclasses.JobPublicationDTO: + return dataclasses.JobPublicationDTO( + job_id=uuid4(), + body=b"{}", + attempt=attempt, + replayed=replayed, + retry_reason=retry_reason, + trace_context=trace_context, + ) + + +def _hex(value: int, width: int) -> str: + return format(value, f"0{width}x") + + +async def test_upload_context_is_server_span() -> None: + """Контекст загрузки — контекст server span запроса; вне span и без + телеметрии — `None` (решение 4).""" + seen: list[dataclasses.TraceContextDTO | None] = [] + app = FastAPI() + + @app.post("/api/v1/upload") + async def upload() -> dict[str, str]: + seen.append(telemetry.current_trace_context()) + return {} + + app.add_middleware(RequestContextMiddleware) + + async def call() -> None: + transport = httpx.ASGITransport(app=app) + async with httpx.AsyncClient( + transport=transport, + base_url="http://test", + ) as client: + await client.post("/api/v1/upload") + + await call() + assert seen == [None] + signals = _start() + try: + await call() + assert telemetry.current_trace_context() is None + (span,) = signals.finished_spans() + finally: + signals.finish() + telemetry.remove_log_hooks() + context = seen[-1] + assert context is not None + # флаги W3C — от SDK: выбрано и, у SDK 1.45, «random trace id» + flags = int(span.context.trace_flags) + assert flags & 0x01 + assert context.traceparent == ( + f"00-{_hex(span.context.trace_id, 32)}-" + f"{_hex(span.context.span_id, 16)}-{_hex(flags, 2)}" + ) + assert context.tracestate is None + + +def test_producer_span_under_saved_context(signals: Signals) -> None: + publication = _publication(attempt=2, retry_reason="storage_unavailable") + with telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=publication, + ) as headers: + pass + (span,) = signals.finished_spans() + assert span.kind == SpanKind.PRODUCER + assert span.name == f"publish {QUEUE}" + assert _hex(span.context.trace_id, 32) == SAVED_TRACE + assert span.parent is not None + assert _hex(span.parent.span_id, 16) == SAVED_SPAN + assert span.parent.is_remote + assert dict(span.attributes) == { + "messaging.system": "rabbitmq", + "messaging.destination.name": QUEUE, + "messaging.operation.type": "send", + "messaging.operation.name": "publish", + "messenger.job.type": ATTACHMENT_JOB_TYPE, + "messenger.job.attempt": 2, + "messenger.job.replayed": False, + "messenger.job.retry_reason": "storage_unavailable", + } + # заголовки — контекст span producer, tracestate прежний + assert headers == { + "traceparent": ( + f"00-{SAVED_TRACE}-{_hex(span.context.span_id, 16)}-01" + ), + "tracestate": "vendor=value", + } + assert str(publication.job_id) not in json.dumps(dict(span.attributes)) + + +@pytest.mark.parametrize("error", [RuntimeError, asyncio.CancelledError]) +def test_producer_span_error(signals: Signals, error: type) -> None: + with ( + pytest.raises(error), + telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=_publication(replayed=True), + ), + ): + raise error(SECRET_TEXT) + (span,) = signals.finished_spans() + assert span.status.status_code == StatusCode.ERROR + assert span.attributes["error.type"] == error.__name__ + assert span.attributes["messenger.job.replayed"] is True + assert SECRET_TEXT not in json.dumps(dict(span.attributes)) + + +@pytest.mark.parametrize( + "saved", + [ + None, + dataclasses.TraceContextDTO(traceparent="00-zz-bad-01"), + dataclasses.TraceContextDTO( + traceparent=f"00-{'0' * 32}-{'0' * 16}-01", + ), + ], + ids=["none", "garbage", "invalid"], +) +def test_producer_without_context_has_no_span( + signals: Signals, + saved: dataclasses.TraceContextDTO | None, +) -> None: + """Проходы relay трасс не начинают: без контекста — ни span, ни + заголовков.""" + with telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=_publication(saved), + ) as headers: + assert headers == {} + assert signals.finished_spans() == [] + + +def test_producer_without_telemetry_passes_context() -> None: + """Телеметрия relay выключена — сохранённый контекст как есть.""" + with telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=_publication(), + ) as headers: + assert headers == { + "traceparent": SAVED.traceparent, + "tracestate": "vendor=value", + } + + +@dataclass +class _Exchange: + messages: list[Any] = field(default_factory=list) + + async def publish( + self, + message: Any, + *, + routing_key: str, + mandatory: bool, + ) -> None: + self.messages.append((message, routing_key, mandatory)) + + +@dataclass +class _Channel: + default_exchange: _Exchange = field(default_factory=_Exchange) + + +async def test_publisher_puts_context_in_headers(signals: Signals) -> None: + """`JobPublisher._publish_one`: span на каждое сообщение, его контекст — + заголовки; без контекста — сообщение без заголовков, тело прежнее.""" + publisher = JobPublisher(settings.broker, namespace="testdb") + channel = _Channel() + traced = _publication() + plain = _publication(None) + await publisher._publish_one(channel, traced) + await publisher._publish_one(channel, plain) + (span,) = signals.finished_spans() + (first, key, mandatory), (second, _, _) = channel.default_exchange.messages + assert key == QUEUE + assert mandatory is True + assert first.body == traced.body + assert first.headers["traceparent"] == ( + f"00-{SAVED_TRACE}-{_hex(span.context.span_id, 16)}-01" + ) + assert first.headers["tracestate"] == "vendor=value" + assert first.message_id == str(traced.job_id) + assert not second.headers + assert second.body == plain.body + + +def test_consumer_span_child_with_link(signals: Signals) -> None: + with ( + telemetry.consumer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + parent=SAVED, + redelivered=True, + ), + telemetry.child_span("SELECT"), + ): + pass + spans = {span.name: span for span in signals.finished_spans()} + consumer = spans[f"process {QUEUE}"] + assert _hex(consumer.context.trace_id, 32) == SAVED_TRACE + assert _hex(consumer.parent.span_id, 16) == SAVED_SPAN + (link,) = consumer.links + assert _hex(link.context.span_id, 16) == SAVED_SPAN + assert _hex(link.context.trace_id, 32) == SAVED_TRACE + assert consumer.attributes["messaging.operation.name"] == "process" + assert consumer.attributes["messenger.job.redelivered"] is True + assert spans["SELECT"].parent.span_id == consumer.context.span_id + + +@pytest.mark.parametrize( + "parent", + [None, dataclasses.TraceContextDTO(traceparent="not-w3c")], + ids=["none", "garbage"], +) +def test_consumer_span_root_without_context( + signals: Signals, + parent: dataclasses.TraceContextDTO | None, +) -> None: + with telemetry.consumer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + parent=parent, + ): + pass + (span,) = signals.finished_spans() + assert span.parent is None + assert span.links == () + + +def test_unsampled_context_is_not_recorded(signals: Signals) -> None: + """Флаг «не выбрано» соблюдается: ни producer, ни consumer, ни + дочерних span; исход и метрика доставки те же (решение 5).""" + publication = _publication(UNSAMPLED) + with telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=publication, + ) as headers: + pass + assert headers["traceparent"].startswith(f"00-{SAVED_TRACE}-") + assert headers["traceparent"].endswith("-00") + parent = core.to_trace_context(headers) + with telemetry.consumer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + parent=parent, + ) as observation: + with telemetry.child_span("SELECT") as child: + assert child is None + observation.finish( + result=dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.READY, + attempt=1, + time_to_ready_seconds=1.5, + ), + duration_seconds=0.2, + ) + points = signals.points(METRIC_JOB_DURATION) + assert signals.finished_spans() == [] + (point,) = points + assert point.attributes["messenger.job.outcome"] == "ready" + + +async def test_delivery_result_attributes_and_time_to_ready( + signals: Signals, +) -> None: + result = dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.READY, + attempt=2, + time_to_ready_seconds=12.5, + ) + delivery = _Delivery(trace_context=SAVED) + await worker_main._handle( + lambda: _Service(None, result), + delivery, + asyncio.Semaphore(1), + asyncio.Event(), + ) + (point,) = signals.points("messenger.job.time_to_ready") + assert dict(point.attributes) == { + "messenger.job.type": ATTACHMENT_JOB_TYPE, + } + assert point.count == 1 + assert point.sum == 12.5 + assert point.explicit_bounds[0] == 0.25 + assert point.explicit_bounds[-1] == 600 + (span,) = signals.finished_spans() + assert _hex(span.context.trace_id, 32) == SAVED_TRACE + assert span.attributes["messenger.job.attempt"] == 2 + assert "messenger.job.reason" not in span.attributes + + +async def test_failed_result_names_reason_without_time( + signals: Signals, +) -> None: + result = dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.FAILED, + attempt=1, + reason=AttachmentJobReason.UNDECODABLE, + error_code=AttachmentErrorCode.INVALID_IMAGE, + ) + await worker_main._handle( + lambda: _Service(None, result), + _Delivery(), + asyncio.Semaphore(1), + asyncio.Event(), + ) + assert signals.points("messenger.job.time_to_ready") == [] + (span,) = signals.finished_spans() + assert span.attributes["messenger.job.reason"] == "undecodable" + assert span.attributes["messenger.job.error_code"] == "invalid_image" + + +# --- метрики уровня 4 ------------------------------------------------------- + + +@dataclass +class _Pool: + used: int = 2 + idle: int = 1 + waiting: int = 3 + timed_out: int = 4 + + def checkedout(self) -> int: + return self.used + + def checkedin(self) -> int: + return self.idle + + def size(self) -> int: + return 10 + + def pending(self) -> int: + return self.waiting + + def timeouts(self) -> int: + return self.timed_out + + +@dataclass +class _SyncEngine: + pool: Any + url: Any + + +@dataclass +class _Engine: + sync_engine: _SyncEngine + + +def test_pool_metrics(signals: Signals) -> None: + from sqlalchemy.engine import make_url + + engine = _Engine( + _SyncEngine( + pool=_Pool(), + url=make_url("postgresql+asyncpg://user@db:5432/app"), + ), + ) + metrics.observe_pool(engine, max_overflow=2) + name = {"db.client.connection.pool.name": "db:5432/app"} + counts = { + point.attributes["db.client.connection.state"]: point.value + for point in signals.points("db.client.connection.count") + } + assert counts == {"used": 2, "idle": 1} + (limit,) = signals.points("db.client.connection.max") + assert limit.value == 12 + assert dict(limit.attributes) == name + (pending,) = signals.points("db.client.connection.pending_requests") + assert pending.value == 3 + (timeouts,) = signals.points("db.client.connection.timeouts") + assert timeouts.value == 4 + # dispose(): новый пул читается на следующем сборе + engine.sync_engine.pool = _Pool(used=0, idle=0, waiting=0, timed_out=0) + (pending,) = signals.points("db.client.connection.pending_requests") + assert pending.value == 0 + + +async def test_worker_saturation(signals: Signals) -> None: + """Конкуренция 2: две доставки заняли места, третья ждёт; после всех — + ноль занятых и ожидающих.""" + load = telemetry.WorkerLoad() + telemetry.observe_worker(capacity=2, load=load) + release = asyncio.Event() + + class _Blocking: + async def handle(self, *, body: bytes, redelivered: bool) -> Any: + await release.wait() + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.READY, + ) + + slots = asyncio.Semaphore(2) + stop = asyncio.Event() + tasks = [ + asyncio.create_task( + worker_main._handle( + _Blocking, + _Delivery(), + slots, + stop, + load=load, + ), + ) + for _ in range(3) + ] + for _ in range(50): + await asyncio.sleep(0) + values = { + name: [point.value for point in signals.points(name)] + for name in ( + "messenger.worker.busy", + "messenger.worker.capacity", + "messenger.worker.waiting", + ) + } + assert values == { + "messenger.worker.busy": [2], + "messenger.worker.capacity": [2], + "messenger.worker.waiting": [1], + } + release.set() + await asyncio.gather(*tasks) + assert (load.busy, load.waiting) == (0, 0) + (busy,) = signals.points("messenger.worker.busy") + assert busy.value == 0 + + +def _snapshot(taken_ago: float) -> dataclasses.QueueSnapshotDTO: + from datetime import timedelta + + from src.utils.utc import utcnow + + taken_at = utcnow() - timedelta(seconds=taken_ago) + return dataclasses.QueueSnapshotDTO( + taken_at=taken_at, + scheduled=1, + outbox=2, + published=3, + processing=4, + oldest_created_at=taken_at - timedelta(seconds=42), + ) + + +def test_queue_gauges_fresh_and_stale(signals: Signals) -> None: + latest: list[dataclasses.QueueSnapshotDTO | None] = [None] + telemetry.observe_queue(queue=QUEUE, latest=lambda: latest[0]) + assert signals.points("messenger.queue.depth") == [] + latest[0] = _snapshot(31) + # снимок старше 30 с не отдаётся + assert signals.points("messenger.queue.depth") == [] + assert signals.points("messenger.queue.oldest_age") == [] + latest[0] = _snapshot(1) + depth = { + point.attributes["messenger.queue.stage"]: point.value + for point in signals.points("messenger.queue.depth") + } + assert depth == { + "scheduled": 1, + "outbox": 2, + "published": 3, + "processing": 4, + } + (age,) = signals.points("messenger.queue.oldest_age") + assert age.value == 42 + assert dict(age.attributes) == {"messaging.destination.name": QUEUE} + + +def test_queue_age_without_unfinished_is_zero() -> None: + snapshot = dataclasses.QueueSnapshotDTO( + taken_at=_snapshot(0).taken_at, + scheduled=0, + outbox=0, + published=0, + processing=0, + ) + depth, (age,) = metrics.queue_observations(snapshot, queue=QUEUE) + assert [item.value for item in depth] == [0, 0, 0, 0] + assert age.value == 0 + + +def _cgroup(root: Any, *, memory_max: str = "268435456") -> None: + (root / "cpu.stat").write_text( + "usage_usec 2500000\nuser_usec 2000000\nsystem_usec 500000\n", + ) + (root / "memory.current").write_text("1048576\n") + (root / "cpu.max").write_text("25000 100000\n") + (root / "memory.max").write_text(f"{memory_max}\n") + + +def test_container_metrics_from_cgroup(tmp_path: Any) -> None: + _cgroup(tmp_path) + signals = _start(cgroup_root=tmp_path) + try: + (cpu,) = signals.points("container.cpu.time") + (memory,) = signals.points("container.memory.usage") + (cpu_limit,) = signals.points("messenger.container.cpu.limit") + (memory_limit,) = signals.points("messenger.container.memory.limit") + finally: + signals.finish() + telemetry.remove_log_hooks() + assert cpu.value == 2.5 + assert memory.value == 1048576 + assert cpu_limit.value == 0.25 + assert memory_limit.value == 268435456 + + +def test_container_without_limit(tmp_path: Any) -> None: + from src.infra.telemetry import container + + _cgroup(tmp_path, memory_max="max") + (tmp_path / "cpu.max").write_text("max 100000\n") + assert container.memory_limit(tmp_path) is None + assert container.cpu_limit(tmp_path) is None + assert container.available(tmp_path) + + +def test_container_unavailable_one_record( + tmp_path: Any, + stdout: io.StringIO, +) -> None: + signals = _start(cgroup_root=tmp_path / "missing") + try: + assert signals.points("container.cpu.time") == [] + finally: + signals.finish() + telemetry.remove_log_hooks() + records = [ + record + for record in _records(stdout) + if record["event"] == "Container metrics are unavailable" + ] + assert len(records) == 1 + assert records[0]["level"] == "warning" + # запись до хуков журнала: в хранилище логов не уходит + assert signals.finished_logs() == [] + + +def test_relay_resource() -> None: + signals = _start(service="messenger-relay") + try: + with telemetry.producer_span( + queue=QUEUE, + job_type=ATTACHMENT_JOB_TYPE, + publication=_publication(), + ): + pass + (span,) = signals.finished_spans() + finally: + signals.finish() + telemetry.remove_log_hooks() + assert span.resource.attributes["service.name"] == "messenger-relay" + assert span.resource.attributes["service.instance.id"] == "test-instance" + + +@pytest.mark.parametrize( + ("headers", "expected"), + [ + (None, None), + ({}, None), + ({"traceparent": SAVED.traceparent}, (SAVED.traceparent, None)), + ( + { + "traceparent": SAVED.traceparent.encode(), + "tracestate": b"vendor=value", + }, + (SAVED.traceparent, "vendor=value"), + ), + ({"traceparent": "01-bad"}, None), + ({"traceparent": SAVED.traceparent.upper()}, None), + ({"traceparent": "\xff".encode("latin-1")}, None), + ({"traceparent": 42}, None), + ({"traceparent": SAVED.traceparent, "tracestate": "x" * 513}, None), + ], + ids=[ + "no-headers", + "empty", + "str", + "bytes", + "garbage", + "upper", + "not-ascii", + "number", + "long-tracestate", + ], +) +def test_delivery_headers( + headers: Any, + expected: tuple[str, str | None] | None, +) -> None: + from src.infra.broker.client import trace_context_from_headers + + context = trace_context_from_headers(headers) + if expected is None: + assert context is None + else: + assert context == dataclasses.TraceContextDTO(*expected) + + +def _loaded_modules(imports: str) -> set[str]: + """Модули SDK, экспортёра, protobuf и `requests` после импорта в + отдельном интерпретаторе с выключенной телеметрией.""" + import os + import subprocess + import sys + from pathlib import Path + + code = ( + "import json, sys\n" + f"import {imports}\n" + "prefixes = ('opentelemetry.sdk', 'opentelemetry.exporter',\n" + " 'google.protobuf', 'requests')\n" + "print(json.dumps(sorted(m for m in sys.modules\n" + " if m.startswith(prefixes))))\n" + ) + root = Path(__file__).resolve().parents[2] + env = {**os.environ, "TELEMETRY__ENABLED": "false"} + result = subprocess.run( # noqa: S603 + [sys.executable, "-c", code], + cwd=root, + env=env, + capture_output=True, + text=True, + check=True, + timeout=60, + ) + return set(json.loads(result.stdout.strip().splitlines()[-1])) + + +def test_sdk_modules_not_loaded_without_telemetry() -> None: + """Выключенная телеметрия — ни провайдеров SDK, ни экспортёра, ни + protobuf, ни HTTP-клиента экспортёра в памяти точек входа (решение 7). + + Исключение — модули метрик SDK, которые redis-py 8.1 сам загружает при + импорте (`redis.observability.providers`: проба «установлен ли SDK»): + точки входа не грузят ничего сверх `import redis.asyncio` (design, + «Уточнения apply»).""" + loaded = _loaded_modules( + "src.main, src.worker.main, src.relay.main, src.cleaner.main", + ) + forbidden = ( + "opentelemetry.exporter", + "opentelemetry.sdk.trace", + "opentelemetry.sdk._logs", + "google.protobuf", + "requests", + ) + assert not {name for name in loaded if name.startswith(forbidden)} + assert loaded <= _loaded_modules("redis.asyncio") diff --git a/service-tests/unit/test_worker_deliveries.py b/service-tests/unit/test_worker_deliveries.py index fe709f3..43a16b2 100644 --- a/service-tests/unit/test_worker_deliveries.py +++ b/service-tests/unit/test_worker_deliveries.py @@ -9,6 +9,11 @@ import asyncio from dataclasses import dataclass, field import pytest +from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter +from opentelemetry.sdk.metrics.export import InMemoryMetricReader +from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( + InMemorySpanExporter, +) from builders import attachment_dto, chat_dto, job_dto, user_dto from fakes import ( @@ -18,6 +23,7 @@ from fakes import ( FakeUnitOfWork, ) from src.core.ports.uow import Repositories +from src.infra import telemetry from src.schemas import dataclasses from src.schemas.enums import AttachmentStatus, AttachmentVariantName from src.schemas.jobs import build_job_body @@ -27,6 +33,8 @@ from src.worker import main as worker_main pytestmark = pytest.mark.anyio SOURCE = b"source-bytes" +TRACE_ID = "0af7651916cd43dd8448eb211c80319c" +SPAN_ID = "b7ad6b7169203331" class _YieldingUnitOfWork(FakeUnitOfWork): @@ -46,6 +54,7 @@ class _Delivery: body: bytes redelivered: bool = False settled: list[str] = field(default_factory=list) + trace_context: dataclasses.TraceContextDTO | None = None async def ack(self) -> None: self.settled.append("ack") @@ -144,3 +153,67 @@ async def test_concurrent_deliveries_have_own_unit_of_work( for job in jobs: attachment = database.attachments[job.attachment_id] assert attachment.status == AttachmentStatus.READY + + +async def test_delivery_context_reaches_consumer_span( + database: FakeDatabase, + storage: FakeObjectStorage, + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Контекст из заголовков доставки — родитель consumer span; итог + доставки — его атрибуты и время до готовности (design change + `job-trace-propagation`, решения 2, 8).""" + monkeypatch.setattr( + worker_main, + "SqlAlchemyUnitOfWork", + lambda _factory, **_: FakeUnitOfWork(database), + ) + spans = InMemorySpanExporter() + metrics = InMemoryMetricReader() + assert telemetry.start_process_telemetry( + "messenger-worker", + exporters=telemetry.Exporters( + spans=spans, + metrics=metrics, + logs=InMemoryLogRecordExporter(), + ), + ) + stop = asyncio.Event() + make_service = worker_main.service_factory( + object(), + storage=storage, + renderer=FakeImageRenderer(database, _rendered()), + stop=stop, + ) + job = await _queued_job(database, storage) + delivery = _Delivery( + body=build_job_body(job, attempt=1), + trace_context=dataclasses.TraceContextDTO( + traceparent=f"00-{TRACE_ID}-{SPAN_ID}-01", + ), + ) + try: + await worker_main._handle( + make_service, + delivery, + asyncio.Semaphore(1), + stop, + ) + data = metrics.get_metrics_data() + finally: + for thread in telemetry.begin_shutdown(): + thread.join(5) + telemetry.remove_log_hooks() + assert delivery.settled == ["ack"] + (span,) = spans.get_finished_spans() + assert format(span.context.trace_id, "032x") == TRACE_ID + assert format(span.parent.span_id, "016x") == SPAN_ID + assert span.attributes["messenger.job.outcome"] == "ready" + assert span.attributes["messenger.job.attempt"] == 1 + names = { + metric.name + for resource in data.resource_metrics + for scope in resource.scope_metrics + for metric in scope.metrics + } + assert "messenger.job.time_to_ready" in names diff --git a/src/api/dependencies.py b/src/api/dependencies.py index e83bdae..8089f35 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -29,6 +29,7 @@ from src.core.services import ( SessionService, UserService, ) +from src.infra import telemetry from src.infra.cache.instance import cache from src.infra.db import ping from src.infra.db.scope import deadline_scope @@ -124,6 +125,20 @@ AttachmentServiceDep = Annotated[ ] +async def get_trace_context() -> dataclasses.TraceContextDTO | None: + """Контекст W3C текущего span — server span запроса — для задания + загрузки (design change `job-trace-propagation`, решение 4); без + телеметрии — `None`. Сервис телеметрию не импортирует: контекст приходит + значением, как `owner_id`.""" + return telemetry.current_trace_context() + + +TraceContextDep = Annotated[ + dataclasses.TraceContextDTO | None, + Depends(get_trace_context), +] + + # схемы basicAuth и bearerAuth из contracts/openapi.json: объявлены в # /openapi.json и дают кнопку Authorize в /docs. auto_error=False — нет # заголовка или схема чужая даёт None, а 401 в формате контракта бросает diff --git a/src/api/routers/v1/attachment.py b/src/api/routers/v1/attachment.py index 13f3e1d..c6eb428 100644 --- a/src/api/routers/v1/attachment.py +++ b/src/api/routers/v1/attachment.py @@ -15,7 +15,11 @@ from fastapi.responses import StreamingResponse from starlette.background import BackgroundTask from starlette.requests import ClientDisconnect -from src.api.dependencies import AttachmentServiceDep, CurrentUser +from src.api.dependencies import ( + AttachmentServiceDep, + CurrentUser, + TraceContextDep, +) from src.api.schemas import Attachment, DisplayFilename, UuidIn from src.core import exceptions from src.schemas.enums import AttachmentVariantName, ImageType @@ -112,9 +116,12 @@ async def upload_attachment( filename: FilenameQuery, request: Request, attachments: AttachmentServiceDep, + trace_context: TraceContextDep, ) -> Attachment: - """202 — оригинал в staging, метаданные и задание в PostgreSQL, брокер - подтвердил сообщение; итог клиент узнаёт по метаданным. + """202 — оригинал в staging, вложение `queued` и задание в PostgreSQL + одной транзакцией; сообщение публикует relay, итог клиент узнаёт по + метаданным. Контекст server span загрузки сохраняется в задании (design + change `job-trace-propagation`, решение 4). Тело не читается, пока не пройдены вход, параметры, членство, `Content-Type` и `Content-Length` (спек «Порядок проверок загрузки»). @@ -129,6 +136,7 @@ async def upload_attachment( media_type=_media_type(request), content_length=_content_length(request), body=_body(request), + trace_context=trace_context, ) return Attachment.model_validate(attachment) diff --git a/src/config/settings.py b/src/config/settings.py index df2a369..70a4d85 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -457,12 +457,14 @@ class Relay(BaseModel): class Telemetry(BaseModel): - """Телеметрия API и worker (design change `otel-telemetry`, решение 8). + """Телеметрия API, worker и relay (design change `otel-telemetry`, решение + 8; relay — `job-trace-propagation`, решение 7). Включает её стенд compose окружением `TELEMETRY__ENABLED` и - `TELEMETRY__OTLP_ENDPOINT` у реплик API и worker; интервалы и очереди — из - `config.toml`. Переменные `OTEL_*` настройками не являются: SDK собирается - только из этих полей. Relay, уборщик и миграции секцию не читают. + `TELEMETRY__OTLP_ENDPOINT` у реплик API, worker и relay; интервалы и + очереди — из `config.toml`. Переменные `OTEL_*` настройками не являются: SDK + собирается только из этих полей. Уборщик, миграции и команда replay секцию + не применяют. """ # выключена — ни провайдеров SDK, ни отправки, ни полей трассы в журнале diff --git a/src/core/ports/attachment_job.py b/src/core/ports/attachment_job.py index e9a8056..b117e15 100644 --- a/src/core/ports/attachment_job.py +++ b/src/core/ports/attachment_job.py @@ -18,7 +18,9 @@ class AbstractAttachmentJobRepository(abc.ABC): *, job: dataclasses.AttachmentJobDTO, ) -> dataclasses.AttachmentJobDTO: - """Новая работа; вложение становится `queued` в той же транзакции.""" + """Новая работа; вложение становится `queued` в той же транзакции. + `traceparent` и `tracestate` задания сохраняются как есть и читаются + всеми выборками заданий.""" @abc.abstractmethod async def lock_job( @@ -108,6 +110,20 @@ class AbstractAttachmentJobRepository(abc.ABC): незавершённых не меньше `limit`. Цена не растёт с превышением, само число выше `limit` неточно.""" + @abc.abstractmethod + async def queue_snapshot( + self, + *, + now: datetime, + ) -> dataclasses.QueueSnapshotDTO: + """Незавершённые задания по стадиям на `now`: `scheduled` — `queued` + без отметки публикации со сроком (`next_attempt_at`, иначе + `created_at`) позже `now`, `outbox` — то же со сроком не позже `now`, + `published` — `queued` с отметкой, `processing` — идёт попытка. Сумма + стадий — все `queued` и `processing`. `oldest_created_at` — + наименьший `created_at` среди них, `None` — незавершённых нет; + `taken_at` = `now`.""" + @abc.abstractmethod async def mark_published( self, diff --git a/src/core/repos/attachment_job.py b/src/core/repos/attachment_job.py index 644a92e..814630c 100644 --- a/src/core/repos/attachment_job.py +++ b/src/core/repos/attachment_job.py @@ -55,6 +55,8 @@ _JOB_COLUMNS = ( AttachmentJob.lease_expires_at, AttachmentJob.published_at, AttachmentJob.finished_at, + AttachmentJob.traceparent, + AttachmentJob.tracestate, ) # срок задания: то же выражение, что в индексе ix_attachment_jobs_outbox @@ -108,6 +110,8 @@ class SqlAlchemyAttachmentJobRepository(AbstractAttachmentJobRepository): attempt=job.attempt, created_at=job.created_at, updated_at=job.updated_at, + traceparent=job.traceparent, + tracestate=job.tracestate, ), ) return job @@ -295,6 +299,64 @@ class SqlAlchemyAttachmentJobRepository(AbstractAttachmentJobRepository): statement = select(counts[0] + counts[1] + counts[2]) return (await self._session.execute(statement)).scalar_one() + async def queue_snapshot( + self, + *, + now: datetime, + ) -> dataclasses.QueueSnapshotDTO: + """Стадии незавершённых заданий и приём старейшего — одним выражением + (design change `job-trace-propagation`, решение 9). Каждый подзапрос + совпадает с условием своего частичного индекса (outbox по выражению + срока, опубликованные, аренда); состояние — константой, иначе общий + план — Seq Scan. Незавершённых ограниченно (предел приёма).""" + published = (_queued(), AttachmentJob.published_at.is_not(None)) + processing = ( + AttachmentJob.state + == literal( + AttachmentJobState.PROCESSING.value, + literal_execute=True, + ), + ) + + def count(*condition: ColumnElement[bool]) -> ColumnElement[int]: + return ( + select(func.count()) + .select_from(AttachmentJob) + .where(*condition) + .scalar_subquery() + ) + + def oldest( + *condition: ColumnElement[bool], + ) -> ColumnElement[datetime]: + return ( + select(func.min(AttachmentJob.created_at)) + .where(*condition) + .scalar_subquery() + ) + + statement = select( + count(*_outbox_condition(), now < _DUE_AT).label("scheduled"), + count(*_outbox_condition(), now >= _DUE_AT).label("outbox"), + count(*published).label("published"), + count(*processing).label("processing"), + # LEAST пропускает NULL: пустая группа возраст не задаёт + func.least( + oldest(*_outbox_condition()), + oldest(*published), + oldest(*processing), + ).label("oldest_created_at"), + ) + row = (await self._session.execute(statement)).one() + return dataclasses.QueueSnapshotDTO( + taken_at=now, + scheduled=row.scheduled, + outbox=row.outbox, + published=row.published, + processing=row.processing, + oldest_created_at=row.oldest_created_at, + ) + async def mark_published( self, *, diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py index 2a7895d..ac14890 100644 --- a/src/core/services/attachment.py +++ b/src/core/services/attachment.py @@ -90,10 +90,14 @@ class AttachmentService: media_type: str | None, content_length: int | None, body: AsyncIterator[bytes], + trace_context: dataclasses.TraceContextDTO | None = None, ) -> dataclasses.AttachmentFullDTO: """Приём оригинала; 202 — оригинал в staging, вложение `queued` и его задание зафиксированы. Брокера в пути запроса нет: намерение до него доводит relay (design change `pipeline-reliability`, решение 1). + `trace_context` — контекст W3C запроса загрузки от слоя API: он + пишется в задание вместе с намерением (design change + `job-trace-propagation`, решение 4), `None` — без контекста. Порядок проверок — спек «Порядок проверок загрузки»: одним блоком и без места членство (404), `Content-Type` (415), `Content-Length` (413) @@ -160,6 +164,7 @@ class AttachmentService: body=body, started=started, waited_ms=waited_ms, + trace_context=trace_context, log=log, ) except exceptions.UploadsBusy: @@ -181,6 +186,7 @@ class AttachmentService: body: AsyncIterator[bytes], started: float, waited_ms: int, + trace_context: dataclasses.TraceContextDTO | None, log: AbstractLogger, ) -> dataclasses.AttachmentFullDTO: """Путь загрузки на занятом месте: тело, проверка, запись.""" @@ -256,6 +262,7 @@ class AttachmentService: queued, job = await self._mark_queued( attachment_id=attachment_id, staging=staging, + trace_context=trace_context, log=log, ) log.info( @@ -275,6 +282,7 @@ class AttachmentService: *, attachment_id: UUID, staging: str, + trace_context: dataclasses.TraceContextDTO | None, log: AbstractLogger, ) -> tuple[dataclasses.AttachmentFullDTO, dataclasses.AttachmentJobDTO]: """`pending` → `queued` и задание одной транзакцией: устойчивое @@ -307,6 +315,16 @@ class AttachmentService: attempt=0, created_at=now, updated_at=now, + traceparent=( + None + if trace_context is None + else trace_context.traceparent + ), + tracestate=( + None + if trace_context is None + else trace_context.tracestate + ), ), ) commit_sent = True diff --git a/src/core/services/attachment_processing.py b/src/core/services/attachment_processing.py index c1146d9..fbabb33 100644 --- a/src/core/services/attachment_processing.py +++ b/src/core/services/attachment_processing.py @@ -4,8 +4,10 @@ Design change `async-attachments`, решения 2 и 7; `pipeline-reliability` 3, 4, 6, 7. `handle` разбирает сообщение, берёт задание по таблице claim, публикует оригинал из staging в конечный ключ, получает варианты от процесса обработки, пишет их объекты и одной транзакцией фиксирует `ready`. Итог — исход доставки -(`JobDeliveryOutcome`, design change `otel-telemetry`, решение 11): из него -`src/worker/main.py` выводит действие с сообщением и пишет метрику. +(`JobDeliveryOutcome`, design change `otel-telemetry`, решение 11) с попыткой, +причиной, кодом ошибки и временем до готовности (`JobDeliveryResultDTO`, design +change `job-trace-propagation`, решение 8): из него `src/worker/main.py` выводит +действие с сообщением и пишет span и метрики. Сообщение — подсказка, истина в строке задания. Worker не публикует: следующую попытку и возврат зависшей публикует relay. Дубль при живой аренде и сообщение @@ -21,6 +23,7 @@ import hashlib import io import random import time +from dataclasses import replace from datetime import timedelta from pydantic import ValidationError @@ -64,6 +67,20 @@ def retry_delay(*, attempt: int, base: float, maximum: float) -> float: return random.uniform(delay / 2, delay) # noqa: S311 +def _skipped() -> dataclasses.JobDeliveryResultDTO: + """Сообщение без работы; номер попытки подставляет `handle` из + сообщения.""" + return dataclasses.JobDeliveryResultDTO(outcome=JobDeliveryOutcome.SKIPPED) + + +def _reason(code: str | None) -> AttachmentJobReason | None: + """Причина из `last_error_code`; незнакомое значение — без причины.""" + try: + return None if code is None else AttachmentJobReason(code) + except ValueError: + return None + + class _PermanentError(Exception): """Повтор не исправит: сразу `failed`.""" @@ -101,15 +118,18 @@ class AttachmentProcessingService: *, body: bytes, redelivered: bool, - ) -> JobDeliveryOutcome: - """Одна доставка и её исход; отказ PostgreSQL — пауза и возврат в - очередь.""" + ) -> dataclasses.JobDeliveryResultDTO: + """Одна доставка и её итог (design change `job-trace-propagation`, + решение 8): исход, попытка, причина и код ошибки, время до готовности; + отказ PostgreSQL — пауза и возврат в очередь.""" try: message = AttachmentJobMessage.model_validate_json(body) except ValidationError: # содержимое сообщения и текст ошибки с его значениями — не в журнал logger.error("Dropped malformed job message", size_bytes=len(body)) - return JobDeliveryOutcome.DROPPED + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.DROPPED, + ) # задача доставки своя, контекст не уходит к другим заданиям http_request_id.set(str(message.job_id)) log = logger.bind( @@ -117,7 +137,7 @@ class AttachmentProcessingService: attachment_id=message.attachment_id, ) try: - return await self._run( + result = await self._run( message=message, redelivered=redelivered, log=log, @@ -127,7 +147,14 @@ class AttachmentProcessingService: # Причину уже записала единица работы log.warning("Job waits for database") await self._pause() - return JobDeliveryOutcome.REQUEUED + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.REQUEUED, + attempt=message.attempt, + ) + if result.outcome == JobDeliveryOutcome.SKIPPED: + # без попытки: номер — из сообщения + return replace(result, attempt=message.attempt) + return result async def _run( self, @@ -135,9 +162,9 @@ class AttachmentProcessingService: message: AttachmentJobMessage, redelivered: bool, log: AbstractLogger, - ) -> JobDeliveryOutcome: + ) -> dataclasses.JobDeliveryResultDTO: claim = await self._claim(message=message, log=log) - if isinstance(claim, JobDeliveryOutcome): + if isinstance(claim, dataclasses.JobDeliveryResultDTO): return claim job, attachment, queue_wait_ms = claim log = log.bind(attempt=job.attempt) @@ -214,8 +241,19 @@ class AttachmentProcessingService: render_memory_limit_applied=rendered.memory_limit_applied, duration_ms=round((time.monotonic() - started) * 1000), ) - return JobDeliveryOutcome.READY - return JobDeliveryOutcome.SKIPPED + # от устойчивого приёма (задание записано вместе с queued) до + # фиксации ready; после replay приём — действие оператора + time_to_ready = ( + (utcnow() - job.created_at).total_seconds() + if job.attempt_base == 0 + else None + ) + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.READY, + attempt=job.attempt, + time_to_ready_seconds=time_to_ready, + ) + return _skipped() async def _claim( self, @@ -228,7 +266,7 @@ class AttachmentProcessingService: dataclasses.AttachmentFullDTO, int | None, ] - | JobDeliveryOutcome + | dataclasses.JobDeliveryResultDTO ): """Взять задание под блокировкой (таблица решения 3) или вернуть итог без попытки. Сообщение без работы подтверждается: живую попытку ведёт её @@ -237,13 +275,13 @@ class AttachmentProcessingService: job = await self.uow.jobs.lock_job(job_id=message.job_id) if job is None or job.attachment_id != message.attachment_id: log.info("Skipped job message", reason="unknown") - return JobDeliveryOutcome.SKIPPED + return _skipped() if job.state == AttachmentJobState.SUCCEEDED: await self._check_finished(job=job, log=log) - return JobDeliveryOutcome.SKIPPED + return _skipped() if job.state == AttachmentJobState.FAILED: log.info("Skipped job message", reason="finished") - return JobDeliveryOutcome.SKIPPED + return _skipped() now = utcnow() if ( job.state == AttachmentJobState.QUEUED @@ -252,14 +290,14 @@ class AttachmentProcessingService: and job.next_attempt_at > now ): log.info("Skipped job message", reason="not_due") - return JobDeliveryOutcome.SKIPPED + return _skipped() if ( job.state == AttachmentJobState.PROCESSING and job.lease_expires_at is not None and job.lease_expires_at > now ): log.info("Skipped job message", reason="busy") - return JobDeliveryOutcome.SKIPPED + return _skipped() if self._budget_spent(job): # попытка потеряна при исчерпанном бюджете: сообщение пришло, а # попытка уже посчитана @@ -275,12 +313,17 @@ class AttachmentProcessingService: reason=job.last_error_code, attempt=job.attempt, ) - return JobDeliveryOutcome.FAILED + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.FAILED, + attempt=job.attempt, + reason=_reason(job.last_error_code), + error_code=AttachmentErrorCode.RETRY_EXHAUSTED, + ) taken = await self._start_attempt(job=job, now=now) await self.uow.commit() if taken is None: log.info("Skipped job message", reason="unknown") - return JobDeliveryOutcome.SKIPPED + return _skipped() started, attachment = taken queue_wait_ms = ( None @@ -505,13 +548,13 @@ class AttachmentProcessingService: error_code: AttachmentErrorCode, reason: AttachmentJobReason, log: AbstractLogger, - ) -> JobDeliveryOutcome: + ) -> dataclasses.JobDeliveryResultDTO: """`failed` своей попытки; задание уже ведёт другая — без записи.""" async with self.uow: locked = await self.uow.jobs.lock_job(job_id=job.id) if not self._own_attempt(locked, job=job): log.info("Skipped job message", reason="superseded") - return JobDeliveryOutcome.SKIPPED + return _skipped() written = await self._write_failed( job=job, error_code=error_code, @@ -519,13 +562,18 @@ class AttachmentProcessingService: ) await self.uow.commit() if not written: - return JobDeliveryOutcome.SKIPPED + return _skipped() log.warning( "Attachment failed", error_code=error_code.value, reason=reason.value, ) - return JobDeliveryOutcome.FAILED + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.FAILED, + attempt=job.attempt, + reason=reason, + error_code=error_code, + ) @staticmethod def _own_attempt( @@ -545,7 +593,7 @@ class AttachmentProcessingService: job: dataclasses.AttachmentJobDTO, reason: AttachmentJobReason, log: AbstractLogger, - ) -> JobDeliveryOutcome: + ) -> dataclasses.JobDeliveryResultDTO: """Временная ошибка: `queued` со сроком следующей попытки и ACK; её сообщение опубликует relay, пауза места конкуренции не занимает. Попытки исчерпаны — `failed`.""" @@ -574,7 +622,7 @@ class AttachmentProcessingService: ) if not own: log.info("Skipped job message", reason="superseded") - return JobDeliveryOutcome.SKIPPED + return _skipped() await self.uow.attachments.return_to_queued( attachment_id=job.attachment_id, updated_at=now, @@ -586,7 +634,11 @@ class AttachmentProcessingService: delay_seconds=round(delay, 3), next_attempt_at=next_attempt_at.isoformat(), ) - return JobDeliveryOutcome.RETRY + return dataclasses.JobDeliveryResultDTO( + outcome=JobDeliveryOutcome.RETRY, + attempt=job.attempt, + reason=reason, + ) async def _pause(self) -> None: """Пауза перед возвратом сообщения при отказе PostgreSQL; её прерывает diff --git a/src/core/services/attachment_relay.py b/src/core/services/attachment_relay.py index 82ea71c..da6524a 100644 --- a/src/core/services/attachment_relay.py +++ b/src/core/services/attachment_relay.py @@ -36,6 +36,32 @@ def _never() -> bool: return False +def publication( + job: dataclasses.AttachmentJobDTO, +) -> dataclasses.JobPublicationDTO: + """Элемент публикации из строки задания (design change + `job-trace-propagation`, решение 3): номер следующей попытки, признак + replay (`attempt_base > 0`), причина повтора — прежний `last_error_code`, + контекст загрузки из колонок задания или `None`.""" + trace_context = ( + None + if job.traceparent is None + else dataclasses.TraceContextDTO( + traceparent=job.traceparent, + tracestate=job.tracestate, + ) + ) + attempt = job.attempt + 1 + return dataclasses.JobPublicationDTO( + job_id=job.id, + body=build_job_body(job, attempt=attempt), + attempt=attempt, + replayed=job.attempt_base > 0, + retry_reason=job.last_error_code, + trace_context=trace_context, + ) + + class AttachmentRelayService: """`uow` — единица работы процесса relay, `publisher` — издатель с подтверждением. Состояние предела — только для записи на его смену.""" @@ -175,10 +201,7 @@ class AttachmentRelayService: if not jobs: return 0, 0, backlog, 0 confirmed = await self.publisher.publish_many( - [ - (job.id, build_job_body(job, attempt=job.attempt + 1)) - for job in jobs - ], + [publication(job) for job in jobs], ) if confirmed: await self.uow.jobs.mark_published( @@ -193,6 +216,13 @@ class AttachmentRelayService: len(jobs), ) + async def queue_snapshot(self) -> dataclasses.QueueSnapshotDTO: + """Незавершённые задания по стадиям и приём старейшего — один блок + (design change `job-trace-propagation`, решение 9). Отказ PostgreSQL — + `ServiceUnavailable`, причину уже записала единица работы.""" + async with self.uow: + return await self.uow.jobs.queue_snapshot(now=utcnow()) + def _note_backlog( self, *, diff --git a/src/infra/broker/client.py b/src/infra/broker/client.py index e233cf4..f428f23 100644 --- a/src/infra/broker/client.py +++ b/src/infra/broker/client.py @@ -22,8 +22,9 @@ Design change `async-attachments`, решение 5. Соединение отк """ import asyncio +import re import time -from collections.abc import AsyncIterator, Sequence +from collections.abc import AsyncIterator, Mapping, Sequence from dataclasses import dataclass from typing import Any from uuid import UUID @@ -38,11 +39,22 @@ from aio_pika.abc import ( from src.config.settings import Broker as BrokerSettings from src.core.exceptions import BrokerUnavailable +from src.infra import telemetry from src.infra.logger import AbstractLogger, get_logger -from src.utils.constants import ATTACHMENT_QUEUE_SUFFIX +from src.schemas.dataclasses import JobPublicationDTO, TraceContextDTO +from src.utils.constants import ( + ATTACHMENT_JOB_TYPE, + ATTACHMENT_QUEUE_SUFFIX, + TRACE_HEADER_TRACEPARENT, + TRACE_HEADER_TRACESTATE, + TRACEPARENT_PATTERN, + TRACESTATE_MAX_LENGTH, +) logger: AbstractLogger = get_logger().bind(module="broker") +_TRACEPARENT = re.compile(TRACEPARENT_PATTERN) + # закрытие прежнего соединения в фоне: при замороженном брокере оно само # зависло бы _BACKGROUND_CLOSE_TIMEOUT_SECONDS = 5 @@ -100,12 +112,13 @@ class JobPublisher: async def publish_many( self, - items: Sequence[tuple[UUID, bytes]], + items: Sequence[JobPublicationDTO], ) -> set[UUID]: - """Пакет `(id, тело)` с подтверждением под одним сроком. Возвращает + """Пакет публикаций с подтверждением под одним сроком. Возвращает подтверждённые `id`. Подмножество — ошибка уже записана, соединение сброшено: подтверждённые до срока отмечаются, исход остальных неизвестен, - и их опубликует следующий проход (возможен дубль).""" + и их опубликует следующий проход (возможен дубль). Span producer — на + каждое сообщение (design change `job-trace-propagation`, решение 3).""" started = time.monotonic() channel: AbstractChannel | None = None confirmed: set[UUID] = set() @@ -118,9 +131,9 @@ class JobPublisher: channel = await self._get_channel() tasks = { asyncio.create_task( - self._publish_one(channel, body, job_id), - ): job_id - for job_id, body in items + self._publish_one(channel, item), + ): item.job_id + for item in items } remaining = deadline - asyncio.get_running_loop().time() done, pending = await asyncio.wait( @@ -155,21 +168,29 @@ class JobPublisher: async def _publish_one( self, channel: AbstractChannel, - body: bytes, - job_id: UUID, + item: JobPublicationDTO, ) -> None: """Сообщение persistent в очередь через default exchange, `mandatory`: - без маршрута брокер вернёт его, и это ошибка.""" - await channel.default_exchange.publish( - aio_pika.Message( - body, - content_type="application/json", - delivery_mode=aio_pika.DeliveryMode.PERSISTENT, - message_id=str(job_id), - ), - routing_key=self.queue, - mandatory=True, - ) + без маршрута брокер вернёт его, и это ошибка. Единственная точка + публикации: span producer под сохранённым контекстом задания, его + контекст — заголовки `traceparent` и `tracestate` (carrier); тело + прежнее. Span заканчивается после подтверждения брокером.""" + with telemetry.producer_span( + queue=self.queue, + job_type=ATTACHMENT_JOB_TYPE, + publication=item, + ) as headers: + await channel.default_exchange.publish( + aio_pika.Message( + item.body, + content_type="application/json", + delivery_mode=aio_pika.DeliveryMode.PERSISTENT, + message_id=str(item.job_id), + headers=headers or None, + ), + routing_key=self.queue, + mandatory=True, + ) async def ready_messages(self) -> int: """Готовые сообщения очереди: активное объявление, которое создаёт ещё и @@ -272,13 +293,46 @@ class JobPublisher: await asyncio.gather(*self._close_tasks, return_exceptions=True) +def _header_text(value: object) -> str | None: + """Строка заголовка: pamqp отдаёт `str`, не UTF-8 — `bytes`; принимается + только ASCII.""" + if isinstance(value, bytes): + try: + return value.decode("ascii") + except UnicodeDecodeError: + return None + return value if isinstance(value, str) else None + + +def trace_context_from_headers( + headers: Mapping[str, object] | None, +) -> TraceContextDTO | None: + """Контекст W3C из заголовков сообщения (design change + `job-trace-propagation`, решения 1, 6): `traceparent` по шаблону версии + `00`, `tracestate` не длиннее предела, иначе `None` — новая трасса, а не + ошибка. Тело и его разбор заголовки не меняют.""" + if not headers: + return None + traceparent = _header_text(headers.get(TRACE_HEADER_TRACEPARENT)) + if traceparent is None or _TRACEPARENT.fullmatch(traceparent) is None: + return None + tracestate = _header_text(headers.get(TRACE_HEADER_TRACESTATE)) + if tracestate is not None and not ( + 0 < len(tracestate) <= TRACESTATE_MAX_LENGTH + ): + return None + return TraceContextDTO(traceparent=traceparent, tracestate=tracestate) + + @dataclass(slots=True) class JobDelivery: - """Сообщение от брокера; подтверждает его `src/worker/main.py`.""" + """Сообщение от брокера; подтверждает его `src/worker/main.py`. + `trace_context` — контекст создания из заголовков или `None`.""" body: bytes redelivered: bool _message: AbstractIncomingMessage + trace_context: TraceContextDTO | None = None async def ack(self) -> None: await self._settle(self._message.ack()) @@ -366,6 +420,7 @@ class JobConsumer: body=message.body, redelivered=bool(message.redelivered), _message=message, + trace_context=trace_context_from_headers(message.headers), ) async def aclose(self) -> None: diff --git a/src/infra/db/engine.py b/src/infra/db/engine.py index 96fe95c..1ba27b7 100644 --- a/src/infra/db/engine.py +++ b/src/infra/db/engine.py @@ -8,6 +8,7 @@ import asyncio from typing import Any import asyncpg +from sqlalchemy import exc as sa_exc from sqlalchemy import text from sqlalchemy.ext.asyncio import ( AsyncEngine, @@ -15,6 +16,7 @@ from sqlalchemy.ext.asyncio import ( async_sessionmaker, create_async_engine, ) +from sqlalchemy.pool import AsyncAdaptedQueuePool from sqlalchemy.util import await_ from src.config.settings import Database @@ -47,6 +49,43 @@ class BoundedCloseConnection(asyncpg.Connection): transport.abort() +class CountingQueuePool(AsyncAdaptedQueuePool): + """Пул engine со счётом запросов соединения, которые сейчас ждут, и + отказов по сроку (design change `job-trace-propagation`, решение 10). + + Публичный `Pool.connect()` — ожидание места, открытие соединения и + проверка при выдаче; числа ожидающих `QueuePool` не отдаёт. `dispose()` + создаёт новый пул того же класса (`recreate`), поэтому счёт — свойство + пула, а не подмена метода экземпляра. Фабрика о телеметрии не знает: числа + читают метрики `db.client.connection.*`. Опирается на `Pool.connect()` и + `QueuePool`, SQLAlchemy закреплён `<2.2`; смену ловит `make + service_test_db` (`test_pool_counts_*`). + """ + + def __init__(self, *args: Any, **kwargs: Any) -> None: + super().__init__(*args, **kwargs) + self._pending = 0 + self._timeouts = 0 + + def connect(self) -> Any: + self._pending += 1 + try: + return super().connect() + except sa_exc.TimeoutError: + self._timeouts += 1 + raise + finally: + self._pending -= 1 + + def pending(self) -> int: + """Запросы соединения, которые сейчас ждут места или открытия.""" + return self._pending + + def timeouts(self) -> int: + """Отказы по сроку ожидания пула с создания пула.""" + return self._timeouts + + def _ping_once(dbapi_connection: Any) -> bool: """Проверка соединения при выдаче одним обменом `;`. @@ -80,6 +119,7 @@ def create_engine(database: Database) -> AsyncEngine: ) engine = create_async_engine( database.url, + poolclass=CountingQueuePool, pool_size=database.pool_size, max_overflow=database.max_overflow, pool_timeout=database.pool_timeout_seconds, diff --git a/src/infra/db/models/attachment.py b/src/infra/db/models/attachment.py index 6746838..64efd46 100644 --- a/src/infra/db/models/attachment.py +++ b/src/infra/db/models/attachment.py @@ -144,6 +144,17 @@ class AttachmentJob(Base): "attempt_base BETWEEN 0 AND attempt", name="attempt_base", ), + # контекст W3C загрузки (design change job-trace-propagation, решение + # 4): шаблон contracts/jobs.schema.json; в ревизии — NOT VALID + CheckConstraint( + "traceparent ~ '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$'", + name="traceparent", + ), + CheckConstraint( + "tracestate IS NULL OR (traceparent IS NOT NULL " + "AND char_length(tracestate) BETWEEN 1 AND 512)", + name="tracestate", + ), # Autogenerate условие и выражение не видит; в ревизии — CONCURRENTLY. # Запросы пишут state константой, иначе общий план подготовленного # выражения индекс не возьмёт @@ -202,6 +213,10 @@ class AttachmentJob(Base): finished_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), ) + # контекст server span загрузки; NULL — строка прежней версии или реплика + # без телеметрии (design change job-trace-propagation, решение 4) + traceparent: Mapped[str | None] = mapped_column(Text) + tracestate: Mapped[str | None] = mapped_column(Text) class AttachmentJobReplay(Base): diff --git a/src/infra/logger.py b/src/infra/logger.py index 5039d00..2b7f0fa 100644 --- a/src/infra/logger.py +++ b/src/infra/logger.py @@ -20,6 +20,7 @@ from structlog.typing import EventDict, WrappedLogger from src.config import settings from src.utils.constants import ( + DB_POOL_LOGGER, TELEMETRY_SDK_LOG_WINDOW_SECONDS, TELEMETRY_SDK_LOGGER_PREFIX, ) @@ -280,6 +281,12 @@ def configure_logger() -> None: # протокола с телами сообщений и строку подключения "aio_pika": {"level": "WARNING"}, "aiormq": {"level": "WARNING"}, + # пул engine (design change job-trace-propagation, решение + # 10): SQLAlchemy называет логгер пула по его классу, а класс + # живёт в src — без этой строки «Pool recreating» и «Pool + # disposed» шли бы INFO, как у логгера src; уровень — прежний, + # как у пула SQLAlchemy под root + DB_POOL_LOGGER: {"level": "WARNING"}, }, }, ) diff --git a/src/infra/telemetry/__init__.py b/src/infra/telemetry/__init__.py index ca7bf8f..a4de81e 100644 --- a/src/infra/telemetry/__init__.py +++ b/src/infra/telemetry/__init__.py @@ -1,15 +1,16 @@ -"""Телеметрия процессов API и worker (design change `otel-telemetry`). +"""Телеметрия процессов API, worker и relay (design change `otel-telemetry`, +`job-trace-propagation`). Правила — `.claude/rules/telemetry.md`. Без включённой телеметрии все вызовы -ничего не делают: ни провайдеров, ни хуков журнала, ни обращений к Collector. +ничего не делают: ни провайдеров, ни хуков журнала, ни обращений к Collector, +ни модулей SDK в памяти (их загружает только `core.start()`). """ from src.infra.telemetry.core import ( Exporters, - JobObservation, begin_shutdown, child_span, - consumer_span, + current_trace_context, finish_request, http_method, is_enabled, @@ -21,21 +22,36 @@ from src.infra.telemetry.core import ( ) from src.infra.telemetry.db import commit_span, instrument_engine from src.infra.telemetry.logs import install_log_hooks, remove_log_hooks +from src.infra.telemetry.messaging import ( + JobObservation, + consumer_span, + producer_span, +) +from src.infra.telemetry.metrics import ( + WorkerLoad, + observe_queue, + observe_worker, +) from src.infra.telemetry.setup import start_process_telemetry __all__ = [ "Exporters", "JobObservation", + "WorkerLoad", "begin_shutdown", "child_span", "commit_span", "consumer_span", + "current_trace_context", "finish_request", "http_method", "install_log_hooks", "instrument_engine", "is_enabled", "mark_error", + "observe_queue", + "observe_worker", + "producer_span", "remove_log_hooks", "remove_otel_environment", "server_span", diff --git a/src/infra/telemetry/container.py b/src/infra/telemetry/container.py new file mode 100644 index 0000000..ed3ca51 --- /dev/null +++ b/src/infra/telemetry/container.py @@ -0,0 +1,112 @@ +"""CPU и память контейнера по его cgroup v2 изнутри (design change +`job-trace-propagation`, решение 12). + +Без сокета Docker: доступ к API Docker равен root на ВМ. Файлы читает callback +сбора метрик (микросекунды), корень cgroup — параметр, по умолчанию +`CGROUP_ROOT`: быстрые тесты дают временный каталог. У worker cgroup включает +процессы обработки. Значение `max` в `cpu.max` и `memory.max` — предела нет, +точки нет. +""" + +from collections.abc import Iterable +from pathlib import Path +from typing import Any + +from opentelemetry.metrics import Meter, Observation + +from src.utils.constants import ( + METRIC_CONTAINER_CPU_LIMIT, + METRIC_CONTAINER_CPU_TIME, + METRIC_CONTAINER_MEMORY_LIMIT, + METRIC_CONTAINER_MEMORY_USAGE, +) + +_USEC = 1_000_000 +_NO_LIMIT = "max" + + +def _read(path: Path) -> str | None: + try: + return path.read_text().strip() + except (OSError, ValueError): + return None + + +def cpu_seconds(root: Path) -> float | None: + """`usage_usec` из `cpu.stat` в секундах.""" + text = _read(root / "cpu.stat") + if text is None: + return None + for line in text.splitlines(): + name, _, value = line.partition(" ") + if name == "usage_usec" and value.strip().isdigit(): + return int(value) / _USEC + return None + + +def memory_bytes(root: Path) -> int | None: + text = _read(root / "memory.current") + return int(text) if text is not None and text.isdigit() else None + + +def cpu_limit(root: Path) -> float | None: + """Квота к периоду `cpu.max` в ядрах; `max` — предела нет.""" + text = _read(root / "cpu.max") + if text is None: + return None + parts = text.split() + if len(parts) != 2 or parts[0] == _NO_LIMIT: + return None + try: + quota, period = int(parts[0]), int(parts[1]) + except ValueError: + return None + return quota / period if period > 0 else None + + +def memory_limit(root: Path) -> int | None: + text = _read(root / "memory.max") + if text is None or text == _NO_LIMIT or not text.isdigit(): + return None + return int(text) + + +def available(root: Path) -> bool: + """Метрики контейнера есть, если читаются `cpu.stat` и + `memory.current`.""" + return cpu_seconds(root) is not None and memory_bytes(root) is not None + + +def _observe(value: Any) -> Iterable[Observation]: + return [] if value is None else [Observation(value)] + + +def register(meter: Meter, *, root: Path) -> None: + """Наблюдаемые инструменты контейнера; вызывающий проверил + `available`.""" + meter.create_observable_counter( + METRIC_CONTAINER_CPU_TIME, + callbacks=[ + lambda _options: _observe(cpu_seconds(root)), + ], + unit="s", + description="CPU time of the container", + ) + meter.create_observable_up_down_counter( + METRIC_CONTAINER_MEMORY_USAGE, + callbacks=[lambda _options: _observe(memory_bytes(root))], + unit="By", + description="Memory usage of the container", + ) + meter.create_observable_up_down_counter( + METRIC_CONTAINER_CPU_LIMIT, + callbacks=[lambda _options: _observe(cpu_limit(root))], + unit="{cpu}", + description="CPU limit of the container", + ) + meter.create_observable_up_down_counter( + METRIC_CONTAINER_MEMORY_LIMIT, + callbacks=[lambda _options: _observe(memory_limit(root))], + unit="By", + description="Memory limit of the container", + ) diff --git a/src/infra/telemetry/core.py b/src/infra/telemetry/core.py index bbd1521..d0a73de 100644 --- a/src/infra/telemetry/core.py +++ b/src/infra/telemetry/core.py @@ -1,12 +1,13 @@ -"""Запуск и закрытие SDK OpenTelemetry, span и метрики процесса. +"""Запуск и закрытие SDK OpenTelemetry, span запроса и хранилищ. -Design change `otel-telemetry`, решения 4, 8–13; правила — -`.claude/rules/telemetry.md`. Провайдеры глобальными не ставятся: их держит -состояние модуля, а вызовы ниже при выключенной телеметрии ничего не делают. -SDK собирается только из `[telemetry]`: переменные `OTEL_*` удаляются из -окружения до создания провайдеров (`OTEL_SDK_DISABLED` провайдеры читают в -конструкторе), ресурс — конструктором без детекторов, у всех параметров -явные значения, `atexit` SDK выключен. +Design change `otel-telemetry`, решения 4, 8–13, и `job-trace-propagation`, +решения 5, 7; правила — `.claude/rules/telemetry.md`. Провайдеры глобальными +не ставятся: их держит состояние модуля, а вызовы ниже при выключенной +телеметрии ничего не делают. Модуль импортирует только `opentelemetry-api`: +SDK, экспортёр и `requests` загружает `start()` (модуль `sdk`), поэтому +процесс без телеметрии их в памяти не держит. Переменные `OTEL_*` вызывающий +удаляет из окружения до `start()` (`OTEL_SDK_DISABLED` провайдеры читают в +конструкторе). """ import asyncio @@ -14,93 +15,45 @@ import os import threading from collections.abc import Iterator, Mapping, Sequence from contextlib import contextmanager, suppress -from dataclasses import dataclass, field -from typing import Any +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any -# транспорт экспортёров OTLP/HTTP (зависимость opentelemetry-exporter-otlp- -# proto-http): своя сессия без окружения -import requests from opentelemetry import trace from opentelemetry.context import Context -from opentelemetry.exporter.otlp.proto.http import Compression -from opentelemetry.exporter.otlp.proto.http._log_exporter import ( - OTLPLogExporter, -) -from opentelemetry.exporter.otlp.proto.http.metric_exporter import ( - OTLPMetricExporter, -) -from opentelemetry.exporter.otlp.proto.http.trace_exporter import ( - OTLPSpanExporter, -) -from opentelemetry.sdk._logs import Logger as OtelLogger -from opentelemetry.sdk._logs import LoggerProvider, LogRecordLimits -from opentelemetry.sdk._logs.export import ( - BatchLogRecordProcessor, - LogRecordExporter, -) -from opentelemetry.sdk.metrics import ( - AlwaysOffExemplarFilter, - Counter, - Histogram, - MeterProvider, - ObservableCounter, - ObservableGauge, - ObservableUpDownCounter, - UpDownCounter, -) -from opentelemetry.sdk.metrics.export import ( - AggregationTemporality, - MetricReader, - PeriodicExportingMetricReader, -) -from opentelemetry.sdk.metrics.view import ( - ExplicitBucketHistogramAggregation, - View, -) -from opentelemetry.sdk.resources import Resource -from opentelemetry.sdk.trace import SpanLimits, TracerProvider -from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter -from opentelemetry.sdk.trace.sampling import ALWAYS_ON from opentelemetry.trace import Span, SpanKind, Status, StatusCode, Tracer +from opentelemetry.trace.propagation.tracecontext import ( + TraceContextTextMapPropagator, +) from src.config.settings import Telemetry as TelemetrySettings +from src.schemas.dataclasses import TraceContextDTO from src.utils.constants import ( ATTR_ERROR_TYPE, ATTR_HTTP_METHOD, ATTR_HTTP_ROUTE, ATTR_HTTP_STATUS, - ATTR_JOB_OUTCOME, - ATTR_JOB_TYPE, ATTR_REQUEST_ID, - HTTP_DURATION_BUCKETS, HTTP_KNOWN_METHODS, HTTP_OTHER_METHOD, - JOB_DURATION_BUCKETS, METRIC_HTTP_SERVER_DURATION, METRIC_JOB_DURATION, + METRIC_JOB_TIME_TO_READY, SERVICE_VERSION, - TELEMETRY_LOG_ATTRIBUTE_LENGTH, - TELEMETRY_LOGS_PATH, - TELEMETRY_MAX_ATTRIBUTES, - TELEMETRY_METRICS_PATH, TELEMETRY_SCOPE, - TELEMETRY_SPAN_ATTRIBUTE_LENGTH, - TELEMETRY_TRACES_PATH, + TRACE_HEADER_TRACEPARENT, + TRACE_HEADER_TRACESTATE, ) +if TYPE_CHECKING: + from opentelemetry.metrics import Meter + from opentelemetry.sdk._logs import LogRecordExporter + from opentelemetry.sdk.metrics.export import MetricReader + from opentelemetry.sdk.trace.export import SpanExporter + _OTEL_ENV_PREFIX = "OTEL_" -# все инструменты — cumulative: Prometheus забирает накопленное (решение 3) -_CUMULATIVE = dict.fromkeys( - ( - Counter, - UpDownCounter, - Histogram, - ObservableCounter, - ObservableUpDownCounter, - ObservableGauge, - ), - AggregationTemporality.CUMULATIVE, -) +# только W3C Trace Context, без baggage и без глобального propagator +# (решение 5): переносится контекст трассы, а не данные +PROPAGATOR = TraceContextTextMapPropagator() @dataclass(frozen=True, slots=True) @@ -108,20 +61,20 @@ class Exporters: """Получатели сигналов вместо OTLP — только для быстрых тестов (in-memory экспортёры SDK).""" - spans: SpanExporter - metrics: MetricReader - logs: LogRecordExporter + spans: "SpanExporter" + metrics: "MetricReader" + logs: "LogRecordExporter" @dataclass(slots=True) class _State: tracer: Tracer - otel_logger: OtelLogger + meter: "Meter" + otel_logger: Any http_duration: Any job_duration: Any - tracer_provider: TracerProvider - meter_provider: MeterProvider - logger_provider: LoggerProvider + time_to_ready: Any + providers: Any _state: _State | None = None @@ -149,7 +102,8 @@ def start( config: TelemetrySettings, exporters: Exporters | None = None, ) -> bool: - """Провайдеры трасс, метрик и логов процесса. Выключено — ничего. + """Провайдеры трасс, метрик и логов процесса. Выключено — ничего, и SDK + не загружается. Вызывающий до этого удаляет `OTEL_*` (`remove_otel_environment`) и пишет `warning`; хуки журнала ставит `src.infra.telemetry.logs`.""" @@ -158,84 +112,30 @@ def start( return True if not config.enabled and exporters is None: return False - resource = Resource( - { + # SDK — только здесь (design change job-trace-propagation, решение 7) + from src.infra.telemetry import sdk + + providers = sdk.build( + resource={ "service.name": service_name, "service.version": SERVICE_VERSION, "service.instance.id": instance_id, "deployment.environment.name": config.environment, }, + config=config, + exporters=exporters, ) - if exporters is None: - exporters = _otlp_exporters(config) - timeout_ms = config.export_timeout_seconds * 1000 - delay_ms = config.schedule_delay_seconds * 1000 - - tracer_provider = TracerProvider( - sampler=ALWAYS_ON, - resource=resource, - shutdown_on_exit=False, - span_limits=SpanLimits( - max_attributes=TELEMETRY_MAX_ATTRIBUTES, - max_events=TELEMETRY_MAX_ATTRIBUTES, - max_links=TELEMETRY_MAX_ATTRIBUTES, - max_span_attributes=TELEMETRY_MAX_ATTRIBUTES, - max_event_attributes=TELEMETRY_MAX_ATTRIBUTES, - max_link_attributes=TELEMETRY_MAX_ATTRIBUTES, - max_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH, - max_span_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH, - ), + meter = providers.meter_provider.get_meter( + TELEMETRY_SCOPE, + SERVICE_VERSION, ) - tracer_provider.add_span_processor( - BatchSpanProcessor( - exporters.spans, - max_queue_size=config.max_queue_size, - schedule_delay_millis=delay_ms, - max_export_batch_size=config.max_export_batch_size, - export_timeout_millis=timeout_ms, - ), - ) - meter_provider = MeterProvider( - metric_readers=[exporters.metrics], - resource=resource, - exemplar_filter=AlwaysOffExemplarFilter(), - shutdown_on_exit=False, - views=[ - View( - instrument_name=METRIC_HTTP_SERVER_DURATION, - aggregation=ExplicitBucketHistogramAggregation( - boundaries=HTTP_DURATION_BUCKETS, - ), - ), - View( - instrument_name=METRIC_JOB_DURATION, - aggregation=ExplicitBucketHistogramAggregation( - boundaries=JOB_DURATION_BUCKETS, - ), - ), - ], - ) - logger_provider = LoggerProvider( - resource=resource, - shutdown_on_exit=False, - log_record_limits=LogRecordLimits( - max_attributes=TELEMETRY_MAX_ATTRIBUTES, - max_attribute_length=TELEMETRY_LOG_ATTRIBUTE_LENGTH, - ), - ) - logger_provider.add_log_record_processor( - BatchLogRecordProcessor( - exporters.logs, - schedule_delay_millis=delay_ms, - max_export_batch_size=config.max_export_batch_size, - export_timeout_millis=timeout_ms, - max_queue_size=config.max_queue_size, - ), - ) - meter = meter_provider.get_meter(TELEMETRY_SCOPE, SERVICE_VERSION) _state = _State( - tracer=tracer_provider.get_tracer(TELEMETRY_SCOPE, SERVICE_VERSION), - otel_logger=logger_provider.get_logger( + tracer=providers.tracer_provider.get_tracer( + TELEMETRY_SCOPE, + SERVICE_VERSION, + ), + meter=meter, + otel_logger=providers.logger_provider.get_logger( TELEMETRY_SCOPE, SERVICE_VERSION, ), @@ -249,58 +149,16 @@ def start( unit="s", description="Duration of job deliveries handled by the worker", ), - tracer_provider=tracer_provider, - meter_provider=meter_provider, - logger_provider=logger_provider, + time_to_ready=meter.create_histogram( + METRIC_JOB_TIME_TO_READY, + unit="s", + description="Time from accepted upload to ready attachment", + ), + providers=providers, ) return True -def _export_session() -> requests.Session: - """Сессия отправки без окружения: `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc` - и `REQUESTS_CA_BUNDLE` на неё не действуют — данные идут только по адресу - `[telemetry]` (verify S5, как с `OTEL_*`, решение 8).""" - session = requests.Session() - session.trust_env = False - return session - - -def _otlp_exporters(config: TelemetrySettings) -> Exporters: - """OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без - заголовков и сжатия, своя сессия без прокси окружения.""" - timeout = config.export_timeout_seconds - endpoint = config.otlp_endpoint - return Exporters( - spans=OTLPSpanExporter( - endpoint=endpoint + TELEMETRY_TRACES_PATH, - headers={}, - timeout=timeout, - compression=Compression.NoCompression, - session=_export_session(), - ), - metrics=PeriodicExportingMetricReader( - OTLPMetricExporter( - endpoint=endpoint + TELEMETRY_METRICS_PATH, - headers={}, - timeout=timeout, - compression=Compression.NoCompression, - preferred_temporality=_CUMULATIVE, - session=_export_session(), - ), - export_interval_millis=config.metric_export_interval_seconds - * 1000, - export_timeout_millis=timeout * 1000, - ), - logs=OTLPLogExporter( - endpoint=endpoint + TELEMETRY_LOGS_PATH, - headers={}, - timeout=timeout, - compression=Compression.NoCompression, - session=_export_session(), - ), - ) - - def begin_shutdown() -> list[threading.Thread]: """Закрытие провайдеров в daemon-потоках, по одному на сигнал: при замороженном Collector каждый ждёт свой срок отправки, а записи журнала @@ -318,9 +176,9 @@ def begin_shutdown() -> list[threading.Thread]: daemon=True, ) for name, provider in ( - ("logs", state.logger_provider), - ("traces", state.tracer_provider), - ("metrics", state.meter_provider), + ("logs", state.providers.logger_provider), + ("traces", state.providers.tracer_provider), + ("metrics", state.providers.meter_provider), ) ] for thread in threads: @@ -449,58 +307,49 @@ def finish_request( state.http_duration.record(duration_seconds, attributes) -@dataclass(slots=True) -class JobObservation: - """Учёт одной доставки worker: исход — атрибут span и метка histogram.""" - - span: Span | None - job_type: str - recorded: bool = field(default=False) - - def finish( - self, - *, - outcome: str, - duration_seconds: float, - error: BaseException | None = None, - ) -> None: - state = _state - if state is None or self.recorded: - return - self.recorded = True - if self.span is not None: - self.span.set_attribute(ATTR_JOB_OUTCOME, outcome) - if error is not None: - mark_error(self.span, error) - state.job_duration.record( - duration_seconds, - {ATTR_JOB_TYPE: self.job_type, ATTR_JOB_OUTCOME: outcome}, - ) +def trace_headers(context: Context | None = None) -> dict[str, str]: + """`traceparent` и непустой `tracestate` контекста (по умолчанию — + текущего); невалидный span — пусто.""" + carrier: dict[str, str] = {} + PROPAGATOR.inject(carrier, context=context) + return carrier -@contextmanager -def consumer_span(*, queue: str, job_type: str) -> Iterator[JobObservation]: - """Span `CONSUMER` доставки (решение 11), корень трассы задания: контекст - из сообщения переносит change 2. Исход и длительность называет - `JobObservation.finish`.""" - state = _state - if state is None: - yield JobObservation(span=None, job_type=job_type) - return - with state.tracer.start_as_current_span( - f"process {queue}", - context=Context(), - kind=SpanKind.CONSUMER, - attributes={ - "messaging.system": "rabbitmq", - "messaging.destination.name": queue, - "messaging.operation.type": "process", - ATTR_JOB_TYPE: job_type, - }, - record_exception=False, - set_status_on_exception=False, - ) as span: - yield JobObservation(span=span, job_type=job_type) +def to_trace_context(carrier: Mapping[str, str]) -> TraceContextDTO | None: + traceparent = carrier.get(TRACE_HEADER_TRACEPARENT) + if not traceparent: + return None + return TraceContextDTO( + traceparent=traceparent, + tracestate=carrier.get(TRACE_HEADER_TRACESTATE) or None, + ) + + +def to_carrier(trace_context: TraceContextDTO) -> dict[str, str]: + carrier = {TRACE_HEADER_TRACEPARENT: trace_context.traceparent} + if trace_context.tracestate: + carrier[TRACE_HEADER_TRACESTATE] = trace_context.tracestate + return carrier + + +def remote_context(trace_context: TraceContextDTO | None) -> Context | None: + """Контекст удалённого родителя из сохранённого значения; `None` — нет + значения или оно не по W3C (новая трасса, а не ошибка).""" + if trace_context is None: + return None + context = PROPAGATOR.extract(to_carrier(trace_context), context=Context()) + if not trace.get_current_span(context).get_span_context().is_valid: + return None + return context + + +def current_trace_context() -> TraceContextDTO | None: + """Контекст текущего валидного span — server span загрузки — для + задания (решение 4); невыбранный сохраняется с флагом `00`. Без + телеметрии или вне span — `None`.""" + if _state is None: + return None + return to_trace_context(trace_headers()) def tracer() -> Tracer | None: @@ -508,6 +357,17 @@ def tracer() -> Tracer | None: return None if state is None else state.tracer -def otel_logger() -> OtelLogger | None: +def meter() -> "Meter | None": + state = _state + return None if state is None else state.meter + + +def otel_logger() -> Any: state = _state return None if state is None else state.otel_logger + + +def job_histograms() -> tuple[Any, Any] | None: + """Histogram длительности доставки и времени до готовности.""" + state = _state + return None if state is None else (state.job_duration, state.time_to_ready) diff --git a/src/infra/telemetry/db.py b/src/infra/telemetry/db.py index a767854..678ec15 100644 --- a/src/infra/telemetry/db.py +++ b/src/infra/telemetry/db.py @@ -17,7 +17,8 @@ from sqlalchemy import event from sqlalchemy.engine import ExceptionContext from sqlalchemy.ext.asyncio import AsyncEngine -from src.infra.telemetry import core +from src.config import settings +from src.infra.telemetry import core, metrics DB_SYSTEM = "postgresql" # атрибут контекста выполнения со span запроса @@ -41,10 +42,25 @@ def operation_name(statement: str) -> str: return words[0].upper() if words else "QUERY" -def instrument_engine(engine: AsyncEngine) -> None: - """Слушатели span на engine процесса; телеметрия выключена — ничего.""" +def instrument_engine( + engine: AsyncEngine, + *, + max_overflow: int | None = None, +) -> None: + """Слушатели span и метрики пула (`db.client.connection.*`, design change + `job-trace-propagation`, решение 10) на engine процесса; предел пула — + его размер и `max_overflow` (по умолчанию `[database]`). Телеметрия + выключена — ничего.""" if not core.is_enabled(): return + metrics.observe_pool( + engine, + max_overflow=( + settings.database.max_overflow + if max_overflow is None + else max_overflow + ), + ) sync_engine = engine.sync_engine base = db_attributes(sync_engine.url) diff --git a/src/infra/telemetry/messaging.py b/src/infra/telemetry/messaging.py new file mode 100644 index 0000000..a0ccb75 --- /dev/null +++ b/src/infra/telemetry/messaging.py @@ -0,0 +1,200 @@ +"""Span брокера: producer публикации relay и consumer доставки worker. + +Design change `job-trace-propagation`, решения 1–3, 8, 13. Контекст W3C +загрузки сохранён в задании; relay открывает span `PRODUCER` дочерним к нему и +кладёт в заголовки сообщения контекст этого span, worker делает span +`CONSUMER` дочерним к контексту из заголовков и ставит link на него +(semantic conventions messaging, обработка одного сообщения). Без контекста +— ни span producer, ни заголовков, а consumer span — корень трассы, как на +уровне 3 (решение 6). Атрибуты — значения enum, без `id` и текста ошибок. +""" + +from collections.abc import Iterator +from contextlib import contextmanager +from dataclasses import dataclass, field + +from opentelemetry import trace +from opentelemetry.context import Context +from opentelemetry.trace import Link, Span, SpanKind + +from src.infra.telemetry import core +from src.schemas.dataclasses import ( + JobDeliveryResultDTO, + JobPublicationDTO, + TraceContextDTO, +) +from src.utils.constants import ( + ATTR_JOB_ATTEMPT, + ATTR_JOB_ERROR_CODE, + ATTR_JOB_OUTCOME, + ATTR_JOB_REASON, + ATTR_JOB_REDELIVERED, + ATTR_JOB_REPLAYED, + ATTR_JOB_RETRY_REASON, + ATTR_JOB_TYPE, + ATTR_MESSAGING_DESTINATION, + ATTR_MESSAGING_OPERATION_NAME, + ATTR_MESSAGING_OPERATION_TYPE, + ATTR_MESSAGING_SYSTEM, + MESSAGING_OPERATION_PROCESS, + MESSAGING_OPERATION_PUBLISH, + MESSAGING_SYSTEM, +) + +# messaging.operation.type semantic conventions +_OPERATION_SEND = "send" +_OPERATION_PROCESS = "process" + + +def _messaging_attributes( + *, + queue: str, + operation_type: str, + operation_name: str, + job_type: str, +) -> dict[str, str]: + return { + ATTR_MESSAGING_SYSTEM: MESSAGING_SYSTEM, + ATTR_MESSAGING_DESTINATION: queue, + ATTR_MESSAGING_OPERATION_TYPE: operation_type, + ATTR_MESSAGING_OPERATION_NAME: operation_name, + ATTR_JOB_TYPE: job_type, + } + + +@contextmanager +def producer_span( + *, + queue: str, + job_type: str, + publication: JobPublicationDTO, +) -> Iterator[dict[str, str]]: + """Span `PRODUCER` `publish <очередь>` публикации под сохранённым + контекстом задания; отдаёт заголовки сообщения. Span заканчивается при + выходе (после подтверждения брокером); ошибка и отмена — `ERROR` и класс. + + Нет контекста или он не по W3C — пусто и без span: проходы relay трасс не + начинают. Телеметрия выключена — сохранённый контекст как есть: цепочка + API → worker не рвётся.""" + parent = core.remote_context(publication.trace_context) + tracer = core.tracer() + if parent is None: + yield {} + return + if tracer is None: + yield core.to_carrier(publication.trace_context) + return + attributes: dict[str, str | int | bool] = { + **_messaging_attributes( + queue=queue, + operation_type=_OPERATION_SEND, + operation_name=MESSAGING_OPERATION_PUBLISH, + job_type=job_type, + ), + ATTR_JOB_ATTEMPT: publication.attempt, + ATTR_JOB_REPLAYED: publication.replayed, + } + if publication.retry_reason: + attributes[ATTR_JOB_RETRY_REASON] = publication.retry_reason + span = tracer.start_span( + f"{MESSAGING_OPERATION_PUBLISH} {queue}", + context=parent, + kind=SpanKind.PRODUCER, + attributes=attributes, + record_exception=False, + set_status_on_exception=False, + ) + try: + yield core.trace_headers(trace.set_span_in_context(span)) + except BaseException as e: + core.mark_error(span, e) + raise + finally: + span.end() + + +@dataclass(slots=True) +class JobObservation: + """Учёт одной доставки worker: итог — атрибуты span, метка histogram + длительности и, у `ready` без replay, точка времени до готовности.""" + + span: Span | None + job_type: str + recorded: bool = field(default=False) + + def finish( + self, + *, + result: JobDeliveryResultDTO, + duration_seconds: float, + error: BaseException | None = None, + ) -> None: + histograms = core.job_histograms() + if histograms is None or self.recorded: + return + self.recorded = True + outcome = result.outcome.value + if self.span is not None: + self.span.set_attribute(ATTR_JOB_OUTCOME, outcome) + if result.attempt is not None: + self.span.set_attribute(ATTR_JOB_ATTEMPT, result.attempt) + if result.reason is not None: + self.span.set_attribute(ATTR_JOB_REASON, result.reason.value) + if result.error_code is not None: + self.span.set_attribute( + ATTR_JOB_ERROR_CODE, + result.error_code.value, + ) + if error is not None: + core.mark_error(self.span, error) + duration, time_to_ready = histograms + duration.record( + duration_seconds, + {ATTR_JOB_TYPE: self.job_type, ATTR_JOB_OUTCOME: outcome}, + ) + if result.time_to_ready_seconds is not None: + time_to_ready.record( + result.time_to_ready_seconds, + {ATTR_JOB_TYPE: self.job_type}, + ) + + +@contextmanager +def consumer_span( + *, + queue: str, + job_type: str, + parent: TraceContextDTO | None = None, + redelivered: bool = False, +) -> Iterator[JobObservation]: + """Span `CONSUMER` `process <очередь>` доставки (решения 2, 11): дочерний + к контексту из заголовков сообщения и с link на него; без контекста или с + неверным — корень трассы. Под невыбранным родителем span не + записывается, исход и метрики те же. Итог называет + `JobObservation.finish`.""" + tracer = core.tracer() + if tracer is None: + yield JobObservation(span=None, job_type=job_type) + return + remote = core.remote_context(parent) + links = [] + if remote is not None: + links.append(Link(trace.get_current_span(remote).get_span_context())) + with tracer.start_as_current_span( + f"{MESSAGING_OPERATION_PROCESS} {queue}", + context=remote if remote is not None else Context(), + kind=SpanKind.CONSUMER, + links=links, + attributes={ + **_messaging_attributes( + queue=queue, + operation_type=_OPERATION_PROCESS, + operation_name=MESSAGING_OPERATION_PROCESS, + job_type=job_type, + ), + ATTR_JOB_REDELIVERED: redelivered, + }, + record_exception=False, + set_status_on_exception=False, + ) as span: + yield JobObservation(span=span, job_type=job_type) diff --git a/src/infra/telemetry/metrics.py b/src/infra/telemetry/metrics.py new file mode 100644 index 0000000..62de0c6 --- /dev/null +++ b/src/infra/telemetry/metrics.py @@ -0,0 +1,204 @@ +"""Наблюдаемые метрики уровня 4: пул PostgreSQL, насыщение worker, очередь. + +Design change `job-trace-propagation`, решения 9–11, 13. Значения читает +callback сбора метрик в потоке экспорта, пишет цикл событий: гонка безвредна +(целые, на сбор ± 1). Телеметрия выключена — регистрации нет. +""" + +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from datetime import timedelta +from typing import Any + +from opentelemetry.metrics import CallbackOptions, Observation + +from src.infra.telemetry import core +from src.schemas.dataclasses import QueueSnapshotDTO +from src.utils.constants import ( + ATTR_DB_CONNECTION_STATE, + ATTR_DB_POOL_NAME, + ATTR_MESSAGING_DESTINATION, + ATTR_QUEUE_STAGE, + DB_CONNECTION_STATE_IDLE, + DB_CONNECTION_STATE_USED, + METRIC_DB_CONNECTION_COUNT, + METRIC_DB_CONNECTION_MAX, + METRIC_DB_CONNECTION_PENDING, + METRIC_DB_CONNECTION_TIMEOUTS, + METRIC_QUEUE_DEPTH, + METRIC_QUEUE_OLDEST_AGE, + METRIC_WORKER_BUSY, + METRIC_WORKER_CAPACITY, + METRIC_WORKER_WAITING, + QUEUE_SNAPSHOT_STALE_SECONDS, + QUEUE_STAGE_OUTBOX, + QUEUE_STAGE_PROCESSING, + QUEUE_STAGE_PUBLISHED, + QUEUE_STAGE_SCHEDULED, +) +from src.utils.utc import utcnow + + +def pool_name(engine_url: Any) -> str: + """Имя пула по semantic conventions: `server.address:server.port/ + db.namespace`.""" + port = "" if engine_url.port is None else f":{engine_url.port}" + return f"{engine_url.host or ''}{port}/{engine_url.database or ''}" + + +def observe_pool(engine: Any, *, max_overflow: int) -> None: + """`db.client.connection.*` пула engine (решение 10): каждый сбор читает + текущий `engine.sync_engine.pool` — `dispose()` создаёт новый пул того же + класса. Ожидающие и отказы по сроку — у `CountingQueuePool`.""" + meter = core.meter() + if meter is None: + return + sync_engine = engine.sync_engine + attributes = {ATTR_DB_POOL_NAME: pool_name(sync_engine.url)} + + def counts(_options: CallbackOptions) -> Iterable[Observation]: + pool = sync_engine.pool + return [ + Observation( + pool.checkedout(), + { + **attributes, + ATTR_DB_CONNECTION_STATE: DB_CONNECTION_STATE_USED, + }, + ), + Observation( + pool.checkedin(), + { + **attributes, + ATTR_DB_CONNECTION_STATE: DB_CONNECTION_STATE_IDLE, + }, + ), + ] + + def limit(_options: CallbackOptions) -> Iterable[Observation]: + return [ + Observation(sync_engine.pool.size() + max_overflow, attributes), + ] + + def pending(_options: CallbackOptions) -> Iterable[Observation]: + read = getattr(sync_engine.pool, "pending", None) + return [] if read is None else [Observation(read(), attributes)] + + def timeouts(_options: CallbackOptions) -> Iterable[Observation]: + read = getattr(sync_engine.pool, "timeouts", None) + return [] if read is None else [Observation(read(), attributes)] + + meter.create_observable_up_down_counter( + METRIC_DB_CONNECTION_COUNT, + callbacks=[counts], + unit="{connection}", + description="Connections of the pool by state", + ) + meter.create_observable_up_down_counter( + METRIC_DB_CONNECTION_MAX, + callbacks=[limit], + unit="{connection}", + description="Maximum connections of the pool", + ) + meter.create_observable_up_down_counter( + METRIC_DB_CONNECTION_PENDING, + callbacks=[pending], + unit="{request}", + description="Requests waiting for a pool connection", + ) + meter.create_observable_counter( + METRIC_DB_CONNECTION_TIMEOUTS, + callbacks=[timeouts], + unit="{timeout}", + description="Pool checkouts that timed out", + ) + + +@dataclass(slots=True) +class WorkerLoad: + """Счётчики мест конкуренции worker (решение 11): `waiting` — доставки до + входа в место, `busy` — внутри. Пишет `_handle` worker.""" + + busy: int = 0 + waiting: int = 0 + + +def observe_worker(*, capacity: int, load: WorkerLoad) -> None: + meter = core.meter() + if meter is None: + return + meter.create_observable_up_down_counter( + METRIC_WORKER_BUSY, + callbacks=[lambda _options: [Observation(load.busy)]], + unit="{delivery}", + description="Deliveries occupying a concurrency slot", + ) + meter.create_observable_up_down_counter( + METRIC_WORKER_CAPACITY, + callbacks=[lambda _options: [Observation(capacity)]], + unit="{delivery}", + description="Concurrency slots of the worker", + ) + meter.create_observable_up_down_counter( + METRIC_WORKER_WAITING, + callbacks=[lambda _options: [Observation(load.waiting)]], + unit="{delivery}", + description="Received deliveries waiting for a slot", + ) + + +def queue_observations( + snapshot: QueueSnapshotDTO | None, + *, + queue: str, +) -> tuple[list[Observation], list[Observation]]: + """Глубина по стадиям и возраст старейшего из последнего снимка; снимок + старше `QUEUE_SNAPSHOT_STALE_SECONDS` или его нет — ничего (решение 9).""" + if snapshot is None or utcnow() - snapshot.taken_at > timedelta( + seconds=QUEUE_SNAPSHOT_STALE_SECONDS, + ): + return [], [] + base = {ATTR_MESSAGING_DESTINATION: queue} + depth = [ + Observation(value, {**base, ATTR_QUEUE_STAGE: stage}) + for stage, value in ( + (QUEUE_STAGE_SCHEDULED, snapshot.scheduled), + (QUEUE_STAGE_OUTBOX, snapshot.outbox), + (QUEUE_STAGE_PUBLISHED, snapshot.published), + (QUEUE_STAGE_PROCESSING, snapshot.processing), + ) + ] + age = 0.0 + if snapshot.oldest_created_at is not None: + age = max( + 0.0, + (snapshot.taken_at - snapshot.oldest_created_at).total_seconds(), + ) + return depth, [Observation(age, base)] + + +def observe_queue( + *, + queue: str, + latest: Callable[[], QueueSnapshotDTO | None], +) -> None: + """Gauge глубины и возраста очереди relay по последнему снимку.""" + meter = core.meter() + if meter is None: + return + meter.create_observable_gauge( + METRIC_QUEUE_DEPTH, + callbacks=[ + lambda _options: queue_observations(latest(), queue=queue)[0], + ], + unit="{job}", + description="Unfinished jobs by stage", + ) + meter.create_observable_gauge( + METRIC_QUEUE_OLDEST_AGE, + callbacks=[ + lambda _options: queue_observations(latest(), queue=queue)[1], + ], + unit="s", + description="Age of the oldest unfinished job since it was accepted", + ) diff --git a/src/infra/telemetry/sdk.py b/src/infra/telemetry/sdk.py new file mode 100644 index 0000000..857e5e7 --- /dev/null +++ b/src/infra/telemetry/sdk.py @@ -0,0 +1,222 @@ +"""Сборка провайдеров SDK OpenTelemetry и экспортёров OTLP/HTTP. + +Единственный модуль пакета, который импортирует SDK, экспортёр и `requests` +(design change `job-trace-propagation`, решение 7): его импортирует только +`core.start()`, поэтому процесс с выключенной телеметрией, уборщик и команда +replay модулей SDK, protobuf и HTTP-клиента экспортёра не загружают. Остальные +модули пакета — только `opentelemetry-api`. + +Всё — из `[telemetry]` (design change `otel-telemetry`, решение 8): ресурс +конструктором без детекторов, у параметров явные значения, `atexit` SDK +выключен. Sampler — `ParentBased(ALWAYS_ON)` (решение 5): корни выбираются +всегда, удалённый родитель из задания передаёт свой флаг выборки. +""" + +from collections.abc import Mapping +from dataclasses import dataclass +from typing import Any + +# транспорт экспортёров OTLP/HTTP (зависимость opentelemetry-exporter-otlp- +# proto-http): своя сессия без окружения +import requests +from opentelemetry.exporter.otlp.proto.http import Compression +from opentelemetry.exporter.otlp.proto.http._log_exporter import ( + OTLPLogExporter, +) +from opentelemetry.exporter.otlp.proto.http.metric_exporter import ( + OTLPMetricExporter, +) +from opentelemetry.exporter.otlp.proto.http.trace_exporter import ( + OTLPSpanExporter, +) +from opentelemetry.sdk._logs import LoggerProvider, LogRecordLimits +from opentelemetry.sdk._logs.export import BatchLogRecordProcessor +from opentelemetry.sdk.metrics import ( + AlwaysOffExemplarFilter, + Counter, + Histogram, + MeterProvider, + ObservableCounter, + ObservableGauge, + ObservableUpDownCounter, + UpDownCounter, +) +from opentelemetry.sdk.metrics.export import ( + AggregationTemporality, + PeriodicExportingMetricReader, +) +from opentelemetry.sdk.metrics.view import ( + ExplicitBucketHistogramAggregation, + View, +) +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import SpanLimits, TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor +from opentelemetry.sdk.trace.sampling import ALWAYS_ON, ParentBased + +from src.config.settings import Telemetry as TelemetrySettings +from src.utils.constants import ( + HTTP_DURATION_BUCKETS, + JOB_DURATION_BUCKETS, + METRIC_HTTP_SERVER_DURATION, + METRIC_JOB_DURATION, + METRIC_JOB_TIME_TO_READY, + TELEMETRY_LOG_ATTRIBUTE_LENGTH, + TELEMETRY_LOGS_PATH, + TELEMETRY_MAX_ATTRIBUTES, + TELEMETRY_METRICS_PATH, + TELEMETRY_SPAN_ATTRIBUTE_LENGTH, + TELEMETRY_TRACES_PATH, + TIME_TO_READY_BUCKETS, +) + +# все инструменты — cumulative: Prometheus забирает накопленное (решение 3) +_CUMULATIVE = dict.fromkeys( + ( + Counter, + UpDownCounter, + Histogram, + ObservableCounter, + ObservableUpDownCounter, + ObservableGauge, + ), + AggregationTemporality.CUMULATIVE, +) +# границы buckets histogram по имени инструмента +_BUCKETS = { + METRIC_HTTP_SERVER_DURATION: HTTP_DURATION_BUCKETS, + METRIC_JOB_DURATION: JOB_DURATION_BUCKETS, + METRIC_JOB_TIME_TO_READY: TIME_TO_READY_BUCKETS, +} + + +@dataclass(frozen=True, slots=True) +class Providers: + tracer_provider: TracerProvider + meter_provider: MeterProvider + logger_provider: LoggerProvider + + +def build( + *, + resource: Mapping[str, Any], + config: TelemetrySettings, + exporters: Any | None, +) -> Providers: + """Провайдеры трасс, метрик и логов. `exporters` — получатели вместо OTLP + (`core.Exporters`, быстрые тесты) или `None`.""" + if exporters is None: + exporters = otlp_exporters(config) + attributes = Resource(dict(resource)) + timeout_ms = config.export_timeout_seconds * 1000 + delay_ms = config.schedule_delay_seconds * 1000 + + tracer_provider = TracerProvider( + sampler=ParentBased(ALWAYS_ON), + resource=attributes, + shutdown_on_exit=False, + span_limits=SpanLimits( + max_attributes=TELEMETRY_MAX_ATTRIBUTES, + max_events=TELEMETRY_MAX_ATTRIBUTES, + max_links=TELEMETRY_MAX_ATTRIBUTES, + max_span_attributes=TELEMETRY_MAX_ATTRIBUTES, + max_event_attributes=TELEMETRY_MAX_ATTRIBUTES, + max_link_attributes=TELEMETRY_MAX_ATTRIBUTES, + max_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH, + max_span_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH, + ), + ) + tracer_provider.add_span_processor( + BatchSpanProcessor( + exporters.spans, + max_queue_size=config.max_queue_size, + schedule_delay_millis=delay_ms, + max_export_batch_size=config.max_export_batch_size, + export_timeout_millis=timeout_ms, + ), + ) + meter_provider = MeterProvider( + metric_readers=[exporters.metrics], + resource=attributes, + exemplar_filter=AlwaysOffExemplarFilter(), + shutdown_on_exit=False, + views=[ + View( + instrument_name=name, + aggregation=ExplicitBucketHistogramAggregation( + boundaries=boundaries, + ), + ) + for name, boundaries in _BUCKETS.items() + ], + ) + logger_provider = LoggerProvider( + resource=attributes, + shutdown_on_exit=False, + log_record_limits=LogRecordLimits( + max_attributes=TELEMETRY_MAX_ATTRIBUTES, + max_attribute_length=TELEMETRY_LOG_ATTRIBUTE_LENGTH, + ), + ) + logger_provider.add_log_record_processor( + BatchLogRecordProcessor( + exporters.logs, + schedule_delay_millis=delay_ms, + max_export_batch_size=config.max_export_batch_size, + export_timeout_millis=timeout_ms, + max_queue_size=config.max_queue_size, + ), + ) + return Providers( + tracer_provider=tracer_provider, + meter_provider=meter_provider, + logger_provider=logger_provider, + ) + + +def export_session() -> requests.Session: + """Сессия отправки без окружения: `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc` + и `REQUESTS_CA_BUNDLE` на неё не действуют — данные идут только по адресу + `[telemetry]` (verify S5 change `otel-telemetry`, как с `OTEL_*`).""" + session = requests.Session() + session.trust_env = False + return session + + +def otlp_exporters(config: TelemetrySettings) -> Any: + """OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без + заголовков и сжатия, своя сессия без прокси окружения.""" + # тип получателей живёт в core: он нужен быстрым тестам без этого модуля + from src.infra.telemetry.core import Exporters + + timeout = config.export_timeout_seconds + endpoint = config.otlp_endpoint + return Exporters( + spans=OTLPSpanExporter( + endpoint=endpoint + TELEMETRY_TRACES_PATH, + headers={}, + timeout=timeout, + compression=Compression.NoCompression, + session=export_session(), + ), + metrics=PeriodicExportingMetricReader( + OTLPMetricExporter( + endpoint=endpoint + TELEMETRY_METRICS_PATH, + headers={}, + timeout=timeout, + compression=Compression.NoCompression, + preferred_temporality=_CUMULATIVE, + session=export_session(), + ), + export_interval_millis=config.metric_export_interval_seconds + * 1000, + export_timeout_millis=timeout * 1000, + ), + logs=OTLPLogExporter( + endpoint=endpoint + TELEMETRY_LOGS_PATH, + headers={}, + timeout=timeout, + compression=Compression.NoCompression, + session=export_session(), + ), + ) diff --git a/src/infra/telemetry/setup.py b/src/infra/telemetry/setup.py index 03239a0..1912348 100644 --- a/src/infra/telemetry/setup.py +++ b/src/infra/telemetry/setup.py @@ -1,10 +1,13 @@ -"""Запуск телеметрии точкой входа процесса (API, worker).""" +"""Запуск телеметрии точкой входа процесса (API, worker, relay).""" + +from pathlib import Path from src.config import settings from src.infra.logger import AbstractLogger, get_logger -from src.infra.telemetry import core +from src.infra.telemetry import container, core from src.infra.telemetry.core import Exporters from src.infra.telemetry.logs import install_log_hooks +from src.utils.constants import CGROUP_ROOT logger: AbstractLogger = get_logger().bind(module="telemetry") @@ -13,10 +16,13 @@ def start_process_telemetry( service_name: str, *, exporters: Exporters | None = None, + cgroup_root: Path | str = CGROUP_ROOT, ) -> bool: - """По `[telemetry]`: выключено — ничего. Включено — `OTEL_*` удаляются - из окружения с `warning` (имена без значений), затем провайдеры и хуки - журнала. `True` — телеметрия работает.""" + """По `[telemetry]`: выключено — ничего, модули SDK не загружаются. + Включено — `OTEL_*` удаляются из окружения с `warning` (имена без + значений), затем провайдеры, метрики контейнера по cgroup v2 (design + change `job-trace-propagation`, решение 12) и хуки журнала. `True` — + телеметрия работает.""" config = settings.telemetry if not config.enabled and exporters is None: return False @@ -27,6 +33,18 @@ def start_process_telemetry( config=config, exporters=exporters, ) + meter = core.meter() + root = Path(cgroup_root) + if meter is not None: + if container.available(root): + container.register(meter, root=root) + else: + # до хуков журнала: одна запись в stdout, на хосте без cgroup + # (macOS) журнал в хранилище логов не меняется + logger.warning( + "Container metrics are unavailable", + cgroup_root=str(root), + ) install_log_hooks() if ignored: logger.warning( diff --git a/src/relay/main.py b/src/relay/main.py index 914ab02..0c437ee 100644 --- a/src/relay/main.py +++ b/src/relay/main.py @@ -11,6 +11,12 @@ SIGTERM: текущий шаг доводится до фиксации или сигнал прерывает сразу, «Stopped relay», код 0. Незаписанная отметка ничего не теряет: следующий запуск опубликует задание снова. +Телеметрия (design change `job-trace-propagation`, решения 3, 7, 9): SDK по +`[telemetry]`, span producer — только публикации заданий с сохранённым +контекстом, проходы и их обращения к PostgreSQL трасс не начинают; снимок +очереди — после успешного прохода не чаще 5 с; закрытие SDK — в окне закрытия +клиентов 0,5 с. Команда replay SDK не запускает. + `python -m src.relay replay [--attachment-id ID]... [--error-code C] [--reason R] [--limit N] [--apply] [--operator NAME]` — операторская команда реестра `failed`, по умолчанию показ. Нужен только PostgreSQL. Коды: 0 — выбранное показано или @@ -21,6 +27,7 @@ SIGTERM: текущий шаг доводится до фиксации или import argparse import asyncio import signal +import time from contextlib import suppress from uuid import UUID @@ -28,12 +35,17 @@ from src.config import settings from src.core import exceptions from src.core.services.attachment_relay import AttachmentRelayService from src.core.services.attachment_replay import AttachmentReplayService -from src.infra import early_stop +from src.infra import early_stop, telemetry from src.infra.broker import JobPublisher from src.infra.db import create_engine, create_session_factory from src.infra.db.uow import SqlAlchemyUnitOfWork from src.infra.logger import AbstractLogger, get_logger +from src.schemas import dataclasses from src.schemas.enums import AttachmentErrorCode, AttachmentJobReason +from src.utils.constants import ( + QUEUE_SNAPSHOT_INTERVAL_SECONDS, + TELEMETRY_SERVICE_RELAY, +) logger: AbstractLogger = get_logger().bind(module="relay") @@ -140,11 +152,39 @@ def _install_stop() -> asyncio.Event: return stop +class QueueSnapshots: + """Последний снимок очереди процесса relay: его читают gauge глубины и + возраста (design change `job-trace-propagation`, решение 9).""" + + def __init__(self) -> None: + self.latest: dataclasses.QueueSnapshotDTO | None = None + self._taken_at: float | None = None + + def due(self, now: float) -> bool: + return ( + self._taken_at is None + or now - self._taken_at >= QUEUE_SNAPSHOT_INTERVAL_SECONDS + ) + + def store( + self, + snapshot: dataclasses.QueueSnapshotDTO, + *, + now: float, + ) -> None: + self.latest = snapshot + self._taken_at = now + + async def run() -> int: stop = _install_stop() relay = settings.relay namespace = settings.database.name + telemetry_enabled = telemetry.start_process_telemetry( + TELEMETRY_SERVICE_RELAY, + ) engine = create_engine(settings.database) + telemetry.instrument_engine(engine) session_factory = create_session_factory(engine) publisher = JobPublisher(settings.broker, namespace=namespace) service = AttachmentRelayService( @@ -154,6 +194,12 @@ async def run() -> int: ), publisher=publisher, ) + snapshots = QueueSnapshots() if telemetry_enabled else None + if snapshots is not None: + telemetry.observe_queue( + queue=publisher.queue, + latest=lambda: snapshots.latest, + ) try: logger.info( "Started relay", @@ -172,27 +218,64 @@ async def run() -> int: database_port=settings.database.port, database_name=namespace, database_pool_size=settings.database.pool_size, + telemetry_enabled=telemetry_enabled, + telemetry_endpoint=( + settings.telemetry.otlp_endpoint if telemetry_enabled else None + ), + telemetry_environment=( + settings.telemetry.environment if telemetry_enabled else None + ), ) - await _serve(service, stop=stop) + await _serve(service, stop=stop, snapshots=snapshots) finally: + # закрытие SDK — в том же окне, что клиенты (как у worker): потоки + # стартуют до gather, что не ушло за срок — теряется + closing = telemetry.begin_shutdown() with suppress(Exception): async with asyncio.timeout(_CLOSE_TIMEOUT_SECONDS): await asyncio.gather( engine.dispose(), publisher.aclose(), + telemetry.wait_closed( + closing, + timeout=_CLOSE_TIMEOUT_SECONDS, + ), return_exceptions=True, ) + # после закрытия SDK — только stdout logger.info("Stopped relay", exit_code=EXIT_OK) return EXIT_OK +async def _take_snapshot( + service: AttachmentRelayService, + snapshots: QueueSnapshots | None, +) -> None: + """Снимок очереди не чаще `QUEUE_SNAPSHOT_INTERVAL_SECONDS`, только при + включённой телеметрии; отказ PostgreSQL — пропуск: устаревший снимок + gauge перестаёт отдавать сам.""" + if snapshots is None: + return + now = time.monotonic() + if not snapshots.due(now): + return + try: + snapshot = await service.queue_snapshot() + except exceptions.ServiceUnavailable: + # причину уже записала единица работы + return + snapshots.store(snapshot, now=now) + + async def _serve( service: AttachmentRelayService, *, stop: asyncio.Event, + snapshots: QueueSnapshots | None = None, ) -> None: """Проходы до сигнала. Пакет полон — следующий проход сразу, отказ — пауза - отказа, иначе — пауза опроса.""" + отказа, иначе — пауза опроса. После успешного прохода — снимок очереди + (решение 9).""" relay = settings.relay while not stop.is_set(): try: @@ -210,6 +293,8 @@ async def _serve( logger.error("Relay pass failed", exc_info=e) pause = relay.failure_pause_seconds else: + if not stop.is_set(): + await _take_snapshot(service, snapshots) if result.unconfirmed: pause = relay.failure_pause_seconds elif result.selected >= relay.batch_size: diff --git a/src/schemas/dataclasses/__init__.py b/src/schemas/dataclasses/__init__.py index 3fc27c8..2b94d92 100644 --- a/src/schemas/dataclasses/__init__.py +++ b/src/schemas/dataclasses/__init__.py @@ -7,6 +7,9 @@ from .attachment import ( AttachmentVariantDTO, CleanupPassDTO, FailedJobDTO, + JobDeliveryResultDTO, + JobPublicationDTO, + QueueSnapshotDTO, ReconcileFindingDTO, ReconcilePassDTO, RelayPassDTO, @@ -15,6 +18,7 @@ from .attachment import ( ReplayPassDTO, ReplayResultDTO, StagingCleanupPassDTO, + TraceContextDTO, ) from .chat import ChatFullDTO, ChatPageDTO from .idempotency import IdempotencyRecordDTO @@ -35,8 +39,11 @@ __all__ = [ "CurrentSessionDTO", "FailedJobDTO", "IdempotencyRecordDTO", + "JobDeliveryResultDTO", + "JobPublicationDTO", "MessageFullDTO", "MessagePageDTO", + "QueueSnapshotDTO", "ReconcileFindingDTO", "ReconcilePassDTO", "RelayPassDTO", @@ -47,6 +54,7 @@ __all__ = [ "SessionFullDTO", "SessionTokenDTO", "StagingCleanupPassDTO", + "TraceContextDTO", "UserCredentialsDTO", "UserFullDTO", ] diff --git a/src/schemas/dataclasses/attachment.py b/src/schemas/dataclasses/attachment.py index 7b0f58a..91b127a 100644 --- a/src/schemas/dataclasses/attachment.py +++ b/src/schemas/dataclasses/attachment.py @@ -6,10 +6,12 @@ from uuid import UUID from src.schemas.enums import ( AttachmentErrorCode, + AttachmentJobReason, AttachmentJobState, AttachmentStatus, AttachmentVariantName, ImageType, + JobDeliveryOutcome, ReconcileFinding, ReconcileStrategy, ) @@ -123,6 +125,64 @@ class AttachmentJobDTO: published_at: datetime | None = None finished_at: datetime | None = None attempt_base: int = 0 + # контекст W3C server span загрузки (design change + # `job-trace-propagation`, решение 4); NULL — строка прежней версии или + # реплика без телеметрии + traceparent: str | None = None + tracestate: str | None = None + + +@dataclass(frozen=True, slots=True) +class TraceContextDTO: + """Контекст W3C Trace Context: значение заголовков `traceparent` и + `tracestate` (design change `job-trace-propagation`, решения 1, 4). + Только идентификаторы трассы и span и флаги, без baggage.""" + + traceparent: str + tracestate: str | None = None + + +@dataclass(frozen=True, slots=True) +class JobPublicationDTO: + """Элемент публикации relay (решение 3): `attempt` — номер попытки в + сообщении, `replayed` — задание возвращено replay, `retry_reason` — + причина повтора (прежний `last_error_code`), `trace_context` — контекст + задания или `None`.""" + + job_id: UUID + body: bytes + attempt: int + replayed: bool = False + retry_reason: str | None = None + trace_context: TraceContextDTO | None = None + + +@dataclass(frozen=True, slots=True) +class JobDeliveryResultDTO: + """Итог доставки worker (решение 8): исход, взятая попытка (у `dropped` + — нет), причина у `retry` и `failed`, код ошибки у `failed`, время до + готовности — только у `ready` без replay.""" + + outcome: JobDeliveryOutcome + attempt: int | None = None + reason: AttachmentJobReason | None = None + error_code: AttachmentErrorCode | None = None + time_to_ready_seconds: float | None = None + + +@dataclass(frozen=True, slots=True) +class QueueSnapshotDTO: + """Снимок незавершённых заданий по стадиям (решение 9): время снимка, + `scheduled` — ждут срока, `outbox` — срок наступил, не опубликованы, + `published` — опубликованы, не взяты, `processing` — идёт попытка; + `oldest_created_at` — приём старейшего незавершённого или `None`.""" + + taken_at: datetime + scheduled: int + outbox: int + published: int + processing: int + oldest_created_at: datetime | None = None @dataclass(frozen=True, slots=True) diff --git a/src/schemas/jobs/attachment.py b/src/schemas/jobs/attachment.py index 31a85a4..77287ec 100644 --- a/src/schemas/jobs/attachment.py +++ b/src/schemas/jobs/attachment.py @@ -16,18 +16,19 @@ from src.schemas.dataclasses import AttachmentJobDTO from src.utils.constants import ( ATTACHMENT_JOB_SCHEMA_VERSION, ATTACHMENT_JOB_TYPE, + TRACEPARENT_PATTERN, + TRACESTATE_MAX_LENGTH, ) from src.utils.utc import to_rfc3339 -_TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$" -_TRACESTATE_MAX_LENGTH = 512 - class AttachmentJobMessage(BaseModel): """Тело сообщения; лишнее поле и чужая версия — ошибка разбора. - `traceparent` и `tracestate` на этом уровне приложение не пишет и не - читает, но принимает: их допускает контракт. + `traceparent` и `tracestate` в теле приложение не пишет и не читает, но + принимает: их допускает контракт. Контекст едет в заголовках сообщения + AMQP с тем же значением W3C (design change `job-trace-propagation`, + решение 1). """ model_config = ConfigDict(extra="forbid") @@ -39,11 +40,11 @@ class AttachmentJobMessage(BaseModel): pipeline_version: Annotated[int, Field(ge=1, strict=True)] attempt: Annotated[int, Field(ge=1, strict=True)] created_at: datetime - traceparent: Annotated[str, Field(pattern=_TRACEPARENT_PATTERN)] | None = ( + traceparent: Annotated[str, Field(pattern=TRACEPARENT_PATTERN)] | None = ( None ) tracestate: ( - Annotated[str, Field(max_length=_TRACESTATE_MAX_LENGTH)] | None + Annotated[str, Field(max_length=TRACESTATE_MAX_LENGTH)] | None ) = None diff --git a/src/utils/constants.py b/src/utils/constants.py index 455fba5..8fc688f 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -132,6 +132,10 @@ PAGE_LIMIT_DEFAULT = 50 DB_APPLICATION_NAME = "mtusi-messenger" # секунды на проверку Postgres в /health/ready READINESS_DB_TIMEOUT_SECONDS = 2 +# логгер пула engine: SQLAlchemy называет его модулем и классом пула +# (`CountingQueuePool`, design change `job-trace-propagation`, решение 10); +# журнал держит его на WARNING, как прежний пул SQLAlchemy +DB_POOL_LOGGER = "src.infra.db.engine.CountingQueuePool" # секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой # срок; дальше соединение обрывается DB_CLOSE_TIMEOUT_SECONDS = 2 @@ -224,6 +228,64 @@ ATTR_RENDER_OUTCOME = "messenger.render.outcome" ATTR_RENDER_EXIT_CODE = "messenger.render.exit_code" ATTR_RENDER_PEAK_KIB = "messenger.render.peak_kib" +# сквозная трасса и сигналы уровня 4 (design change `job-trace-propagation`, +# решения 1–13) +TELEMETRY_SERVICE_RELAY = "messenger-relay" +# W3C Trace Context: версия 00, как шаблон contracts/jobs.schema.json; те же +# значения — колонки attachment_jobs и заголовки сообщения AMQP +TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$" +TRACESTATE_MAX_LENGTH = 512 +TRACE_HEADER_TRACEPARENT = "traceparent" +TRACE_HEADER_TRACESTATE = "tracestate" +# span брокера (semantic conventions messaging) +MESSAGING_SYSTEM = "rabbitmq" +MESSAGING_OPERATION_PUBLISH = "publish" +MESSAGING_OPERATION_PROCESS = "process" +ATTR_MESSAGING_SYSTEM = "messaging.system" +ATTR_MESSAGING_DESTINATION = "messaging.destination.name" +ATTR_MESSAGING_OPERATION_TYPE = "messaging.operation.type" +ATTR_MESSAGING_OPERATION_NAME = "messaging.operation.name" +ATTR_JOB_ATTEMPT = "messenger.job.attempt" +ATTR_JOB_REPLAYED = "messenger.job.replayed" +ATTR_JOB_RETRY_REASON = "messenger.job.retry_reason" +ATTR_JOB_REDELIVERED = "messenger.job.redelivered" +ATTR_JOB_REASON = "messenger.job.reason" +ATTR_JOB_ERROR_CODE = "messenger.job.error_code" +# метрики уровня 4 (таблица решения 13) +METRIC_JOB_TIME_TO_READY = "messenger.job.time_to_ready" +METRIC_QUEUE_DEPTH = "messenger.queue.depth" +METRIC_QUEUE_OLDEST_AGE = "messenger.queue.oldest_age" +METRIC_DB_CONNECTION_COUNT = "db.client.connection.count" +METRIC_DB_CONNECTION_MAX = "db.client.connection.max" +METRIC_DB_CONNECTION_PENDING = "db.client.connection.pending_requests" +METRIC_DB_CONNECTION_TIMEOUTS = "db.client.connection.timeouts" +METRIC_WORKER_BUSY = "messenger.worker.busy" +METRIC_WORKER_CAPACITY = "messenger.worker.capacity" +METRIC_WORKER_WAITING = "messenger.worker.waiting" +METRIC_CONTAINER_CPU_TIME = "container.cpu.time" +METRIC_CONTAINER_MEMORY_USAGE = "container.memory.usage" +METRIC_CONTAINER_CPU_LIMIT = "messenger.container.cpu.limit" +METRIC_CONTAINER_MEMORY_LIMIT = "messenger.container.memory.limit" +ATTR_QUEUE_STAGE = "messenger.queue.stage" +ATTR_DB_POOL_NAME = "db.client.connection.pool.name" +ATTR_DB_CONNECTION_STATE = "db.client.connection.state" +DB_CONNECTION_STATE_USED = "used" +DB_CONNECTION_STATE_IDLE = "idle" +# стадии незавершённых заданий: ждёт срока следующей попытки, срок наступил и +# не опубликовано, опубликовано и не взято, идёт попытка +QUEUE_STAGE_SCHEDULED = "scheduled" +QUEUE_STAGE_OUTBOX = "outbox" +QUEUE_STAGE_PUBLISHED = "published" +QUEUE_STAGE_PROCESSING = "processing" +# время до ready, секунды: путь без повторов 0,5–2 с, бюджет smoke 60 с, +# паузы повторов до 75 с, возврат по аренде 70 с, наибольшая пауза 300 с +TIME_TO_READY_BUCKETS = (0.25, 0.5, 1, 2.5, 5, 10, 20, 30, 60, 120, 300, 600) +# снимок очереди relay: не чаще раза в интервал; старше срока не отдаётся +QUEUE_SNAPSHOT_INTERVAL_SECONDS = 5 +QUEUE_SNAPSHOT_STALE_SECONDS = 30 +# cgroup v2 контейнера изнутри (решение 12) +CGROUP_ROOT = "/sys/fs/cgroup" + # хранилище объектов (S3) # имя bucket по правилам S3: 3–63 символа, строчные латинские буквы, # цифры, точка и дефис, по краям — буква или цифра diff --git a/src/worker/main.py b/src/worker/main.py index bed1718..ac55c57 100644 --- a/src/worker/main.py +++ b/src/worker/main.py @@ -42,6 +42,7 @@ from src.infra.db.uow import SqlAlchemyUnitOfWork from src.infra.logger import AbstractLogger, get_logger from src.infra.render import ImageRenderer from src.infra.s3 import ObjectStorage, create_object_storage +from src.schemas.dataclasses import JobDeliveryResultDTO from src.schemas.enums import JobDeliveryOutcome, JobOutcome from src.utils.constants import ATTACHMENT_JOB_TYPE, TELEMETRY_SERVICE_WORKER @@ -106,6 +107,9 @@ async def run() -> int: stop=stop, ) + load = telemetry.WorkerLoad() + telemetry.observe_worker(capacity=worker.concurrency, load=load) + try: if not ( settings.s3.access_key_id.get_secret_value() @@ -146,7 +150,7 @@ async def run() -> int: settings.telemetry.environment if telemetry_enabled else None ), ) - await _serve(make_service, namespace=namespace, stop=stop) + await _serve(make_service, namespace=namespace, stop=stop, load=load) finally: # одним сроком, а не по очереди: сумма не растёт с числом клиентов # (S5). Закрытие SDK — в том же окне: потоки стартуют до gather и @@ -173,6 +177,7 @@ async def _serve( *, namespace: str, stop: asyncio.Event, + load: telemetry.WorkerLoad, ) -> None: """Соединения с брокером до сигнала.""" worker = settings.worker @@ -197,7 +202,7 @@ async def _serve( continue logger.info("Connected to broker", broker_queue=consumer.queue) pump = asyncio.create_task( - _pump(consumer, make_service, slots, tasks, stop), + _pump(consumer, make_service, slots, tasks, stop, load), ) stopping = asyncio.create_task(stop.wait()) await asyncio.wait( @@ -236,12 +241,13 @@ async def _pump( slots: asyncio.Semaphore, tasks: set[asyncio.Task[None]], stop: asyncio.Event, + load: telemetry.WorkerLoad, ) -> None: """Каждая доставка — своя задача со своим контекстом журнала и своим сервисом.""" async for delivery in consumer.deliveries(): task = asyncio.create_task( - _handle(make_service, delivery, slots, stop), + _handle(make_service, delivery, slots, stop, load=load), ) tasks.add(task) task.add_done_callback(tasks.discard) @@ -252,45 +258,75 @@ async def _handle( delivery: JobDelivery, slots: asyncio.Semaphore, stop: asyncio.Event, + *, + load: telemetry.WorkerLoad | None = None, ) -> None: """Подтверждение — только после итога сервиса. Отмена при остановке сообщение не подтверждает: брокер вернёт его после закрытия соединения. Сообщение сверх конкуренции ждёт место без взятия; после сигнала остановки - попытка не начинается.""" - async with slots: - if stop.is_set(): - return - # span и наблюдение histogram — после места конкуренции: ожидание - # места — не работа (design change otel-telemetry, решение 11); - # подтверждение — внутри span - with telemetry.consumer_span( - queue=queue_name(settings.database.name), - job_type=ATTACHMENT_JOB_TYPE, - ) as observation: - started = time.monotonic() + попытка не начинается. `load` — счётчики «ждут места» и «заняты» для + метрик насыщения (design change `job-trace-propagation`, решение 11), + снимаются в `finally`.""" + if load is None: + load = telemetry.WorkerLoad() + load.waiting += 1 + waiting = True + try: + async with slots: + load.waiting -= 1 + waiting = False + load.busy += 1 try: - outcome = await make_service().handle( - body=delivery.body, - redelivered=delivery.redelivered, - ) - except Exception as e: - observation.finish( - outcome=JobDeliveryOutcome.ERROR.value, - duration_seconds=time.monotonic() - started, - error=e, - ) - logger.error("Job handling failed", exc_info=e) - with suppress(TimeoutError): - await asyncio.wait_for( - stop.wait(), - timeout=settings.worker.reconnect_seconds, - ) - outcome = JobDeliveryOutcome.ERROR - observation.finish( - outcome=outcome.value, - duration_seconds=time.monotonic() - started, + if stop.is_set(): + return + await _process(make_service, delivery, stop) + finally: + load.busy -= 1 + finally: + if waiting: + load.waiting -= 1 + + +async def _process( + make_service: Callable[[], AttachmentProcessingService], + delivery: JobDelivery, + stop: asyncio.Event, +) -> None: + """Доставка на месте конкуренции. Span и наблюдение histogram — после + места: ожидание места — не работа (design change otel-telemetry, решение + 11); подтверждение — внутри span. Span — дочерний к контексту из заголовков + сообщения, с link на него; без контекста — корень (design change + job-trace-propagation, решение 2).""" + with telemetry.consumer_span( + queue=queue_name(settings.database.name), + job_type=ATTACHMENT_JOB_TYPE, + parent=delivery.trace_context, + redelivered=delivery.redelivered, + ) as observation: + started = time.monotonic() + try: + result = await make_service().handle( + body=delivery.body, + redelivered=delivery.redelivered, ) - await _settle(delivery, outcome.action) + except Exception as e: + result = JobDeliveryResultDTO(outcome=JobDeliveryOutcome.ERROR) + observation.finish( + result=result, + duration_seconds=time.monotonic() - started, + error=e, + ) + logger.error("Job handling failed", exc_info=e) + with suppress(TimeoutError): + await asyncio.wait_for( + stop.wait(), + timeout=settings.worker.reconnect_seconds, + ) + observation.finish( + result=result, + duration_seconds=time.monotonic() - started, + ) + await _settle(delivery, result.outcome.action) async def _settle(delivery: JobDelivery, action: JobOutcome) -> None: diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index b87cec8..4988fce 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -49,11 +49,14 @@ services: # relay без перезапуска: его останавливают и убивают сами проверки; опрос чаще # и порог потерянного сообщения короче, чтобы тесту не ждать 5 минут (design # change pipeline-reliability, решение 15) + # Телеметрия выключена, как у api и worker (design change + # job-trace-propagation, решение 7) relay: restart: "no" environment: RELAY__POLL_INTERVAL_SECONDS: "0.2" RELAY__REPUBLISH_AFTER_SECONDS: "5" + TELEMETRY__ENABLED: "false" # worker со сроками, сравнимыми со временем теста, и без перезапуска: его # останавливают и убивают сами проверки (design change async-attachments, # решение 15). Сумма пауз 14–28 с больше возврата S3 (~8 с): «Временная diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 96eada7..dc88d57 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -337,6 +337,10 @@ def main() -> int: relay, "-e", f"DATABASE__NAME={test_db}", + # и relay — без телеметрии (design change job-trace-propagation, + # решение 7) + "-e", + "TELEMETRY__ENABLED=false", "relay", quiet=True, )