feat: propagate trace context through outbox and add pipeline saturation metrics

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 19:54:37 +03:00
co-authored by Claude Opus 5.5
parent ff0073e8e3
commit 72cfa9aaf6
64 changed files with 4699 additions and 552 deletions
+5 -1
View File
@@ -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.<конфигурация>`);
+12 -3
View File
@@ -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`
+8
View File
@@ -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/<domain>.py` — DTO между repo → service → api;
`src/schemas/enums/<domain>.py` — `StrEnum` доменов. HTTP-модели
(pydantic) лежат не здесь, а в `src/api/schemas/` (`api-layer.md`).
+15 -1
View File
@@ -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`, без
+12 -2
View File
@@ -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.
### Исключение: запись ранней остановки
+8
View File
@@ -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` его не пересоздаст: повтор миграции
+6 -1
View File
@@ -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`);
+7 -3
View File
@@ -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`
+5 -3
View File
@@ -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`
+4 -2
View File
@@ -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/`
+50 -23
View File
@@ -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 <LB> 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 <LB> 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).
+17 -4
View File
@@ -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)`.
+47 -11
View File
@@ -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
File diff suppressed because it is too large Load Diff
+3 -3
View File
@@ -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): на нём слушает приложение, его же
+31 -17
View File
@@ -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 <LB> 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 <LB> 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 <LB> 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 <LB> 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 <LB> 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/<domain>.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/<domain>.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/<domain>.py # SqlAlchemy<Domain>Repository: одна атомарная операция на метод; 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/<domain>.py # <Domain>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; строка с ключом <id>/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(<service.name>): 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(<service.name>, 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_<service> на каждый сервис, 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_<service> на каждый сервис, 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-<n> с лимитом 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 с ревизией до и после)
+6 -3
View File
@@ -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/<change>`, 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` через
+23 -1
View File
@@ -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).
+148 -8
View File
@@ -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 требует подтверждения, какие реальные процессы/хранилища перезапущены.
+4
View File
@@ -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:
+5 -4
View File
@@ -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"
# секунды между отправками метрик
+3 -2
View File
@@ -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:
@@ -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": [
{
@@ -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")
@@ -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).
+41 -41
View File
@@ -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 <LB> trace-chain` (16, спек «Цепочка и сигналы уровня 4 находятся»): пять частей решения
- [x] 9.1 Команда `driver.py --port <LB> 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 (после коммита кода основной сессией)
+85
View File
@@ -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()
+4
View File
@@ -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,
+10 -4
View File
@@ -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:
+35
View File
@@ -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,
*,
+103
View File
@@ -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))
@@ -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,
+140
View File
@@ -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
@@ -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):
+716 -5
View File
@@ -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")
@@ -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
+15
View File
@@ -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 в формате контракта бросает
+11 -3
View File
@@ -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)
+6 -4
View File
@@ -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, ни отправки, ни полей трассы в журнале
+17 -1
View File
@@ -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,
+62
View File
@@ -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,
*,
+18
View File
@@ -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
+79 -27
View File
@@ -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; её прерывает
+34 -4
View File
@@ -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,
*,
+77 -22
View File
@@ -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:
+40
View File
@@ -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,
+15
View File
@@ -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):
+7
View File
@@ -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"},
},
},
)
+20 -4
View File
@@ -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",
+112
View File
@@ -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",
)
+114 -254
View File
@@ -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)
+19 -3
View File
@@ -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)
+200
View File
@@ -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)
+204
View File
@@ -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",
)
+222
View File
@@ -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(),
),
)
+23 -5
View File
@@ -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(
+88 -3
View File
@@ -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:
+8
View File
@@ -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",
]
+60
View File
@@ -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)
+8 -7
View File
@@ -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
+62
View File
@@ -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 символа, строчные латинские буквы,
# цифры, точка и дефис, по краям — буква или цифра
+72 -36
View File
@@ -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:
+3
View File
@@ -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 с): «Временная
+4
View File
@@ -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,
)