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:
@@ -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
@@ -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`
|
||||
|
||||
@@ -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
@@ -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`, без
|
||||
|
||||
@@ -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.
|
||||
|
||||
### Исключение: запись ранней остановки
|
||||
|
||||
@@ -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` его не пересоздаст: повтор миграции
|
||||
|
||||
@@ -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`);
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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
@@ -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
@@ -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)`.
|
||||
|
||||
@@ -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
@@ -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): на нём слушает приложение, его же
|
||||
|
||||
@@ -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 с ревизией до и после)
|
||||
|
||||
@@ -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
@@ -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).
|
||||
|
||||
@@ -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 требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
|
||||
@@ -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
@@ -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
@@ -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).
|
||||
|
||||
@@ -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 (после коммита кода основной сессией)
|
||||
|
||||
@@ -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()
|
||||
@@ -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,
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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,
|
||||
*,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 в формате контракта бросает
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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, ни отправки, ни полей трассы в журнале
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
*,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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; её прерывает
|
||||
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -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"},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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",
|
||||
)
|
||||
@@ -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(),
|
||||
),
|
||||
)
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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 с): «Временная
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user