feat: add OpenTelemetry SDK, collector and telemetry stores

Collector (contrib), Prometheus, Loki, Tempo and Grafana with provisioning
from git; SDK in API and worker with level 3 metrics, traces and logs
carrying trace_id/span_id; telemetry off by default outside the stand;
broker healthcheck runs as the broker user so a fresh stand starts once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 10:19:50 +03:00
co-authored by Claude Opus 5.5
parent 9b35c256b7
commit a4497e3f32
62 changed files with 6175 additions and 214 deletions
+9
View File
@@ -125,6 +125,15 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP
(`/chats/{chat_id}` вместо `/api/v1/chats/{chat_id}`). Источник —
таблица из публичного `iter_route_contexts(app.routes)` в
`request_context.py`. Структуру роутеров ради логов не менять.
- С лабы 6 тот же middleware открывает server span и пишет histogram
`http.server.request.duration` (design change `otel-telemetry`, решение 10): не для health
(`HEALTH_PATHS` — ни записи, ни span, ни метрики), имя и атрибуты — после маршрутизации, из
той же таблицы шаблонов, что итоговая запись (`http.route` без маршрута нет), метод — со
стандартным набором или `_OTHER`, `messenger.request_id` — только в span. Итоговая запись
пишется внутри span (у неё `trace_id`); 5xx и исключение — `ERROR` и `error.type`. Входящий
`traceparent` не извлекается. Нестандартный метод, который не знает парсер uvicorn (BREW),
до middleware не доходит (`KNOWN_ISSUES.md`). `FastAPI(version=SERVICE_VERSION)` — та же
версия, что `service.version`.
- `X-Instance-Id` (лаба 3) ставит тот же middleware, что и
`X-Request-Id`, на каждый ответ, включая health, 404 и 405. Значение
— `settings.app.instance_id` (по умолчанию hostname процесса, в
+7
View File
@@ -173,6 +173,13 @@ change `s3-storage`, решение 9): старт стенда перечисл
`BENCH_BROKER_*`, `BENCH_RELAY_*`, `BENCH_WORKER_*` рабочего стенда; плагин метрик
брокера и политика перезапуска worker — только его `queue.compose.yml`; остальные
профили меряют реплику;
- **телеметрия** (с лабы 6, design change `otel-telemetry`, решение 20) выключена:
`TELEMETRY__ENABLED: "false"` у `api` и `worker` в `bench.compose.yml`, сервисы телеметрии
описаны основным файлом, но ни один профиль их не запускает. `GRAFANA_ADMIN_PASSWORD` compose
требует при разборе — его, как секреты S3, генерирует `compose_env`. Новые ключи окружения
реплик (`TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`) попадают в `stand.app_env`: метки
до лабы 6 с новыми не сравниваются (их в этом репозитории нет). Профиль трека 1 с
телеметрией включает её явно своим окружением;
- **PostgreSQL `max_connections`:** 100, как у образа (`-c
max_connections` в override); у серий — из конфигурации ячейки,
лимиты конфигурации в паспорте (`limits.<конфигурация>`);
+32 -1
View File
@@ -382,10 +382,41 @@ Design change `async-attachments`, решения 4, 6, 12, 14.
«cleaner key list staging prefix» и «cleaner key list database prefix».
- **`restart.sh`** перезапускает и брокер; relay, worker и уборщика не трогает: защита
вызывает hook при остановленном worker, и он останется остановленным.
- **Суммы:** постоянные 9,0 CPU, 4992 МБ, с разовыми 10,0 CPU, 5376 МБ; соединений
- **Суммы** (до лабы 6; с телеметрией — раздел «Наблюдаемость»): постоянные 9,0 CPU, 4992 МБ, с разовыми 10,0 CPU, 5376 МБ; соединений
PostgreSQL `API_REPLICAS × 10 + migrate 1 + cleaner 1 + worker 2 + relay 1` = 25, при
замене 35.
## Наблюдаемость (с лабы 6)
Design change `otel-telemetry`, решения 1, 7, 14–20; правила конфигураций — `telemetry.md`.
- **Сервисы:** `otel-collector` (contrib 0.164.0), `prometheus` (v3.15.1), `loki` (3.7.9),
`tempo` (3.1.1), `grafana` (13.3.1) — тег и digest индекса, `restart: unless-stopped`,
`GOMEMLIMIT` ~80 % лимита (Go лимит cgroup не видит). Каждый конфиг `infra/otel/` — отдельный
bind mount файла длинной записью; volumes `prometheus_data:/prometheus`, `loki_data:/loki`,
`tempo_data:/var/tempo` (образы стартуют на пустых без chown), у Grafana — tmpfs
`/var/lib/grafana` (пароль из `.env` действует на каждом старте, правки UI не переживают
рестарт).
- **Сеть `telemetry`** (не `internal`: иначе не работает порт Grafana): хранилища и Grafana —
только в ней, Collector — в `default` и `telemetry`. Наружу — только
`127.0.0.1:${GRAFANA_OUT_PORT:-3000}:3000`. Сервисы приложения от телеметрии не зависят
(`depends_on` нет), сервисы телеметрии друг от друга — тоже.
- **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` — адрес, не секрет).
- **Брокер** (решение 19): healthcheck — exec-форма `gosu rabbitmq rabbitmq-diagnostics -q
check_port_connectivity`: CLI от root на пустом volume создавал `.erlang.cookie` (0400, root)
раньше сервера, тот падал на `eacces`. Стенд с нуля проверяет `driver.py stand-from-scratch`
(свой проект, удаляет свои volumes сам).
- **`restart.sh`** сервисы телеметрии не трогает (решение 6).
- **Суммы:** постоянные лимиты 11,5 CPU / 7040 МиБ, с одноразовыми 12,5 CPU / 7424 МиБ при ВМ
12 CPU / 7934 МиБ; телеметрия — 2,5 CPU / 2048 МиБ; пики и правило «лимит ≥ 1,5 × пика» —
`evidence/telemetry/budget.md`. Соединений PostgreSQL телеметрия не добавляет.
- **CI** — `configs` для семи файлов, у Prometheus, Loki и Tempo `volumes: !override` с одним
именованным volume, у Collector и Grafana `volumes: !reset []`, порт Grafana `!reset []`.
## Обновление кода на стенде
- `make run_docker` после пересборки пересоздаёт реплики, образ которых
+9
View File
@@ -292,6 +292,15 @@ paths:
- обхода и пропуска после отказа, как у Valkey, нет: без S3 путь
вложений всё равно 503. `/health/ready` S3 не проверяет (спек
`health`, design change `s3-storage`): текст работает без него.
- Телеметрия (`telemetry/`, с лабы 6, design change `otel-telemetry`, решения 4, 8, 12, 13;
правило `telemetry.md`): глобальных провайдеров OpenTelemetry нет — состояние пакета, при
выключенной телеметрии все вызовы no-op. Запускает её точка входа процесса (API — lifespan,
worker — `run()`), не модули клиентов. Дочерний span — в единственной точке вызова клиента:
`ObjectStorage._call` (`S3.<Операция>`, без ключа, `StoredObjectMissing` у HEAD и DELETE —
исход), `Cache.get` / `Cache.set` (`messenger.cache.result`: `hit`, `miss`, `stored`, `error`,
`skipped`), `ImageRenderer.render`, `SqlAlchemyUnitOfWork._commit` (`COMMIT`), запросы —
слушатели `instrument_engine` (фабрика engine о телеметрии не знает). Span не меняет ни
перевода ошибок, ни сроков; новое чтение из хранилища — внутри уже обёрнутого вызова.
- Клиенты внешних сервисов: адреса и секреты из `settings`
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
переводятся в доменные исключения. Логи — по `logging.md`, без
+14
View File
@@ -97,6 +97,20 @@ paths:
`log_config=None` uvicorn при старте применит свой `LOGGING_CONFIG`
поверх нашего. Access-лог пишет свой middleware (`api-layer.md`).
### Телеметрия журнала (с лабы 6)
Design change `otel-telemetry`, решения 2 и 12; правило `telemetry.md`. В обеих цепочках
(`processors` перед `wrap_for_formatter` и `foreign_pre_chain`) — `export_to_telemetry`, затем
`add_trace_fields`: запись уходит в логгер SDK (тело — `event`, уровень, время записи,
остальные поля — атрибуты, контекст — текущий), затем stdout получает `trace_id` и `span_id`
активного записывающего span. Вне span (старт, остановка, health, фоновые циклы) полей нет;
без телеметрии хуков нет — записи прежние. `logger.py` SDK не импортирует. Записи логгеров
`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` без значений. Запрет содержимого раздела ниже
действует и на отправленные записи: в Loki — те же записи, что в stdout.
### Исключение: запись ранней остановки
`src/infra/early_stop.py` пишет одну запись мимо structlog: сигнал
+11
View File
@@ -97,6 +97,17 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n
`REPORT.md` (design change `upload-memory`, решение 6). Проверки лабы 3 (≥2 реплики, failover,
гонка через разные реплики) — только на стенде compose через LB.
## Телеметрия (с лабы 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`.
Остановка: API закрывает SDK после «Stopped API» и ждёт не дольше
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с; 8 с дренажа + 1 с < 10 с), worker — в окне `gather`
закрытия клиентов (0,5 с; худший случай прежний, 9,5 с); `shutdown()` провайдеров — в
daemon-потоках, процесс их не ждёт. Без Collector и при замороженном Collector сроки прежние
(`driver.py telemetry-outage`).
## Уборщик (с лабы 4)
`python -m src.cleaner [--once]` → `src/cleaner/__main__.py` →
+18
View File
@@ -242,6 +242,24 @@ run_relay` — те же мосты. Имена skeleton: `BROKER_URL_FILE` →
`WORKER_CONCURRENCY`, `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS` → поля `[worker]`;
`STAGING_RETENTION_SECONDS` → `[cleaner] staging_retention_seconds`.
### Телеметрия (с лабы 6)
`[telemetry]` (класс `Telemetry`, design change `otel-telemetry`, решение 8) читают только
процессы API и worker: `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` и
`config_example.toml` включения нет: файл монтируется и в консоль. Разовая подмена —
`TELEMETRY__*`. **`OTEL_*` — не настройки**, как любые переменные без секции: процесс с
включённой телеметрией удаляет их из окружения и пишет `warning` с именами. Имена skeleton:
`OTEL_SERVICE_NAME` → константы `TELEMETRY_SERVICE_API` / `_WORKER`,
`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`
— переменные compose, приложение их не читает.
### Уборщик (с лабы 4)
`[cleaner]` (класс `Cleaner`, design change `upload-consistency`,
+9
View File
@@ -433,6 +433,15 @@ paths:
- девять сценариев `queue-overload` с открытой нагрузкой и счётчиками — исключения сверки:
`make bench_queue QUEUE_LABEL=baseline4` → `evidence/queue/baseline4/summary.md`.
С лабы 6 (design change `otel-telemetry`, решение 20) телеметрия на тестовых стендах выключена:
`make test_isolated` передаёт `-e TELEMETRY__ENABLED=false` контейнерам API и worker, стенд
отказов — `TELEMETRY__ENABLED: "false"` у `api` и `worker` в `failures.compose.yml`; сервисы
телеметрии они не запускают (старт списком), а `GRAFANA_ADMIN_PASSWORD` compose требует только
при разборе — его даёт `make env_setup`. «Started API» их API называет `telemetry_enabled:
false`. Сценарии `observability` по HTTP-тестам не проверяются: их проверяют быстрые тесты
`service-tests/` и команды драйвера `telemetry-check`, `telemetry-outage`, `stand-from-scratch`
на рабочем стенде.
Проверки отказов реплик (остановка, kill, зависание, rolling update) —
не pytest, а `make test-failover`, профиль `failover` стенда `bench/`
(`make bench_failover`, `bench.md`), команды драйвера `kill-inflight`,
+90
View File
@@ -0,0 +1,90 @@
---
paths:
- "src/infra/telemetry/**"
- "infra/otel/**"
---
# Телеметрия (с лабы 6)
Спеки `observability`, `service-logging` («Связь записей с трассой», «Журнал в хранилище
логов»), `service-configuration` («Параметры телеметрии»), `graceful-shutdown` («Остановка при
недоступном Collector»); решения — design change `otel-telemetry` (номера ниже). Здесь то, что
легко нарушить.
## SDK в процессе (`src/infra/telemetry/`)
- **Только API и worker** (решение 5): `start_process_telemetry(<имя>)` после
`early_stop.disarm()`, затем `instrument_engine(engine)`. Relay, уборщик, миграции и процесс
обработки SDK не запускают; окружение процесса обработки — прежнее, без `OTEL_*` и адреса.
- **Настройки — только `[telemetry]`** (решение 8): ресурс конструктором без детекторов, sampler
`ALWAYS_ON`, лимиты 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()`
корня).
- **Атрибуты** (решения 10–12): метки метрик — только метод (стандартный или `_OTHER`), полный
шаблон маршрута, код статуса, тип и исход задания. Ни `url.path`, `url.query` (в ней
`filename`), заголовков, `client.address`, ключа объекта S3 и кэша (в них id), ни значений
параметров SQL (`db.query.text` — параметризованный текст). Ошибка — статус `ERROR` и
`error.type` (класс), `record_exception` не вызывать: текст исключения бывает с данными.
`messenger.request_id` — только в span, не в метриках. Имена — константы
`src/utils/constants.py`.
- **Новая точка вызова хранилища** — span в единственном месте вызова (как `_call` S3,
`Cache.get`/`set`), а не библиотека автоинструментирования: `instrumentation-sqlalchemy`
несовместим с SQLAlchemy 2.1, остальные патчат клиенты глобально (решение 4).
- **Журнал** (решения 2, 12): `src/infra/logger.py` SDK не импортирует — процессоры зовут хуки
пакета. Экспорт стоит раньше полей трассы в обеих цепочках (`processors` и
`foreign_pre_chain`); записи логгеров `opentelemetry.*` не экспортируются, в stdout — не чаще
одной в минуту на логгер (`RateLimitFilter`). API логов SDK без стабильного имени: SDK закреплён
`>=1.45.2,<1.46`, смену ловит `service-tests/unit/test_telemetry.py`.
- **Закрытие со сроком** (решение 13): `shutdown()` провайдеров — в daemon-потоках
(`begin_shutdown`), ожидание не дольше срока (`wait_closed`), не `asyncio.to_thread` и не
`force_flush`: при замороженном Collector `shutdown()` ждёт до 6 с. API — после «Stopped API»,
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с); worker — в окне `gather` закрытия (0,5 с).
- **Исход доставки** (решение 11) называет сервис (`JobDeliveryOutcome`), действие с сообщением
выводится из него; span и histogram пишет точка входа после места конкуренции, `error` — у
непредвиденного исключения.
## Конфигурации (`infra/otel/`)
- **Каждый файл — отдельный bind mount файла** длинной записью (`read_only`, `create_host_path:
false`), не каталог: override CI заменяет их `configs` по одному (`.github/ci/compose.yml`,
`stand-env.sh`). Новый файл — строка в обоих (решение 20).
- **Collector** (решение 14): только приёмник OTLP HTTP `:4318`, `memory_limiter` и `batch` в
каждом pipeline, экспортёры `prometheus` (`:8889`), `otlp_http/loki`, `otlp_http/tempo`;
тип `otlp_http`, а не устаревший `otlphttp`; `debug` и расширения (`pprof`, `zpages`,
`health_check`) не добавлять. Проверка — подкоманда `validate` бинарника образа, в журнале
старта нет `deprecated`.
- **Хранилища** (решение 15): срок хранения 7 суток явно у всех трёх (у Tempo 3.x — два ключа
`block_retention`, backend-scheduler и backend-worker), у Prometheus ещё предел объёма;
данные — именованные volumes, без remote write, OTLP-приёмника Prometheus, admin API и
lifecycle. Проверка — `promtool check config`, `-verify-config` Loki, старт Tempo и
`/status/config`.
- **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`),
установка плагинов из сети — тоже.
- **Сети и порты** (решение 17): хранилища и Grafana — только в сети `telemetry`, Collector — в
обеих; наружу — только Grafana на `127.0.0.1`. Сервисы приложения не ждут сервисов
телеметрии (`depends_on` нет).
- **Healthcheck** (решение 18) — только у Prometheus и Grafana (`wget` в образе); у Collector,
Loki и Tempo оболочки нет, живость — цели `up` в Prometheus и проверка источников.
- **Go и память**: `GOMEMLIMIT` ~80 % лимита контейнера, лимит не меньше 1,5 × измеренного пика
(`evidence/telemetry/budget.md`).
## Проверки
`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).
+9
View File
@@ -105,6 +105,15 @@ change `async-attachments` (2, 6–8) и `pipeline-reliability` (1–9, 19). З
закрытие потребителя 0,5, engine и S3 — одним `gather` под сроком 0,5: 9,5 с < 10 с.
Новые клиенты не добавляют срока. Задание, прерванное остановкой, получает
следующую попытку по аренде: release на пути отмены ненадёжен.
- **Телеметрия** (с лабы 6, design change `otel-telemetry`, решения 5, 11–13): исход доставки
называет сервис — `JobDeliveryOutcome` (`ready`, `failed`, `retry`, `skipped`, `requeued`,
`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 с.
- **Сообщение** — `src/schemas/jobs/attachment.py`, по `contracts/jobs.schema.json`:
только id и служебные поля. Ключи, размер, SHA-256 и тип worker берёт из
PostgreSQL. Не по схеме — `error` без содержимого, `reject(requeue=False)`.
+44 -1
View File
@@ -1,6 +1,6 @@
---
name: run-mtusi-messenger
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS; лаба 5 — RabbitMQ, relay и worker) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, `make s3_check`, check that the S3 bucket is private, run the defense scenario or its failure windows, check the broker, the worker or the relay process, show the pipeline state, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP.
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS; лаба 5 — RabbitMQ, relay и worker; лаба 6 — OTel Collector, Prometheus, Loki, Tempo и Grafana) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, check telemetry (find a request in Loki and Tempo, Grafana provisioning, Collector outage, stand from scratch), run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, `make s3_check`, check that the S3 bucket is private, run the defense scenario or its failure windows, check the broker, the worker or the relay process, show the pipeline state, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP.
---
REST API мессенджера (пользователи, чаты, сообщения) — сервер на
@@ -464,6 +464,49 @@ Gotchas:
- **`pipeline-state` считает задания прежнего уровня как есть:** строка с отметкой без сообщения —
`published_not_taken`, пока relay не снимет отметку по порогу `republish_after_seconds`.
## Лаба 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` — без телеметрии.
```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 stand-from-scratch --runs 2 # ~1 мин на прогон
```
- **`telemetry-check`** — всё через HTTP API Grafana (источники-прокси Prometheus, Loki, Tempo):
вход 401 / 401 / 200, порт только на `127.0.0.1`, источники по uid и их проверка, dashboard
provisioned и отказ его сохранения, цели Prometheus `up`; затем «тихая» база счётчиков (35 с без
изменений), свой пользователь, сообщение, 10 GET чата, 401, 404, `BREW` и `PROPFIND`,
`traceparent`, загрузка и недекодируемый JPEG (12 бит, генератор тестов в образе API).
Сверяет stdout ↔ Loki ↔ Tempo по `X-Request-Id`, трассу worker по `attachment_id`, рост
счётчиков ровно на свои запросы и задания по обеим репликам, span S3 с ошибкой при `docker
compose pause s3` (`unpause` в `finally`), отсутствие трасс health и чужих корней, сети
хранилищ из `api` и `worker`, разовый контейнер 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.
- **`stand-from-scratch`** — только свой проект (`--project`, по умолчанию `mtusi-lab6-scratch`;
рабочий — код 2): `make run_docker` с `COMPOSE_PROJECT_NAME` и свободными портами хоста, затем
состояния, `RestartCount`, `eacces` / `permission denied` в журналах, provisioning Grafana,
`make test` через свой LB; `down -v` своего проекта в начале, после каждого прогона и при
Ctrl+C. Рабочий стенд лучше остановить заранее (`make stop`): два стенда — 14 ГиБ лимитов на ВМ
7,75 ГиБ; ID его контейнеров команда сверяет. После — `docker compose start`, а не `up`:
`make run_docker` проекта scratch пересобирает общий тег `mtusi-messenger:lab6`, и `up`
пересоздал бы реплики рабочего стенда.
- **Gotchas:** Tempo 3.1 на неизвестный trace-id отвечает 200 с пустой трассой; трасса без
корня — ещё не вся (дочерние span приходят раньше); итоговая запись о запросе пишется после
отправки ответа — ждать её опросом. `BREW` не доходит до приложения (`KNOWN_ISSUES.md`).
## Direct invocation (без HTTP)
Для правок в `src/core/` сервисы вызываются поверх единицы работы, сервер не
File diff suppressed because it is too large Load Diff
+21 -2
View File
@@ -1,7 +1,7 @@
# Шаблон .env: `make env_setup` создаёт из него .env и подставляет
# случайные значения в пустые POSTGRES_PASSWORD, VALKEY_PASSWORD,
# RABBITMQ_DEFAULT_PASS и секреты S3 (S3_ROOT_*, S3_JWT_SIGNING_KEY,
# S3_API_*, S3_CLEANER_*, S3_WORKER_*).
# RABBITMQ_DEFAULT_PASS, секреты S3 (S3_ROOT_*, S3_JWT_SIGNING_KEY,
# S3_API_*, S3_CLEANER_*, S3_WORKER_*) и GRAFANA_ADMIN_PASSWORD.
# Существующий .env он не перезаписывает, а дописывает в конец
# переменные шаблона, которых в нём нет: секреты — случайными, остальные
# — значениями шаблона; печатает только имена.
@@ -21,6 +21,16 @@
# не файл); WORKER_CONCURRENCY: [worker] concurrency; JOB_MAX_ATTEMPTS:
# [worker] max_attempts; JOB_TIMEOUT_SECONDS: [worker] job_timeout_seconds;
# STAGING_RETENTION_SECONDS: [cleaner] staging_retention_seconds.
# С 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;
# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf — постоянно (установлен только
# экспортёр OTLP/HTTP protobuf); OTEL_RESOURCE_ATTRIBUTES — [telemetry]
# environment (deployment.environment.name), service.* вычисляет код.
# Включает телеметрию compose (TELEMETRY__ENABLED у api и worker), в .env её
# нет: консоль — без телеметрии.
# порт сервиса ([app] port): на нём слушает приложение, его же
# публикует compose, на нём же healthcheck
@@ -129,6 +139,15 @@ BROKER__PORT=${RABBITMQ_OUT_PORT}
BROKER__USER=${RABBITMQ_DEFAULT_USER}
BROKER__PASSWORD=${RABBITMQ_DEFAULT_PASS}
# Grafana — интерфейс телеметрии (с lab6). Пароль администратора получает
# только сервис grafana (GF_SECURITY_ADMIN_PASSWORD); состояние Grafana —
# tmpfs, пароль из .env действует на каждом старте. Пустой make env_setup
# заменяет случайным
GRAFANA_ADMIN_PASSWORD=
# порт на 127.0.0.1 хоста, куда публикуется Grafana; порты Collector,
# Prometheus, Loki и Tempo не публикуются
GRAFANA_OUT_PORT=3000
# make test_isolated: порт на 127.0.0.1, куда публикуется тестовый
# контейнер API
TEST_APP_PORT=18088
+55
View File
@@ -78,6 +78,47 @@ services:
- source: haproxy_cfg
target: /usr/local/etc/haproxy/haproxy.cfg
# наблюдаемость (design change otel-telemetry, решение 20): те же сервисы,
# конфиги — configs; у хранилищ остаётся только именованный volume, у
# Grafana — tmpfs (не volumes) и ни одного порта на хосте
otel-collector:
volumes: !reset []
configs:
- source: otel_collector
target: /etc/otelcol-contrib/config.yaml
prometheus:
volumes: !override
- prometheus_data:/prometheus
configs:
- source: prometheus_yml
target: /etc/prometheus/prometheus.yml
loki:
volumes: !override
- loki_data:/loki
configs:
- source: loki_yaml
target: /etc/loki/loki.yaml
tempo:
volumes: !override
- tempo_data:/var/tempo
configs:
- source: tempo_yaml
target: /etc/tempo/tempo.yaml
grafana:
ports: !reset []
volumes: !reset []
configs:
- source: grafana_datasources
target: /etc/grafana/provisioning/datasources/datasources.yaml
- source: grafana_dashboards
target: /etc/grafana/provisioning/dashboards/dashboards.yaml
- source: grafana_dashboard_overview
target: /etc/grafana/dashboards/messenger-overview.json
# файлы по умолчанию 0444 и root: непривилегированные пользователи
# контейнеров читают, но не меняют — как read_only у bind mount
configs:
@@ -91,3 +132,17 @@ configs:
environment: CI_RABBITMQ_CONF
haproxy_cfg:
environment: CI_HAPROXY_CFG
otel_collector:
environment: CI_OTEL_COLLECTOR
prometheus_yml:
environment: CI_PROMETHEUS_YML
loki_yaml:
environment: CI_LOKI_YAML
tempo_yaml:
environment: CI_TEMPO_YAML
grafana_datasources:
environment: CI_GRAFANA_DATASOURCES
grafana_dashboards:
environment: CI_GRAFANA_DASHBOARDS
grafana_dashboard_overview:
environment: CI_GRAFANA_DASHBOARD_OVERVIEW
+10
View File
@@ -12,6 +12,16 @@ CI_S3_BOOTSTRAP="$(cat infra/s3/bootstrap.sh)$nl"
CI_HAPROXY_CFG="$(cat infra/haproxy/haproxy.cfg)$nl"
CI_RABBITMQ_CONF="$(cat infra/rabbitmq/rabbitmq.conf)$nl"
export CI_CONFIG_TOML CI_VALKEY_CONF CI_S3_BOOTSTRAP CI_HAPROXY_CFG CI_RABBITMQ_CONF
# наблюдаемость (design change otel-telemetry, решение 20)
CI_OTEL_COLLECTOR="$(cat infra/otel/collector.yaml)$nl"
CI_PROMETHEUS_YML="$(cat infra/otel/prometheus/prometheus.yml)$nl"
CI_LOKI_YAML="$(cat infra/otel/loki/loki.yaml)$nl"
CI_TEMPO_YAML="$(cat infra/otel/tempo/tempo.yaml)$nl"
CI_GRAFANA_DATASOURCES="$(cat infra/otel/grafana/datasources.yaml)$nl"
CI_GRAFANA_DASHBOARDS="$(cat infra/otel/grafana/dashboards.yaml)$nl"
CI_GRAFANA_DASHBOARD_OVERVIEW="$(cat infra/otel/grafana/dashboards/messenger-overview.json)$nl"
export CI_OTEL_COLLECTOR CI_PROMETHEUS_YML CI_LOKI_YAML CI_TEMPO_YAML \
CI_GRAFANA_DATASOURCES CI_GRAFANA_DASHBOARDS CI_GRAFANA_DASHBOARD_OVERVIEW
# готовность стенда через LB: /health/ready отвечает 200 от API_REPLICAS
# (из .env, по умолчанию 2) разных реплик — X-Instance-Id. Срок 60 с:
+40 -20
View File
@@ -11,7 +11,14 @@ SDK OpenTelemetry в API и worker, отдельный OTel Collector, хран
(логи), Tempo (трассы), интерфейс — Grafana (решения пользователя
2026-11-11). План изменений лабы и развилки — `PLAN.md`. Решения, принятые
без пользователя, и открытые вопросы —
`QUESTIONS.md`. Код перенесён из лабы 5 (репозиторий
`QUESTIONS.md`. Первое изменение лабы — change `otel-telemetry` (активный,
`openspec/changes/otel-telemetry/`, новая capability `observability`): SDK в
API и worker (секция `[telemetry]`, `src/infra/telemetry/`), Collector
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 (репозиторий
`mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit
`046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5
остались в её репозитории. Дальше — что досталось от лабы 5: брокер
@@ -96,13 +103,14 @@ 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 — в
`openspec/changes/archive/`, активных нет (новые capability: с `s3-storage` —
`openspec/changes/archive/`, активный — `otel-telemetry` (новые capability: с `s3-storage` —
`object-storage`, с `attachments` — `attachments`, с
`upload-consistency` — `storage-consistency`, с `async-attachments` —
`attachment-processing`, `message-broker`, с `pipeline-reliability` — `job-outbox`,
с `unit-of-work` — `unit-of-work`, с `track1-queue-overload` — `queue-overload`);
в `KNOWN_ISSUES.md` одиннадцать открытых записей (с переноса в лабу 6 — первый старт
RabbitMQ на пустом volume: `eacces` на `.erlang.cookie`, `make run_docker` падает; смесь версий при замене реплик на первый
в `KNOWN_ISSUES.md` одиннадцать открытых записей (запись о первом старте RabbitMQ на
пустом volume закрыта change `otel-telemetry`; с него же — 400 текстом uvicorn на
нестандартный метод HTTP; смесь версий при замене реплик на первый
релиз с обработкой; bootstrap после удаления
bucket; уборщик
удаляет объект зависшей загрузки по ключу вне своего префикса; 408 LB на медленные заголовки текстом HAProxy; поля `float` настроек принимают `inf`; 504 LB на метаданных и скачивании вложения при зависшем PostgreSQL; ложный FAIL `driver.py reconcile-cycle` на наполненном стенде; память S3 на долго живущем стенде; граница живой загрузки уборщика без закрытия соединения; остановка API при замороженном PostgreSQL дольше срока контейнера). Отчёт, evidence и рабочий план лабы 3 остались в её
@@ -343,13 +351,13 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `scripts/stop-one.example.sh` | образец failover hook; свой — `scripts/stop-one.sh`: остановить одну API-реплику по `TARGET_INSTANCE_ID` и оставить её остановленной |
| `compose.example.yaml` | список ролей с пустым `services`, не стенд; свой стенд — свой compose-файл |
| `infra/README.md` | куда класть конфигурации сервисов и что сопоставить в `REPORT.md` |
| `infra/otel/README.md` | с лабы 6: что положить — `collector.yaml` (receivers, processors, exporters, bind endpoints, memory limits / batch, поведение при backpressure), конфиги хранилищ, provisioning datasources и dashboards Grafana, dashboard JSON; на 4 — alert rules и runbooks; OTLP, metrics и административные порты наружу не публиковать |
| `infra/otel/README.md` | с лабы 6: что положить — `collector.yaml` (receivers, processors, exporters, bind endpoints, memory limits / batch, поведение при backpressure), конфиги хранилищ, provisioning datasources и dashboards Grafana, dashboard JSON; на 4 — alert rules и runbooks; OTLP, metrics и административные порты наружу не публиковать; сделано — `infra/otel/` (change `otel-telemetry`, карта кода), правило `telemetry.md` |
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает; сборку, стенд и `make test` — свой job `workflows/application.yml` (карта кода) |
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, lab5 `BROKER_URL_FILE` и др.) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`); имена lab6 `OTEL_*` сопоставляет первый change лабы (`PLAN.md`) |
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, lab5 `BROKER_URL_FILE` и др.) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`); имена lab6 `OTEL_*` настройками не являются — их соответствие `[telemetry]` и константам кода в шапке шаблона и в `REPORT.md`; `GRAFANA_ADMIN_PASSWORD` (случайный от `make env_setup`) и `GRAFANA_OUT_PORT` |
| `examples/requests.http` | ручные запросы для HTTP-клиента IDE |
## Где лежат инструкции
@@ -382,6 +390,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `worker.md` | `src/worker/**`, `src/relay/**`, `src/infra/render/**`, `src/core/services/attachment_processing.py`, `attachment_relay.py`, `attachment_replay.py`, `src/utils/image_variants.py`: worker, relay, процесс обработки, claim и fencing, аренда, бюджет, лимиты, варианты, replay |
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
| `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций |
| `telemetry.md` | `src/infra/telemetry/**`, `infra/otel/**` (с лабы 6): SDK только из `[telemetry]` и без `OTEL_*`, правило корня, запреты атрибутов, журнал через хуки, закрытие со сроком, конфигурации Collector, хранилищ и Grafana файлами для CI, сети и healthcheck |
- **`openspec/`** (схема `spec-driven`, язык артефактов — русский, см.
`openspec/config.yaml`): что система делает и зачем.
@@ -471,7 +480,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `make run_dev` | `make upgrade` (Postgres из compose и миграции), `make start_cache` и `make start_s3`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload |
| `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` |
| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и шестью секретами S3, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает, но в существующий `.env` дописывает переменные шаблона, которых в нём нет (секреты — случайными, прежние строки не меняются); печатает только имена |
| `make run_docker` | `make env_setup` (недостающие файлы и переменные) + `docker compose build` + `up -d`: postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2) и cleaner → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf`, `infra/haproxy/haproxy.cfg` и `infra/s3/bootstrap.sh` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` |
| `make run_docker` | `make env_setup` (недостающие файлы и переменные) + `docker compose build` + `up -d`: postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2) и cleaner → haproxy на `127.0.0.1:APP_OUT_PORT`; рядом, без зависимостей приложения от них, — otel-collector, prometheus, loki, tempo и grafana на `127.0.0.1:GRAFANA_OUT_PORT` (пароль `admin` — `GRAFANA_ADMIN_PASSWORD` из `.env`); на пустых volumes — с первой попытки; `config.toml`, `infra/valkey/valkey.conf`, `infra/haproxy/haproxy.cfg` и `infra/s3/bootstrap.sh` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` |
| `make stop` / `make down` | остановить / удалить контейнеры compose; volumes с данными остаются; S3 останавливается плавно ~15 с |
| `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` |
| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) |
@@ -503,6 +512,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `driver.py --port <LB> pipeline-state` | только чтение, JSON: задания по состояниям, due, ждущие срока, опубликованные и не взятые, истёкшие аренды, возраст старейшего, очередь |
| `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 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` |
| `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст |
@@ -510,7 +522,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `make s3_check` | приватность bucket вне API на запущенном стенде (`driver.py s3-check`): bootstrap в режиме `check` (права ключей API и уборщика, чужой временный bucket, административные запросы), анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети, затем `cleanup`; таблица «где → проверка → ожидаемо → получено», код 1 при нарушении |
| `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) |
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
| `make wipe_data` | `down -v` — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода `yes` |
| `make wipe_data` | `down -v` — удалить данные стенда (volumes Postgres, S3, брокера и хранилищ телеметрии называются в запросе) и кэш; только после ввода `yes` |
| `make service_test` | быстрые тесты сервисов на фейках (`service-tests/unit`): ветки всех сервисов, архитектура (импорты, сигнатуры порт — реализация — фейк), контракт repo на фейке; без PostgreSQL, Valkey, S3, брокера, docker и сети, секунды (`service-tests.md`) |
| `make service_test_db` | `start_db` и `service-tests/db` на временной базе `test_uow_<db>`: настоящая единица работы, тот же контракт repo на SQL, соединение на шаг и общий срок JSON-запроса в процессе (S3 и кэш — фейки), замороженный сервер — TCP-прокси; база удаляется при любом исходе, имя не по шаблону — код 2 |
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_<db>/` (`student-tests.md`) |
@@ -550,7 +562,7 @@ 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
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/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
@@ -563,7 +575,7 @@ src/
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, пагинация
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-лог
middlewares/ # X-Request-Id, X-Instance-Id и access-лог; с лабы 6 — server span и histogram http.server.request.duration (не для health), итоговая запись внутри span
core/
ports/uow.py # AbstractUnitOfWork: блок, commit, rollback, blocks_opened, правила вложенного входа и repo вне блока, UnitOfWorkError; реальные шаги — _open, _close, _commit, _rollback реализации; Repositories
ports/<domain>.py # Abstract<Domain>Repository: абстрактные методы, докстринг — контракт (None, False, условие перехода); импорты — только DTO, enum, src.utils
@@ -586,25 +598,26 @@ src/
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 429 предела заданий (UploadBacklogFull), 500 пропавшего объекта
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 в каждой записи
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, провайдеры, хуки
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
render/client.py # ImageRenderer: процесс обработки на задание, окружение без секретов, срок и kill в finally, разбор вывода, коды в ImageRejected / RenderInterrupted
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/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 на блок; импортируют только точки входа
db/uow.py # SqlAlchemyUnitOfWork(factory, timeout_seconds) поверх session_scope, repo на блок; импортируют только точки входа; span COMMIT в _commit
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада)
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск; span GET / SET без ключа с messenger.cache.result
cache/instance.py # глобал cache процесса API
s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost)
s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost); span S3.<Операция> в _call без ключа (нет объекта у HEAD и DELETE — исход missing, не ошибка)
s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan
schemas/
jobs/attachment.py # AttachmentJobMessage (pydantic по contracts/jobs.schema.json) и build_job_body
dataclasses/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head)
enums/<domain>.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head), JobDeliveryOutcome (исход доставки worker → JobOutcome)
utils/
image_variants.py # render_variants: thumbnail, crop, optimized из одного декодирования, fit_size вниз своим расчётом, EXIF orientation, alpha на белый у JPEG, InvalidImage; импортирует Pillow, поэтому только src/worker/render.py
constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3
@@ -633,8 +646,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 (одновременные доставки); conftest подставляет поля settings
db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow
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 под родителем, без родителя — ни одного)
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
@@ -659,6 +672,11 @@ migrations/, alembic.ini # ревизии alembic, async env.py; приме
infra/ # конфигурации сервисов стенда; README.md — skeleton
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
rabbitmq/rabbitmq.conf # предел памяти брокера 400 МиБ: лимит контейнера он не видит
otel/collector.yaml # Collector contrib (change otel-telemetry): OTLP HTTP :4318, memory_limiter и batch, экспортёры prometheus :8889, otlp_http/loki, otlp_http/tempo, свои метрики :8888
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)
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 при замене)
@@ -666,7 +684,7 @@ scripts/restart.sh # restart hook для make test-persistence, по r
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain (до 90 с: дольше загрузки) → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck, MALLOC_MMAP_THRESHOLD_ (буфер загрузки растёт без копии)
docker-compose.yml # проект mtusi-lab6: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), rabbitmq, migrate, s3-bootstrap, relay и worker (пароль брокера только у них и rabbitmq), api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env)
docker-compose.yml # проект mtusi-lab6: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), rabbitmq, migrate, s3-bootstrap, relay и worker (пароль брокера только у них и rabbitmq), api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; с лабы 6 — otel-collector (сети default и telemetry), prometheus, loki, tempo, grafana (сеть telemetry, наружу — только Grafana на 127.0.0.1:GRAFANA_OUT_PORT), x-telemetry-env у api и worker, healthcheck брокера через gosu rabbitmq; адреса и порты из .env, volumes postgres_data, s3_data, rabbitmq_data, prometheus_data, loki_data, tempo_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env)
.dockerignore
config_example.toml, .env.example
evidence/broker/ # change async-attachments: stand.md (driver.py broker-check), isolated.md (очередь временной базы)
@@ -675,6 +693,8 @@ 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/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 с ревизией до и после)
evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде текущей лабы: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
@@ -696,7 +716,7 @@ evidence/bench/unit-of-work-*/ # change unit-of-work, профиль quick с и
evidence/rollout/unit-of-work*/ # change unit-of-work: unit-of-work (замена с Profile.rollout_from), unit-of-work-previous (--from b2fb88f: CPU на запрос старых и новых реплик)
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md; unit-of-work-before__unit-of-work-after.md и unit-of-work-aa__unit-of-work-after.md — цена шага от двух меток одного кода
.github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона (адрес Gitea литералом: github.server_url — внутренний http://gitea:3000, из job не резолвится; по той же причине contracts.yml на этом раннере падает на actions/checkout), сборка и стенд под проектом mtusi-lab6-safronov-ci-<run_id>, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make validate, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона; у Prometheus, Loki и Tempo — только именованный volume, у Collector и Grafana — ни одного (tmpfs Grafana остаётся)
.github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
+15 -18
View File
@@ -182,25 +182,22 @@
22 с и больше, отдельным change; там же поправить «17 с» в спеках. Правка меняет код уборщика и стенд
отказов, в `track1-queue-overload` не входит.
## Первый старт RabbitMQ на пустом volume: `eacces` на `.erlang.cookie`, `make run_docker` падает
## Нестандартный метод HTTP: 400 текстом uvicorn, мимо приложения
- **Где:** `docker-compose.yml`, сервис `rabbitmq`: healthcheck `rabbitmq-diagnostics -q
check_port_connectivity` с `start_interval: 1s`, образ `rabbitmq:4.3.7`. Найдено при переносе
в лабу 6 (2026-11-11), первый `make run_docker` на новом проекте `mtusi-lab6`.
- **Что:** healthcheck идёт от root с `HOME=/var/lib/rabbitmq`. На пустом volume первая проверка
(~1 с после старта) создаёт `.erlang.cookie` от root с правами 0400 раньше сервера, а сервер
работает от `rabbitmq` (uid 999): «Error when reading /var/lib/rabbitmq/.erlang.cookie: eacces»,
процесс падает, `restart: unless-stopped` поднимает его (`RestartCount` 1), entrypoint при
рестарте меняет владельца — дальше брокер `healthy`. Но `up -d` к этому моменту уже вернул
«dependency failed to start: container mtusi-lab6-rabbitmq-1 is unhealthy»: `worker` и `haproxy`
остались `Created`, код цели 1. Владелец файла после рестарта — `rabbitmq:root`, группа от root
осталась. На volume лабы 5 не проявлялось: cookie там создал сервер давно.
- **Чем грозит:** стенд из чистого clone не поднимается одной командой (шаг 1 сценария защиты лабы
6, CI на новом прогоне). Повторный `docker compose up -d --wait` доводит стенд, данные не страдают.
- **Предложение:** проверку — от пользователя брокера: `gosu rabbitmq rabbitmq-diagnostics -q
check_port_connectivity` (`gosu` в образе есть, `/usr/sbin/gosu`), проверить на пустом volume
несколько раз подряд и в CI; сценарий в требовании «Свой проект compose у лабы» или в спеке
`message-broker` («Стенд с нуля одной командой»).
- **Где:** HTTP-парсер uvicorn (httptools, выбирается автоматически), `src/main.py`
(`uvicorn.run` без `http=`). Найдено apply change `otel-telemetry` (`driver.py
telemetry-check`, сценарий `observability` «Необычный метод и неизвестный путь»).
- **Что:** запрос с методом, которого нет в списке llhttp (`BREW`), отклоняется парсером до
ASGI-приложения: `400 Bad Request`, `content-type: text/plain`, тело «Invalid HTTP request
received.», без `X-Request-Id`, `X-Instance-Id` и тела ошибки контракта; ни итоговой записи, ни
span, ни метрики. Метод из списка llhttp, но вне стандартного набора (`PROPFIND`, `PURGE`)
доходит до приложения: 404 в формате контракта и ряд `_OTHER`. HAProxy такой запрос передаёт.
- **Чем грозит:** ответ API не в формате контракта на экзотический метод; сценарий спека с
методом `BREW` по HTTP не воспроизводится — `telemetry-check` проверяет `_OTHER` на `PROPFIND`, а
у `BREW` — только отсутствие метода и UUID в метках.
- **Предложение:** `uvicorn.run(..., http="h11")` (h11 принимает любой токен метода) — после
замера цены на трек 1, — или правило HAProxy, отвечающее 400 в формате контракта на методы вне
списка; затем поправить сценарий спека. Отдельный change.
## Остановка API при замороженном PostgreSQL дольше срока контейнера
+5 -3
View File
@@ -68,7 +68,7 @@ replay:
# нет (секреты — случайными, остальные — значениями шаблона), прежние
# строки не меняются (design change upload-consistency). Печатаются
# только имена, значения — нет
ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY
ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY GRAFANA_ADMIN_PASSWORD
# шаблон с подставленными секретами — в поток, не в вывод команды
ENV_FILLED = sed \
-e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \
@@ -83,6 +83,7 @@ ENV_FILLED = sed \
-e "s/^S3_WORKER_ACCESS_KEY=$$/S3_WORKER_ACCESS_KEY=$$(openssl rand -hex 10)/" \
-e "s/^S3_WORKER_SECRET_KEY=$$/S3_WORKER_SECRET_KEY=$$(openssl rand -hex 20)/" \
-e "s/^RABBITMQ_DEFAULT_PASS=$$/RABBITMQ_DEFAULT_PASS=$$(openssl rand -hex 16)/" \
-e "s/^GRAFANA_ADMIN_PASSWORD=$$/GRAFANA_ADMIN_PASSWORD=$$(openssl rand -hex 16)/" \
.env.example
# строки NAME=… шаблона, имени которых в .env нет, — в конец .env под
# комментарием; в вывод — только имена
@@ -125,7 +126,8 @@ EXPECT_REPLICAS ?= $(API_REPLICAS)
DC=docker compose
# стенд: postgres, valkey, s3, rabbitmq -> migrate, s3-bootstrap -> api ×
# API_REPLICAS, cleaner, worker -> haproxy
# API_REPLICAS, cleaner, worker -> haproxy; телеметрия — otel-collector,
# prometheus, loki, tempo, grafana (приложение их не ждёт)
# (единственный порт API на хосте — у haproxy). env_setup создаёт
# недостающие .env и config.toml из шаблонов: без config.toml compose не
# запустится (bind с create_host_path: false), без паролей — тоже.
@@ -182,7 +184,7 @@ revision: upgrade
wipe_data:
@project=$$($(DC) config | sed -n 's/^name: //p'); \
volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \
read -p "Удалить все данные стенда (volumes Postgres, S3 и брокера: $$volumes)? Введите yes: " answer; \
read -p "Удалить все данные стенда (volumes Postgres, S3, брокера и хранилищ телеметрии: $$volumes)? Введите yes: " answer; \
if [ "$$answer" = "yes" ]; then \
$(DC) down -v --remove-orphans; \
else \
+16
View File
@@ -124,6 +124,17 @@ Change `openspec/changes/otel-telemetry/`, propose 2026-11-11. Номера —
- Консоль, `make test_isolated`, стенд отказов и `bench/` — без телеметрии (20).
- Проверка «стенд с нуля» — команда драйвера со своим проектом compose, которая сама удаляет свои volumes:
`make wipe_data` и `down -v` агенту запрещены (21).
- Apply (2026-11-11), подробности — design, «Уточнения apply»:
- `BREW` не доходит до приложения (парсер uvicorn, 400 текстом): `_OTHER` проверен на `PROPFIND`, дефект — в
`KNOWN_ISSUES.md` (п. 2);
- атрибуты сверх решения 12: `stored` у `SET` Valkey, `messenger.s3.result`, `error.type` = код у 5xx без исключения,
атрибуты процесса обработки (п. 3);
- закрытие SDK — по потоку на провайдер (п. 4); подтверждение доставки — внутри места конкуренции (п. 5);
- Grafana: выключены 15 встроенных источников, кроме prometheus, loki, tempo; сверх решения — получение ключей
плагинов, внешние снимки, ссылки обратной связи, gravatar (п. 6);
- `level=error` Loki «empty ring» на старте и Tempo «no jobs found» в простое — шум, не отказ (п. 7);
- `stand-from-scratch` останавливает рабочий стенд на время проверки (`make stop` / `docker compose start`) (п. 10);
- лимиты решения 7 подтверждены замером, не менялись (п. 11).
### Вопросы
@@ -141,3 +152,8 @@ Change `openspec/changes/otel-telemetry/`, propose 2026-11-11. Номера —
5. Пользователю: метки последнего шага (`make bench_uploads`, `make bench_queue`) по методике `bench/` снимаются с
выключенным SDK: «код лабы 6 с телеметрией» — код есть, телеметрия выключена. Если нужны метки с включённой телеметрией —
это профиль трека 1 (change `track1-telemetry-cost`) и другая методика.
6. Преподавателю (apply): сценарий `observability` «Необычный метод и неизвестный путь» назван методом `BREW`, а его
uvicorn отклоняет до приложения (400 не в формате контракта, `KNOWN_ISSUES.md`). Достаточно ли `_OTHER` на методе,
который доходит до приложения (`PROPFIND`)? Иначе — `http="h11"` у uvicorn или правило HAProxy (отдельный change).
7. Пользователю (apply): перед замерами для отчёта переснять `telemetry-check`, `telemetry-outage`,
`stand-from-scratch` и бюджет на закоммиченном коде — evidence сняты на незакоммиченном дереве поверх `9b35c25`.
+115
View File
@@ -13,12 +13,127 @@ TODO: версии runtime/образов, prerequisites, команды соз
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
## Наблюдаемость
Change `otel-telemetry` (design — `openspec/changes/otel-telemetry/design.md`, номера решений
в скобках). Числа и проверки сняты на рабочем дереве поверх `9b35c25` до коммита change
(шапки файлов `evidence/telemetry/`, `evidence/stand/`).
### Назначение компонентов
| Компонент | Версия (тег, digest индекса — `docker-compose.yml`) | На какой вопрос об инциденте отвечает |
| --- | --- | --- |
| SDK OpenTelemetry Python (`opentelemetry-api`, `-sdk`, `-exporter-otlp-proto-http`) | 1.45.2 (`>=1.45.2,<1.46`), semantic conventions 0.66b2 | производит три сигнала в API и worker; экспорт OTLP/HTTP protobuf в фоне, очереди ограничены |
| OTel Collector, дистрибутив **contrib** | 0.164.0 | получатель и маршрутизатор, а не хранилище: `memory_limiter`, `batch`, три pipeline до трёх хранилищ; contrib — ради `tail_sampling` трека 1 (1) |
| Prometheus | v3.15.1 | **метрика**: «сколько и как быстро» — RPS, доля ошибок, квантили длительности, исходы заданий по времени; scrape экспортёра Collector (3) |
| Loki | 3.7.9 | **лог**: «что именно произошло в этом запросе / задании» — те же записи, что в stdout, поиск по `request_id`, `attachment_id`, `trace_id` |
| Tempo | 3.1.1 | **трасса**: «где ушло время и что упало» — server / consumer span с дочерними PostgreSQL, Valkey, S3 и процессом обработки |
| Grafana | 13.3.1 | интерфейс без своего состояния: источники и dashboard из git, переход лог ↔ трасса (16) |
### Сигналы уровня 3
| Логический сигнал контракта | Инструмент SDK | Prometheus / Loki / Tempo | Единица |
| --- | --- | --- | --- |
| HTTP requests | счёт наблюдений histogram `http.server.request.duration` | `http_server_request_duration_seconds_count{job="messenger-api", http_request_method, http_route, http_response_status_code}` | запросы |
| HTTP duration | histogram `http.server.request.duration`, границы 0,005…30 с (10) | `http_server_request_duration_seconds_bucket` / `_sum` | с |
| jobs (успешные / ошибочные) | счёт наблюдений histogram `messenger.job.duration` | `messenger_job_duration_seconds_count{job="messenger-worker", messenger_job_type, messenger_job_outcome}` | задания |
| job duration | histogram `messenger.job.duration`, границы 0,05…60 с (11) | `messenger_job_duration_seconds_bucket` / `_sum` | с |
| логи с `trace_id` / `span_id` | логгер SDK из процессора structlog (2) | Loki: поток `service_name`, `service_instance_id`, `deployment_environment_name`; поля записи, `trace_id`, `span_id` — structured metadata; строка — `event` | запись |
| трассы API | span `SERVER` `«метод» «шаблон»` (корень), дочерние `SELECT`/`INSERT`/…, `COMMIT`, `GET`/`SET` Valkey, `S3.<Операция>` | Tempo: `messenger.request_id`, `http.*`, `db.*`, `rpc.*`, `error.type` | span |
| трассы worker | span `CONSUMER` `process <очередь>` (корень), дочерние PostgreSQL, S3, `render attachment variants` | Tempo: `messaging.*`, `messenger.job.type`, `messenger.job.outcome` | span |
Запросы панелей dashboard (`infra/otel/grafana/dashboards/messenger-overview.json`, uid
`messenger-overview`, папка Messenger):
- RPS по маршруту и классу статуса: `sum by (http_route, status_class)
(label_replace(rate(http_server_request_duration_seconds_count{job="messenger-api"}[5m]),
"status_class", "${1}xx", "http_response_status_code", "([0-9])..")))`;
- **доля ошибок HTTP** — числитель 5xx API, знаменатель — все учтённые запросы (health не
учитывается, 4xx — отдельная панель того же вида):
`sum(rate(http_server_request_duration_seconds_count{job="messenger-api",http_response_status_code=~"5.."}[5m]))
/ sum(rate(http_server_request_duration_seconds_count{job="messenger-api"}[5m]))`;
- p50 и p95: `histogram_quantile(q, sum by (le) (rate(http_server_request_duration_seconds_bucket{job="messenger-api"}[5m])))`
— из суммы buckets всех реплик, а не средние; p95 по маршрутам — `sum by (le, http_route)`;
- задания по исходу: `sum by (messenger_job_outcome) (rate(messenger_job_duration_seconds_count{job="messenger-worker"}[5m]))`;
**успешные** — `ready`, **ошибочные** — `failed`, `retry`, `requeued`, `dropped`, `error`,
`skipped` — ни то, ни другое (подтверждено без попытки);
- p50 и p95 длительности `ready`: `histogram_quantile(q, sum by (le) (rate(messenger_job_duration_seconds_bucket{job="messenger-worker",messenger_job_outcome="ready"}[5m])))`;
- журналы `{service_name=~"messenger-.*"}` (Loki), поиск трасс `{ resource.service.name =~ "messenger-.*" }` (Tempo).
### Ресурс и имена `OTEL_*`
| Атрибут ресурса | Значение | Prometheus | Loki |
| --- | --- | --- | --- |
| `service.name` | `messenger-api` / `messenger-worker` (константы точки входа) | `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_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).
### Инфраструктура наблюдаемости
| Роль `infrastructure.json` | Сервис | Версия | Healthcheck | Volume | Порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| `otel_collector` | `otel-collector` | contrib 0.164.0 | нет (в образе нет оболочки): цель `otel-collector` в Prometheus | — | OTLP `:4318`, метрики `:8888`, `:8889` — только в сетях стенда | нет |
| `telemetry_storage` (метрики) | `prometheus` | v3.15.1 | `wget /-/ready` | `prometheus_data`, срок 7d, предел 1GB | `:9090` — только сеть `telemetry` | нет |
| `telemetry_storage` (логи) | `loki` | 3.7.9 | нет: цель `loki` и проверка источника | `loki_data`, срок 168h | `:3100` — только сеть `telemetry` | нет |
| `telemetry_storage` (трассы) | `tempo` | 3.1.1 | нет: цель `tempo` и проверка источника | `tempo_data`, срок 168h | `:3200`, OTLP `:4318` — только сеть `telemetry` | нет |
| `grafana` | `grafana` | 13.3.1 | `wget /api/health` | tmpfs (provisioning из git) | `127.0.0.1:${GRAFANA_OUT_PORT:-3000}` | `admin` / `GRAFANA_ADMIN_PASSWORD` из `.env` (случайный от `make env_setup`), только у Grafana |
Сети: хранилища и Grafana — `telemetry`, Collector — `default` и `telemetry`; из контейнеров
API и worker имена `prometheus`, `loki`, `tempo`, `grafana` не разрешаются (17). Приложение от
сервисов телеметрии не зависит: без них стартует и работает (`evidence/telemetry/collector-outage.md`).
### Бюджет
Лимиты телеметрии: Collector 0,5 CPU / 256 МиБ, Prometheus 0,5 / 384, Loki 0,5 / 512, Tempo
0,5 / 512, Grafana 0,5 / 384 — 2,5 CPU / 2048 МиБ. Постоянные лимиты стенда — 11,5 CPU /
7040 МиБ, с одноразовыми — 12,5 CPU / 7424 МиБ при ВМ 12 CPU / 7934 МиБ: лимиты — потолки, а не
резерв. Замер (`evidence/telemetry/budget.md`): пики `memory.peak` — Collector 72, Prometheus 76,
Loki 117, Tempo 235, Grafana 249 МиБ, каждый лимит не меньше 1,5 × пика; реплика API под `make
test` + `make load` — 230 МиБ с телеметрией и 216 без неё (лимит 512); простой всего стенда —
1715 МиБ, из них телеметрия — 770. Грубая цена SDK (один прогон `make load`): 437 против 499
запросов/с, p95 15,8 против 10,4 мс — исследование трека 1.
### Ограничения наблюдаемости
- **Отказ Collector:** что не ушло, теряется: очереди SDK ограничены (2048 span и записей), при
остановке процесса закрытие ждёт не дольше 1 с (API) и 0,5 с (worker). Cumulative-метрики SDK
копит в себе: после возврата Collector счётчики не теряются, теряется разрешение; рестарт
Collector сбрасывает ряды экспортёра (`rate()` это переносит). Записи об отказе отправки — только
stdout, не чаще одной в минуту на модуль SDK (`evidence/telemetry/collector-outage.md`).
- **Ответы балансировщика** (502, 503, 504, 408 HAProxy) в метрики API не попадают: их генерирует
LB, метрик HAProxy на уровне 3 нет. Нестандартный метод вне списка парсера uvicorn (`BREW`)
отклоняется до приложения 400 текстом — ни span, ни ряда (`KNOWN_ISSUES.md`).
- **OTLP без аутентификации и TLS** — до лабы 7: Collector принимает от любого контейнера сети
`default`; хранилища отделены сетью.
- Trace-id клиента не продолжается (публичная точка входа); перенос контекста через брокер, relay
с SDK, метрики пула, очереди и насыщения — следующие changes уровня 4.
- `service.version` не различает сборки одной версии контракта.
- Tempo 3.1 в простое пишет `level=error` «no jobs found» (backend-worker опрашивает
scheduler без заданий) — шум журнала, не отказ.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Уровень 3: Collector, хранилища, provisioning, свой запрос и задание найдены, приватность | `driver.py --port 8080 telemetry-check` | код 0: Loki → Tempo по `X-Request-Id`, трасса worker, рост счётчиков, история после рестарта хранилищ | `evidence/telemetry/check.md` |
| Телеметрия не меняет ответы и остановку | `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 |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
+7
View File
@@ -118,6 +118,10 @@ services:
image: mtusi-messenger:bench
restart: "no"
volumes: !reset []
environment:
# телеметрия выключена: методика и бюджеты стенда прежние (design change
# otel-telemetry, решение 20); сервисы телеметрии стенд не запускает
TELEMETRY__ENABLED: "false"
deploy:
resources:
limits:
@@ -144,6 +148,9 @@ services:
# размер 500k с наполнением идёт ~25 мин; на медленном хосте срок
# 3600 с по умолчанию мог бы истечь посреди прогона и дать 401
AUTH__SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL_SECONDS:?run make bench}
# телеметрия выключена, как у worker (design change otel-telemetry,
# решение 20): вариант трека 1 с телеметрией включает её явно
TELEMETRY__ENABLED: "false"
deploy:
replicas: ${BENCH_API_REPLICAS:?run make bench}
resources:
+5 -1
View File
@@ -1751,7 +1751,10 @@ def compose_env(profile: Profile) -> dict[str, str]:
`cleaner` описан, но профили его не запускают. С брокером, relay и worker
(design change `async-attachments`, решение 16; `pipeline-reliability`,
решение 16) — пароль брокера и ключи пользователя worker: bootstrap S3
заводит его и в профилях с S3. Реплики пароля брокера не получают.
заводит его и в профилях с S3. Реплики пароля брокера не получают. С
телеметрией (design change `otel-telemetry`, решение 20) — пароль
администратора Grafana: сервисы телеметрии описаны, но ни один профиль их
не запускает, а реплики и worker стенда — с выключенной телеметрией.
"""
env = {key: os.environ[key] for key in HOST_ENV if key in os.environ}
return {
@@ -1769,6 +1772,7 @@ def compose_env(profile: Profile) -> dict[str, str]:
"S3_WORKER_ACCESS_KEY": secrets.token_hex(10),
"S3_WORKER_SECRET_KEY": secrets.token_hex(20),
"RABBITMQ_DEFAULT_PASS": secrets.token_urlsafe(24),
"GRAFANA_ADMIN_PASSWORD": secrets.token_hex(16),
"BENCH_APP_CPUS": profile.cpus,
"BENCH_APP_MEMORY": profile.memory,
"BENCH_DB_CPUS": profile.db_cpus,
+18
View File
@@ -184,3 +184,21 @@ max_published_backlog = 1000
republish_after_seconds = 300
# секунды паузы после отказа брокера или PostgreSQL
failure_pause_seconds = 2
[telemetry]
# Телеметрия API и worker (OpenTelemetry SDK → Collector). Включение и адрес
# Collector здесь не задаются: файл монтируется и в консольный запуск, а
# телеметрию включает compose у api и worker (TELEMETRY__ENABLED,
# TELEMETRY__OTLP_ENDPOINT). Переменные OTEL_* настройками не являются.
# deployment.environment.name ресурса
environment = "lab"
# секунды между отправками метрик
metric_export_interval_seconds = 15
# секунды на одну отправку пакета
export_timeout_seconds = 2
# span и записей журнала в очереди SDK; сверх — теряются
max_queue_size = 2048
# span и записей в одной отправке; не больше очереди
max_export_batch_size = 512
# секунды паузы между пакетами
schedule_delay_seconds = 1
+210 -5
View File
@@ -1,8 +1,9 @@
# Стенд лабы 6: HAProxy — единственная точка входа, за ним API ×
# API_REPLICAS; PostgreSQL, Valkey (кэш), S3 (SeaweedFS, байты вложений),
# RabbitMQ (задания обработки), одноразовые миграции и bootstrap S3, уборщик
# незавершённых загрузок, relay публикации заданий, worker обработки вложений.
# Правила — .claude/rules/docker.md и balancer.md. Значения — из .env
# незавершённых загрузок, relay публикации заданий, worker обработки вложений;
# с лабы 6 — OTel Collector, Prometheus, Loki, Tempo и Grafana (сеть
# telemetry). Правила — .claude/rules/docker.md, balancer.md и telemetry.md. Значения — из .env
# (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и
# у режима docker. Имя проекта меняется в каждой лабе: от него зависят
# имена volumes, и стенд не должен подключаться к данным прошлой лабы.
@@ -50,6 +51,13 @@ x-broker-env: &broker-env
BROKER__USER: ${RABBITMQ_DEFAULT_USER:?RABBITMQ_DEFAULT_USER is not set, run make env_setup}
BROKER__PASSWORD: ${RABBITMQ_DEFAULT_PASS:?RABBITMQ_DEFAULT_PASS is empty, run make env_setup}
# телеметрия — api и worker (design change otel-telemetry, решение 8): SDK
# включён и шлёт OTLP/HTTP только в Collector по имени сервиса в сети compose.
# Адрес не секрет; переменные OTEL_* настройками не являются
x-telemetry-env: &telemetry-env
TELEMETRY__ENABLED: "true"
TELEMETRY__OTLP_ENDPOINT: http://otel-collector:4318
# образ сервера S3 и bootstrap: тег с версией и digest индекса (amd64 и
# arm64)
x-s3-image: &s3-image chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d
@@ -261,7 +269,10 @@ services:
aliases:
- ${RABBITMQ_HOST:-rabbitmq}
healthcheck:
test: ["CMD-SHELL", "rabbitmq-diagnostics -q check_port_connectivity"]
# от пользователя брокера, exec-формой: CLI от root на пустом volume
# создавал .erlang.cookie (0400, root) раньше сервера, и тот падал на
# eacces (design change otel-telemetry, решение 19)
test: ["CMD", "gosu", "rabbitmq", "rabbitmq-diagnostics", "-q", "check_port_connectivity"]
interval: 10s
timeout: 5s
retries: 10
@@ -358,7 +369,7 @@ services:
image: mtusi-messenger:lab6
restart: unless-stopped
environment:
<<: [*db-env, *cache-env, *s3-env, *s3-api-keys-env]
<<: [*db-env, *cache-env, *s3-env, *s3-api-keys-env, *telemetry-env]
APP__PORT: ${APP__PORT:-8080}
volumes:
- *config-toml
@@ -482,7 +493,7 @@ services:
entrypoint: ["python", "-m", "src.worker"]
restart: unless-stopped
environment:
<<: [*db-env, *s3-env, *broker-env]
<<: [*db-env, *s3-env, *broker-env, *telemetry-env]
# шаги с БД короткие: соединение на задание
DATABASE__POOL_SIZE: "2"
# пользователь worker: чтение и запись объектов, без удаления и
@@ -554,7 +565,201 @@ services:
cpus: "1.0"
memory: 256M
# --- наблюдаемость (design change otel-telemetry, решения 1, 7, 14–18) ---
# Сервисы приложения их не ждут, а они — друг друга: без них приложение
# работает, отправку и запросы они повторяют сами. Порты наружу — только
# у Grafana. Сервисы на Go получают GOMEMLIMIT ~80 % лимита: лимит cgroup
# рантайм не видит
# OTel Collector contrib: OTLP/HTTP от api и worker (сеть default), метрики
# для scrape и экспорт в Loki и Tempo (сеть telemetry). Секретов нет. В
# образе нет ни оболочки, ни HTTP-клиента: healthcheck нет, живость — цель
# otel-collector в Prometheus
otel-collector:
image: otel/opentelemetry-collector-contrib:0.164.0@sha256:340c9ca6a36617084c6661bdc4f0fe92b7cda5a805d61673ec8db375fddc522b
restart: unless-stopped
command: ["--config=/etc/otelcol-contrib/config.yaml"]
environment:
GOMEMLIMIT: 160MiB
volumes:
- type: bind
source: ./infra/otel/collector.yaml
target: /etc/otelcol-contrib/config.yaml
read_only: true
bind:
create_host_path: false
networks:
- default
- telemetry
deploy:
resources:
limits:
# memory_limiter 200 / 40 МиБ в collector.yaml
cpus: "0.5"
memory: 256M
# Prometheus — метрики: scrape Collector и собственных метрик конвейера;
# срок и предел объёма хранения — флаги. Без remote write, OTLP, admin API и
# lifecycle
prometheus:
image: prom/prometheus:v3.15.1@sha256:fa3302279710be2f21a8301ec17a8b4f2301fd829bd113839b3b6b02b6f191a2
restart: unless-stopped
command:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
- --storage.tsdb.retention.time=7d
- --storage.tsdb.retention.size=1GB
environment:
GOMEMLIMIT: 300MiB
volumes:
# volume образа (Config.Volumes), владелец nobody
- prometheus_data:/prometheus
- type: bind
source: ./infra/otel/prometheus/prometheus.yml
target: /etc/prometheus/prometheus.yml
read_only: true
bind:
create_host_path: false
networks:
- telemetry
healthcheck:
# busybox wget есть в образе
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:9090/-/ready"]
interval: 10s
timeout: 3s
retries: 5
start_period: 30s
start_interval: 1s
deploy:
resources:
limits:
cpus: "0.5"
memory: 384M
# Loki — логи: родной OTLP от Collector, filesystem в volume, срок 7 суток.
# Оболочки и HTTP-клиента в образе нет: healthcheck нет, живость — цель loki
# в Prometheus и проверка источника в Grafana
loki:
image: grafana/loki:3.7.9@sha256:0db216b630ae1f348a1584c67f3cead8b4c1fc839169a39501db664744158e28
restart: unless-stopped
command: ["-config.file=/etc/loki/loki.yaml"]
environment:
GOMEMLIMIT: 400MiB
volumes:
- loki_data:/loki
- type: bind
source: ./infra/otel/loki/loki.yaml
target: /etc/loki/loki.yaml
read_only: true
bind:
create_host_path: false
networks:
- telemetry
deploy:
resources:
limits:
cpus: "0.5"
memory: 512M
# Tempo — трассы: монолит 3.1 с локальным хранилищем, срок 7 суток. Как у
# Loki, healthcheck нет
tempo:
image: grafana/tempo:3.1.1@sha256:64e2fbd56d9c2b3412a4b430a58ea59e91a670b1e75f920a0c702213ad145044
restart: unless-stopped
command: ["-config.file=/etc/tempo/tempo.yaml", "-target=all"]
environment:
GOMEMLIMIT: 400MiB
volumes:
- tempo_data:/var/tempo
- type: bind
source: ./infra/otel/tempo/tempo.yaml
target: /etc/tempo/tempo.yaml
read_only: true
bind:
create_host_path: false
networks:
- telemetry
deploy:
resources:
limits:
cpus: "0.5"
memory: 512M
# Grafana — интерфейс без своего состояния (tmpfs): источники и dashboard —
# provisioning из git, пароль администратора из .env действует на каждом
# старте. Наружу — только 127.0.0.1. Без анонимного входа, регистрации,
# установки плагинов из сети, отчётов и проверок обновлений; встроенные
# источники, кроме prometheus, loki и tempo, выключены (каждый — свой
# процесс)
grafana:
image: grafana/grafana:13.3.1@sha256:0615ec4fbd4072004b7d86b46ded63013a74b7d6eb1119273dd89e8fa25c13cf
restart: unless-stopped
environment:
GF_SECURITY_ADMIN_USER: admin
GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?GRAFANA_ADMIN_PASSWORD is empty, run make env_setup}
GF_SECURITY_DISABLE_GRAVATAR: "true"
GF_AUTH_ANONYMOUS_ENABLED: "false"
GF_AUTH_DISABLE_SIGNOUT_MENU: "false"
GF_USERS_ALLOW_SIGN_UP: "false"
GF_USERS_ALLOW_ORG_CREATE: "false"
GF_ANALYTICS_REPORTING_ENABLED: "false"
GF_ANALYTICS_CHECK_FOR_UPDATES: "false"
GF_ANALYTICS_CHECK_FOR_PLUGIN_UPDATES: "false"
GF_ANALYTICS_FEEDBACK_LINKS_ENABLED: "false"
GF_NEWS_NEWS_FEED_ENABLED: "false"
GF_SNAPSHOTS_EXTERNAL_ENABLED: "false"
GF_PLUGINS_PREINSTALL_DISABLED: "true"
GF_PLUGINS_PUBLIC_KEY_RETRIEVAL_DISABLED: "true"
GF_PLUGINS_DISABLE_PLUGINS: cloudwatch,elasticsearch,grafana-postgresql-datasource,grafana-pyroscope-datasource,influxdb,jaeger,mssql,mysql,opentsdb,stackdriver,zipkin,grafana-azure-monitor-datasource,graphite,grafana-testdata-datasource
GOMEMLIMIT: 300MiB
ports:
- "127.0.0.1:${GRAFANA_OUT_PORT:-3000}:3000"
tmpfs:
- /var/lib/grafana
volumes:
- type: bind
source: ./infra/otel/grafana/datasources.yaml
target: /etc/grafana/provisioning/datasources/datasources.yaml
read_only: true
bind:
create_host_path: false
- type: bind
source: ./infra/otel/grafana/dashboards.yaml
target: /etc/grafana/provisioning/dashboards/dashboards.yaml
read_only: true
bind:
create_host_path: false
- type: bind
source: ./infra/otel/grafana/dashboards/messenger-overview.json
target: /etc/grafana/dashboards/messenger-overview.json
read_only: true
bind:
create_host_path: false
networks:
- telemetry
healthcheck:
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:3000/api/health"]
interval: 10s
timeout: 3s
retries: 5
start_period: 60s
start_interval: 1s
deploy:
resources:
limits:
cpus: "0.5"
memory: 384M
networks:
# хранилища телеметрии и Grafana: контейнеры приложения до них не достают,
# связь — только через Collector (он в обеих сетях). Не internal: иначе не
# работает опубликованный порт Grafana
telemetry:
volumes:
postgres_data:
s3_data:
rabbitmq_data:
prometheus_data:
loki_data:
tempo_data:
+91
View File
@@ -0,0 +1,91 @@
# `driver.py stand-from-scratch --runs 2` (change `otel-telemetry`, задача 11.3)
- Основа: commit `9b35c25` (propose), **рабочее дерево не закоммичено** (apply change
`otel-telemetry`). Основная сессия решает, переснимать ли после коммита.
- Дата: 2026-11-11, старт 06:27:32Z, ~2 мин; команда из корня:
`python3 .claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2`.
- Сценарий `container-run` «Стенд с нуля одной командой» (design, решения 19 и 21). Проект compose
`mtusi-lab6-scratch` (рабочий `mtusi-lab6` команда отказывается брать — код 2), свободные порты
хоста для `APP_OUT_PORT`, `POSTGRES_OUT_PORT`, `VALKEY_OUT_PORT`, `S3_OUT_PORT`,
`RABBITMQ_OUT_PORT`, `GRAFANA_OUT_PORT` аргументами `make run_docker`, `COMPOSE_PROJECT_NAME`
окружением. Перед первым прогоном и после каждого — `docker compose -p mtusi-lab6-scratch down -v
--remove-orphans` изнутри команды (в том числе при Ctrl+C): volumes проекта пусты перед прогоном и
после него. `.env` и `config.toml` — рабочего стенда (секреты те же, данные — свои volumes).
- Рабочий стенд на время проверки остановлен `make stop` (два стенда — 14 ГиБ лимитов на ВМ
7,75 ГиБ); его 17 контейнеров до и после — с теми же ID, затем `docker compose start`.
- До change на пустом volume брокер падал на `eacces` (`.erlang.cookie` от root,
`KNOWN_ISSUES.md`) и `make run_docker` кончался кодом 1; healthcheck теперь
`gosu rabbitmq rabbitmq-diagnostics -q check_port_connectivity`.
```
working stand mtusi-lab6: 17 containers
down -v mtusi-lab6-scratch: code 0
run 1: make run_docker took 13 s
down -v mtusi-lab6-scratch: code 0
run 2: make run_docker took 12 s
down -v mtusi-lab6-scratch: code 0
run 1: project volumes before expected 0 got 0
run 1: make run_docker exit code expected 0 got 0
run 1: api state expected running:0 got running:0
run 1: cleaner state expected running:0 got running:0
run 1: grafana state expected running:0 got running:0
run 1: haproxy state expected running:0 got running:0
run 1: loki state expected running:0 got running:0
run 1: migrate state expected exited:0 got exited:0
run 1: otel-collector state expected running:0 got running:0
run 1: postgres state expected running:0 got running:0
run 1: prometheus state expected running:0 got running:0
run 1: rabbitmq state expected running:0 got running:0
run 1: relay state expected running:0 got running:0
run 1: s3 state expected running:0 got running:0
run 1: s3-bootstrap state expected exited:0 got exited:0
run 1: tempo state expected running:0 got running:0
run 1: valkey state expected running:0 got running:0
run 1: worker state expected running:0 got running:0
run 1: rabbitmq RestartCount expected 0 got 0
run 1: otel-collector RestartCount expected 0 got 0
run 1: prometheus RestartCount expected 0 got 0
run 1: loki RestartCount expected 0 got 0
run 1: tempo RestartCount expected 0 got 0
run 1: grafana RestartCount expected 0 got 0
run 1: eacces / permission denied in logs expected 0 got 0
run 1: grafana datasources provisioned and healthy expected yes got yes
run 1: dashboard provisioned expected 200 True got 200 True
run 1: make test through its LB expected 0 PASS got 0 PASS
run 1: volumes left expected 0 got 0
run 2: project volumes before expected 0 got 0
run 2: make run_docker exit code expected 0 got 0
run 2: api state expected running:0 got running:0
run 2: cleaner state expected running:0 got running:0
run 2: grafana state expected running:0 got running:0
run 2: haproxy state expected running:0 got running:0
run 2: loki state expected running:0 got running:0
run 2: migrate state expected exited:0 got exited:0
run 2: otel-collector state expected running:0 got running:0
run 2: postgres state expected running:0 got running:0
run 2: prometheus state expected running:0 got running:0
run 2: rabbitmq state expected running:0 got running:0
run 2: relay state expected running:0 got running:0
run 2: s3 state expected running:0 got running:0
run 2: s3-bootstrap state expected exited:0 got exited:0
run 2: tempo state expected running:0 got running:0
run 2: valkey state expected running:0 got running:0
run 2: worker state expected running:0 got running:0
run 2: rabbitmq RestartCount expected 0 got 0
run 2: otel-collector RestartCount expected 0 got 0
run 2: prometheus RestartCount expected 0 got 0
run 2: loki RestartCount expected 0 got 0
run 2: tempo RestartCount expected 0 got 0
run 2: grafana RestartCount expected 0 got 0
run 2: eacces / permission denied in logs expected 0 got 0
run 2: grafana datasources provisioned and healthy expected yes got yes
run 2: dashboard provisioned expected 200 True got 200 True
run 2: make test through its LB expected 0 PASS got 0 PASS
run 2: volumes left expected 0 got 0
working stand mtusi-lab6: same container IDs expected yes got yes
PASS: make run_docker on empty volumes passed 2 times at the first attempt
```
Код выхода — 0. «running:0» — состояние и код выхода контейнера (`docker compose ps --format
json`) через 30 с после `make run_docker`; у двух реплик API состояние одно.
+63
View File
@@ -0,0 +1,63 @@
# Бюджет стенда с телеметрией (change `otel-telemetry`, задача 10.1)
- Основа: commit `9b35c25` (propose), **рабочее дерево не закоммичено** (apply change
`otel-telemetry`); основная сессия решает, переснимать ли после коммита.
- Дата: 2026-11-11, стенд — проект compose `mtusi-lab6` (`make run_docker`), Docker 29.9.2,
ВМ Docker Desktop 12 CPU / 7934 МиБ, ядро 7.0.14-linuxkit.
- Методика (design, решение 7): на фазу — свежие cgroup реплик API и worker (`docker compose
up -d --no-deps --force-recreate --wait api worker`), 30 с простоя (`docker stats`), затем
`make test` и `make load` (30 с, 4 клиента, closed-loop запись) под выборкой `docker stats`
раз в 2 с; в конце `memory.peak` каждого контейнера (cgroup v2 ВМ, одноразовый контейнер с
`--cgroupns host`, только чтение). Фаза «выключена» — тот же стенд с override
`TELEMETRY__ENABLED: "false"` у `api` и `worker`. Пик сервисов телеметрии — с их старта
(включает `telemetry-check` и `telemetry-outage`, снятые раньше), а не за фазу.
- Скрипт замера — во временном каталоге сессии, в git не идёт; это одноразовая проверка
лимитов, а не метка `bench/`.
## Память и CPU
| Контейнер | Фаза | Простой, МиБ | Под нагрузкой (макс. выборки), МиБ | CPU макс., % | `memory.peak`, МиБ | Лимит, МиБ | 1,5 × пик ≤ лимита |
|---|---|---|---|---|---|---|---|
| `api-1` | телеметрия включена | 111,4 | 226,1 | 71,0 | 229,6 | 512 | да (344) |
| `api-2` | включена | 111,6 | 225,6 | 71,3 | 227,3 | 512 | да (341) |
| `worker` | включена | 101,0 | 103,6 | 31,1 | 120,0 | 1024 | да (180) |
| `api-1` | выключена | 109,8 | 213,0 | 75,4 | 213,7 | 512 | — |
| `api-2` | выключена | 113,3 | 212,6 | 66,4 | 216,5 | 512 | — |
| `worker` | выключена | 100,0 | 102,0 | 25,4 | 119,4 | 1024 | — |
| `otel-collector` | — | 47,7 | 71,4 | 2,6 | 71,8 | 256 | да (108) |
| `prometheus` | — | 66,2 | 68,3 | 1,6 | 76,4 | 384 | да (115) |
| `loki` | — | 59,0 | 103,5 | 3,5 | 116,8 | 512 | да (175) |
| `tempo` | — | 43,8 | 211,5 | 7,6 | 234,8 | 512 | да (352) |
| `grafana` | — | 239,1 | 240,3 | 2,1 | 249,1 | 384 | да (374) |
- Реплика API в своём лимите: пик 230 МиБ с телеметрией против 216 без неё (+~14 МиБ: SDK,
очереди span и записей, экспортёры).
- Пик Tempo — 235 МиБ во время простоя второй фазы (запись блоков после нагрузки), под
нагрузкой первой — 97 МиБ. Grafana ближе всех к границе правила: 249 × 1,5 = 374 из 384 МиБ.
Лимиты решения 7 правило «не меньше 1,5 × пика» выполняют, поднимать не пришлось.
## Цена SDK в репликах (грубо, один прогон)
`make load` (30 с, 4 клиента) на том же стенде подряд:
| Телеметрия | Успешных запросов/с | p50, мс | p95, мс | p99, мс | Ошибок |
|---|---|---|---|---|---|
| включена | 437,3 | 7,7 | 15,8 | 33,1 | 0 |
| выключена | 499,1 | 7,2 | 10,4 | 19,1 | 0 |
Один прогон closed-loop на шумном хосте, не метка `bench/`: это порядок цены (−12 % RPS, хвост
выше), а не замер; исследование — трек 1 «Цена наблюдаемости».
## Суммы лимитов (`docker compose config`)
| | CPU | Память, МиБ |
|---|---|---|
| сервисы телеметрии (`otel-collector`, `prometheus`, `loki`, `tempo`, `grafana`) | 2,5 | 2048 |
| постоянные сервисы стенда (2 реплики API) | 11,5 | 7040 |
| с одноразовыми (`migrate`, `s3-bootstrap`) | 12,5 | 7424 |
| ВМ Docker | 12 | 7934 |
Лимиты — потолки, а не резерв: CPU делится по времени, а память простоя всего стенда после
замера (`docker stats`) — 1715 МиБ, из них сервисы телеметрии — 770 МиБ (Tempo после записи
блоков держит больше, чем на старте). Совпадает с `docker inspect`
(`HostConfig.NanoCpus`, `HostConfig.Memory`) всех контейнеров рабочего стенда.
+148
View File
@@ -0,0 +1,148 @@
# `driver.py --port 8080 telemetry-check` (change `otel-telemetry`, задача 11.1)
- Основа: commit `9b35c25` (propose), **рабочее дерево не закоммичено** (apply change
`otel-telemetry`); образ `mtusi-messenger:lab6` собран `make run_docker` из этого дерева.
Основная сессия решает, переснимать ли после коммита.
- Дата: 2026-11-11, старт 06:10:37Z, ~2 мин; рабочий стенд `mtusi-lab6` (две реплики API,
worker, Collector, Prometheus, Loki, Tempo, Grafana), команда из корня репозитория:
`python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 telemetry-check`.
- Всё — через HTTP API Grafana на `127.0.0.1:3000` с паролем из `.env` (источники-прокси uid
`prometheus`, `loki`, `tempo`); пароль, токены и тела в вывод не попадают. Пароль, `username`,
токен, текст, ключ и имя файла пробы — случайные синтетические, в выводе только их метки
U, P, T, M, K, F.
- Сценарии: `observability` — «Стенд с телеметрией», «Хранилища недоступны приложению»,
«История после рестарта хранилищ», «Provisioning после старта», «Источник правды — git», «Вход
в Grafana», «Ресурс сигналов», «Чужой traceparent», «Запросы в метрике», «Health не
учитывается», «Необычный метод и неизвестный путь» (см. ниже), «Готовое вложение в метриках»,
«Неудачное вложение в метриках», «Трасса запроса», «Трасса задания», «Отказ S3 в трассе»,
«Health и фоновые циклы без трасс», «Проба приватности», «Запрос найден», «Задание найдено»;
`service-logging` — «Записи запроса ведут к трассе», «Записи задания ведут к трассе», «Запись в
Loki совпадает со stdout»; `service-configuration` — «Переменные OTEL_* не действуют».
- Отклонение (design, «Уточнения apply»): метод `BREW` HTTP-парсер uvicorn (httptools) отклоняет
400 текстом до приложения — ни span, ни ряда (`KNOWN_ISSUES.md`); ряд `_OTHER` без `http_route`
проверен на `PROPFIND` к неизвестному пути с UUID, у обоих — ни метода, ни UUID в метках.
- Свой запрос: `X-Request-Id` `acfab668a2fe4b4b865f03382d20a571`, `X-Instance-Id`
`dd98da9edd95`, trace-id `73907d1c87e5087abd1b998e3a06c89d`; проба приватности просмотрела
44 записи Loki (столько же, сколько записей stdout `api` и `worker` и разового контейнера за
окно), 29 трасс Tempo и 860 рядов Prometheus.
```
grafana without credentials expected 401 got 401
grafana wrong password expected 401 got 401
grafana password from .env expected 200 got 200
grafana published only on 127.0.0.1 expected yes got yes
datasource prometheus expected 200 prometheus got 200 prometheus
datasource prometheus health expected OK got OK
datasource loki expected 200 loki got 200 loki
datasource loki health expected OK got OK
datasource tempo expected 200 tempo got 200 tempo
datasource tempo health expected OK got OK
dashboard from git expected 200 got 200
dashboard provisioned expected True got True
dashboard folder expected Messenger got Messenger
save of the provisioned dashboard rejected expected yes got yes
dashboard equals git after the attempt expected yes got yes
prometheus target otel-collector up expected 1 got 1
prometheus target otel-collector-exporter up expected 1 got 1
prometheus target loki up expected 1 got 1
prometheus target tempo up expected 1 got 1
prometheus target prometheus up expected 1 got 1
register probe user expected 201 got 201
login by Basic expected 201 got 201
create chat expected 201 got 201
send message expected 201 got 201
401 without token expected 401 got 401
404 of an unknown chat expected 404 got 404
BREW rejected by the HTTP parser before the app expected 400 got 400
PROPFIND of an unknown path with a UUID expected 404 got 404
request with traceparent expected 200 got 200
upload sample.png expected 202 got 202
attachment becomes ready expected ready got ready
undecodable JPEG generated expected yes got yes
upload undecodable JPEG expected 202 got 202
undecodable JPEG becomes failed expected failed got failed
stdout records of the request expected yes got yes
one trace_id and span_id in them expected 1 got 1
trace_id format expected yes got yes
Loki record of the request expected 1 got 1
Loki service_name expected messenger-api got messenger-api
Loki service_instance_id = X-Instance-Id expected dd98da9edd95 got dd98da9edd95
Loki instance_id = X-Instance-Id expected dd98da9edd95 got dd98da9edd95
Loki trace_id = stdout expected 73907d1c87e5087abd1b998e3a06c89d got 73907d1c87e5087abd1b998e3a06c89d
Loki event, method, path, status, duration = stdout expected yes got yes
Tempo server span expected POST /api/v1/chats/{chat_id}/messages SPAN_KIND_SERVER got POST /api/v1/chats/{chat_id}/messages SPAN_KIND_SERVER
server span status code expected 201 got 201
server span request id = X-Request-Id expected acfab668a2fe4b4b865f03382d20a571 got acfab668a2fe4b4b865f03382d20a571
resource service.name expected messenger-api got messenger-api
resource service.instance.id expected dd98da9edd95 got dd98da9edd95
resource service.version = contract expected 1.6.0 got 1.6.0
resource deployment.environment.name expected lab got lab
PostgreSQL query spans under it expected yes got yes
COMMIT span under it expected yes got yes
traceparent request has its own trace expected yes got yes
spans of the foreign trace-id in Tempo expected 0 got 0
its server span has no parent expected yes got yes
Loki worker record of the attachment expected 1 got 1
worker stdout records carry the job trace_id expected yes got yes
Tempo consumer span expected SPAN_KIND_CONSUMER ready got SPAN_KIND_CONSUMER ready
worker resource service.name expected messenger-worker got messenger-worker
job spans: PostgreSQL expected yes got yes
job spans: S3.GetObject (staging) expected yes got yes
job spans: S3.PutObject (original and 3 variants) expected yes got yes
job spans: render process expected yes got yes
upload with S3 paused expected 503 got 503
its server span status expected STATUS_CODE_ERROR got STATUS_CODE_ERROR
S3 span with error expected yes got yes
S3 span duration within 4.0-7.5 s expected yes got yes
error.type of the S3 span set expected yes got yes
health traces in Tempo expected 0 got 0
trace roots other than requests and deliveries expected 0 got 0
api -> prometheus expected not reachable got not reachable
api -> loki expected not reachable got not reachable
api -> tempo expected not reachable got not reachable
api -> grafana expected not reachable got not reachable
api -> otel-collector:4318 expected connected got connected
worker -> prometheus expected not reachable got not reachable
worker -> loki expected not reachable got not reachable
worker -> tempo expected not reachable got not reachable
worker -> grafana expected not reachable got not reachable
worker -> otel-collector:4318 expected connected got connected
probe container with OTEL_* started expected 0 got 0
probe container healthy expected yes got yes
probe request inside expected 401 got 401
warning level expected warning got warning
warning names the variables expected ['OTEL_EXPORTER_OTLP_ENDPOINT', 'OTEL_SDK_DISABLED'] got ['OTEL_EXPORTER_OTLP_ENDPOINT', 'OTEL_SDK_DISABLED']
no variable values in stdout expected yes got yes
probe records reach Loki from [telemetry] expected yes got yes
probe service_name expected messenger-api got messenger-api
chat GET 200 count grew by 10 expected 10 got 10
count grew on every replica expected 2 got 2
jobs ready grew by 1 expected 1 got 1
jobs failed grew by 1 expected 1 got 1
_OTHER series without http_route expected yes got yes
401 series of /api/v1/users/me expected yes got yes
404 series of /api/v1/chats/{chat_id} expected yes got yes
forbidden label names expected [] got []
label values that are UUIDs expected 0 got 0
label values with BREW, PROPFIND or the odd UUID expected 0 got 0
dashboard panel queries (11) without error expected 0 got 0
panel queries with data after traffic expected [] got []
U in telemetry expected [] got []
P in telemetry expected [] got []
T in telemetry expected [] got []
M in telemetry expected [] got []
K in telemetry expected [] got []
F in telemetry expected [] got []
Bearer in telemetry expected [] got []
Basic in telemetry expected [] got []
foreign trace-id in telemetry expected [] got []
pipeline back after restart expected yes got yes
same Loki record after restart expected yes got yes
same trace after restart expected yes got yes
same metric value at the saved time expected 10 got 10
PASS: own request and job are found in Loki, Tempo and Prometheus through Grafana, no secrets in telemetry
```
Код выхода — 0. «Same metric value at the saved time» — значение суммы ряда GET карточки чата на
момент снимка до рестарта, запрошенное снова после `docker compose restart otel-collector
prometheus loki tempo` (параметр `time` запроса).
+89
View File
@@ -0,0 +1,89 @@
# `driver.py --port 8080 telemetry-outage` (change `otel-telemetry`, задача 11.2)
- Основа: commit `9b35c25` (propose), **рабочее дерево не закоммичено** (apply change
`otel-telemetry`); образ собран `make run_docker` из этого дерева. Основная сессия решает,
переснимать ли после коммита.
- Дата: 2026-11-11, старт 06:13:24Z, ~2,5 мин; рабочий стенд `mtusi-lab6`, команда из корня:
`python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 telemetry-outage`.
- Сценарии: `observability` «Collector остановлен», «Collector заморожен»; `service-logging`
«Отказ отправки журнала»; `container-run` «Приложение без телеметрии»; `graceful-shutdown`
«docker stop при остановленном Collector», «docker stop при замороженном Collector».
- Ход: на фазу — `docker compose stop` (или `pause`) `otel-collector`; `make test` через LB;
`/health/ready`; свой `GET /users/me` и его запись в stdout; загрузка `sample.png` до `ready`;
окно не меньше 20 с, чтобы экспорт трёх сигналов успел отказать; записи логгеров
`opentelemetry.*` в stdout каждого контейнера `api` и `worker` с начала фазы; `docker stop
--timeout 10` одной реплики и `docker compose stop worker` (время, код выхода, запись об
остановке в stdout); `make replicas`, запуск worker; возврат Collector (`start` / `unpause`) — и
новые запись API в Loki, трасса API в Tempo, запись worker в Loki, ряды API и worker в
Prometheus с отметкой времени позже возврата, без перезапуска процессов. Последняя фаза — все
пять сервисов телеметрии остановлены, `docker compose restart api worker`, `make test`, затем
возврат телеметрии и сигналы снова. В `finally` — `unpause` и `start` телеметрии, `make
replicas`, worker и relay.
- Время остановки при недоступном Collector: реплика API — 1,55 с (stop) и 1,58 с (pause), worker
— 0,72 с в обоих случаях; срок закрытия SDK — 1 с у API и окно 0,5 с у worker
(`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS`, design, решение 13).
- Записи SDK об отказе — по одной на модуль экспортёра (трассы, метрики, логи) на контейнер за
окно: фильтр пропускает не больше одной в минуту на логгер. В фазе `pause` у части контейнеров
экспортёр логов ещё не дождался срока отправки к моменту подсчёта — записей меньше трёх.
```
[collector stop] SDK records in 20 s: {'cf1cf6304893 opentelemetry.exporter.otlp.proto.http._log_exporter': 1, 'cf1cf6304893 opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, 'cf1cf6304893 opentelemetry.exporter.otlp.proto.http.metric_exporter': 1, 'dd98da9edd95 opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, 'dd98da9edd95 opentelemetry.exporter.otlp.proto.http._log_exporter': 1, 'dd98da9edd95 opentelemetry.exporter.otlp.proto.http.metric_exporter': 1, '7ba13dcb409f opentelemetry.exporter.otlp.proto.http._log_exporter': 1, '7ba13dcb409f opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, '7ba13dcb409f opentelemetry.exporter.otlp.proto.http.metric_exporter': 1}
[collector stop] docker stop api cf1cf6304893: 1.55 s
[collector stop] docker compose stop worker: 0.72 s
[collector pause] SDK records in 20 s: {'cf1cf6304893 opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, 'cf1cf6304893 opentelemetry.exporter.otlp.proto.http.metric_exporter': 1, 'dd98da9edd95 opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, '7ba13dcb409f opentelemetry.exporter.otlp.proto.http.trace_exporter': 1, '7ba13dcb409f opentelemetry.exporter.otlp.proto.http.metric_exporter': 1}
[collector pause] docker stop api cf1cf6304893: 1.58 s
[collector pause] docker compose stop worker: 0.72 s
[collector stop] make test expected 0 PASS got 0 PASS
[collector stop] /health/ready expected 200 got 200
[collector stop] upload becomes ready expected yes got yes
[collector stop] own request record in stdout expected yes got yes
[collector stop] SDK records per logger at most 1 expected yes got yes
[collector stop] docker stop api faster than 10 s expected yes got yes
[collector stop] api exit code expected 0 got 0
[collector stop] Stopped API in stdout expected yes got yes
[collector stop] stop worker faster than 10 s expected yes got yes
[collector stop] worker exit code expected 0 got 0
[collector stop] Stopped worker in stdout expected yes got yes
[collector stop] worker started again expected yes got yes
[collector stop] LB ready expected yes got yes
[collector stop] API record reaches Loki again expected yes got yes
[collector stop] API trace reaches Tempo again expected yes got yes
[collector stop] worker record reaches Loki again expected yes got yes
[collector stop] API metrics scraped again expected yes got yes
[collector stop] worker metrics scraped again expected yes got yes
[collector pause] make test expected 0 PASS got 0 PASS
[collector pause] /health/ready expected 200 got 200
[collector pause] upload becomes ready expected yes got yes
[collector pause] own request record in stdout expected yes got yes
[collector pause] SDK records per logger at most 1 expected yes got yes
[collector pause] docker stop api faster than 10 s expected yes got yes
[collector pause] api exit code expected 0 got 0
[collector pause] Stopped API in stdout expected yes got yes
[collector pause] stop worker faster than 10 s expected yes got yes
[collector pause] worker exit code expected 0 got 0
[collector pause] Stopped worker in stdout expected yes got yes
[collector pause] worker started again expected yes got yes
[collector pause] LB ready expected yes got yes
[collector pause] API record reaches Loki again expected yes got yes
[collector pause] API trace reaches Tempo again expected yes got yes
[collector pause] worker record reaches Loki again expected yes got yes
[collector pause] API metrics scraped again expected yes got yes
[collector pause] worker metrics scraped again expected yes got yes
[telemetry down] app services depend on telemetry expected [] got []
[telemetry down] docker compose restart api worker expected 0 got 0
[telemetry down] LB ready expected yes got yes
[telemetry down] replicas started expected 2 got 2
[telemetry down] worker started expected yes got yes
[telemetry down] make test expected 0 PASS got 0 PASS
[telemetry down] Grafana back expected yes got yes
[telemetry down] API record reaches Loki again expected yes got yes
[telemetry down] API trace reaches Tempo again expected yes got yes
[telemetry down] worker record reaches Loki again expected yes got yes
[telemetry down] API metrics scraped again expected yes got yes
[telemetry down] worker metrics scraped again expected yes got yes
PASS: API and worker work and stop in time without the Collector, signals come back without restarts
restored: telemetry services started, replicas and worker running: yes
```
Код выхода — 0.
+70
View File
@@ -0,0 +1,70 @@
# OTel Collector contrib 0.164.0 (design change otel-telemetry, решения 1, 3,
# 14): получатель, обработчик и экспортёр, не хранилище. Три pipeline — каждый
# до своего хранилища: метрики — scrape Prometheus с экспортёра prometheus,
# логи — Loki (родной OTLP), трассы — Tempo. Расширений нет (pprof, zpages,
# health_check образа не берутся). Порты наружу не публикуются: OTLP
# слушает сеть приложения, :8888 и :8889 забирает Prometheus в сети
# telemetry.
receivers:
otlp:
protocols:
# только OTLP/HTTP: SDK приложения отправляет protobuf по HTTP
http:
endpoint: 0.0.0.0:4318
processors:
# предел памяти Collector: при 200 МиБ отказ приёма (SDK получает ошибку и
# теряет пакет), всплеск — 40 МиБ; GOMEMLIMIT контейнера — 160 МиБ
memory_limiter:
check_interval: 1s
limit_mib: 200
spike_limit_mib: 40
# пакеты до хранилищ: не больше 1024 элементов или раз в секунду
batch:
send_batch_size: 1024
timeout: 1s
exporters:
# метрики приложения для scrape Prometheus (honor_labels): job =
# service.name, instance = service.instance.id, остальной ресурс —
# target_info; ряды остановленной реплики уходят через 5 мин
prometheus:
endpoint: 0.0.0.0:8889
translation_strategy: UnderscoreEscapingWithSuffixes
metric_expiration: 5m
resource_to_telemetry_conversion:
enabled: false
# sending_queue и retry_on_failure — по умолчанию: явные пределы и учёт
# потерь — change 3 (уровень 4)
otlp_http/loki:
endpoint: http://loki:3100/otlp
otlp_http/tempo:
endpoint: http://tempo:4318
service:
telemetry:
logs:
level: info
encoding: json
# собственные метрики Collector — для Prometheus (жив ли конвейер)
metrics:
level: normal
readers:
- pull:
exporter:
prometheus:
host: 0.0.0.0
port: 8888
pipelines:
metrics:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [prometheus]
logs:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp_http/loki]
traces:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp_http/tempo]
+17
View File
@@ -0,0 +1,17 @@
# Провайдер dashboard из файлов (design change otel-telemetry, решение 16):
# JSON из git, правки из интерфейса не сохраняются, удалить нельзя. Каталог
# /etc/grafana/dashboards — bind mount файла dashboard (только чтение).
apiVersion: 1
providers:
- name: messenger
orgId: 1
folder: Messenger
folderUid: messenger
type: file
disableDeletion: true
allowUiUpdates: false
updateIntervalSeconds: 60
options:
path: /etc/grafana/dashboards
foldersFromFilesStructure: false
@@ -0,0 +1,238 @@
{
"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.",
"tags": ["messenger", "lab6"],
"timezone": "utc",
"editable": false,
"graphTooltip": 1,
"schemaVersion": 39,
"version": 1,
"refresh": "30s",
"time": {"from": "now-1h", "to": "now"},
"annotations": {"list": []},
"templating": {"list": []},
"links": [],
"panels": [
{
"id": 1,
"type": "row",
"title": "API (messenger-api)",
"collapsed": false,
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 0},
"panels": []
},
{
"id": 2,
"type": "timeseries",
"title": "Requests per second by route and status class",
"description": "Count of the http.server.request.duration histogram, all replicas; health is not recorded.",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 12, "x": 0, "y": 1},
"fieldConfig": {"defaults": {"unit": "reqps"}, "overrides": []},
"options": {"legend": {"displayMode": "table", "placement": "right", "calcs": ["lastNotNull"]}, "tooltip": {"mode": "multi", "sort": "desc"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum by (http_route, status_class) (label_replace(rate(http_server_request_duration_seconds_count{job=\"messenger-api\"}[5m]), \"status_class\", \"${1}xx\", \"http_response_status_code\", \"([0-9])..\"))",
"legendFormat": "{{http_route}} {{status_class}}"
}
]
},
{
"id": 3,
"type": "timeseries",
"title": "Error ratio (5xx of all requests)",
"description": "Numerator: API responses 5xx; denominator: all recorded requests. 4xx are shown separately; responses generated by the load balancer are not in API metrics.",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 6, "x": 12, "y": 1},
"fieldConfig": {"defaults": {"unit": "percentunit", "min": 0}, "overrides": []},
"options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "single"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum(rate(http_server_request_duration_seconds_count{job=\"messenger-api\",http_response_status_code=~\"5..\"}[5m])) / sum(rate(http_server_request_duration_seconds_count{job=\"messenger-api\"}[5m]))",
"legendFormat": "5xx ratio"
}
]
},
{
"id": 4,
"type": "timeseries",
"title": "Client errors ratio (4xx of all requests)",
"description": "Wrong password, foreign chat, validation: not part of the error ratio.",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 6, "x": 18, "y": 1},
"fieldConfig": {"defaults": {"unit": "percentunit", "min": 0}, "overrides": []},
"options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "single"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum(rate(http_server_request_duration_seconds_count{job=\"messenger-api\",http_response_status_code=~\"4..\"}[5m])) / sum(rate(http_server_request_duration_seconds_count{job=\"messenger-api\"}[5m]))",
"legendFormat": "4xx ratio"
}
]
},
{
"id": 5,
"type": "timeseries",
"title": "Request duration p50 and p95 (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},
"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(http_server_request_duration_seconds_bucket{job=\"messenger-api\"}[5m])))",
"legendFormat": "p50"
},
{
"refId": "B",
"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"
}
]
},
{
"id": 6,
"type": "timeseries",
"title": "Request duration p95 by route",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 12, "x": 12, "y": 9},
"fieldConfig": {"defaults": {"unit": "s", "min": 0}, "overrides": []},
"options": {"legend": {"displayMode": "table", "placement": "right", "calcs": ["lastNotNull"]}, "tooltip": {"mode": "multi", "sort": "desc"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "histogram_quantile(0.95, sum by (le, http_route) (rate(http_server_request_duration_seconds_bucket{job=\"messenger-api\"}[5m])))",
"legendFormat": "{{http_route}}"
}
]
},
{
"id": 7,
"type": "row",
"title": "Worker (messenger-worker)",
"collapsed": false,
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 17},
"panels": []
},
{
"id": 8,
"type": "timeseries",
"title": "Jobs per second by outcome",
"description": "Count of messenger.job.duration by messenger.job.outcome. Successful: ready; failed: failed, retry, requeued, dropped, error; skipped is neither.",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 8, "x": 0, "y": 18},
"fieldConfig": {"defaults": {"unit": "ops"}, "overrides": []},
"options": {"legend": {"displayMode": "table", "placement": "bottom", "calcs": ["lastNotNull"]}, "tooltip": {"mode": "multi", "sort": "desc"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum by (messenger_job_outcome) (rate(messenger_job_duration_seconds_count{job=\"messenger-worker\"}[5m]))",
"legendFormat": "{{messenger_job_outcome}}"
}
]
},
{
"id": 9,
"type": "timeseries",
"title": "Successful and failed jobs per second",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 8, "x": 8, "y": 18},
"fieldConfig": {"defaults": {"unit": "ops", "min": 0}, "overrides": []},
"options": {"legend": {"displayMode": "list", "placement": "bottom"}, "tooltip": {"mode": "multi"}},
"targets": [
{
"refId": "A",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum(rate(messenger_job_duration_seconds_count{job=\"messenger-worker\",messenger_job_outcome=\"ready\"}[5m]))",
"legendFormat": "successful (ready)"
},
{
"refId": "B",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"expr": "sum(rate(messenger_job_duration_seconds_count{job=\"messenger-worker\",messenger_job_outcome=~\"failed|retry|requeued|dropped|error\"}[5m]))",
"legendFormat": "failed"
}
]
},
{
"id": 10,
"type": "timeseries",
"title": "Job duration p50 and p95 (ready)",
"description": "Handling of one delivery after the concurrency slot, outcome ready.",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"gridPos": {"h": 8, "w": 8, "x": 16, "y": 18},
"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_duration_seconds_bucket{job=\"messenger-worker\",messenger_job_outcome=\"ready\"}[5m])))",
"legendFormat": "p50"
},
{
"refId": "B",
"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"
}
]
},
{
"id": 11,
"type": "row",
"title": "Logs and traces",
"collapsed": false,
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 26},
"panels": []
},
{
"id": 12,
"type": "logs",
"title": "API and worker 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},
"options": {"showTime": true, "showLabels": false, "wrapLogMessage": true, "sortOrder": "Descending", "enableLogDetails": true, "dedupStrategy": "none", "prettifyLogMessage": false},
"targets": [
{
"refId": "A",
"datasource": {"type": "loki", "uid": "loki"},
"expr": "{service_name=~\"messenger-.*\"}",
"queryType": "range"
}
]
},
{
"id": 13,
"type": "table",
"title": "Recent traces",
"description": "TraceQL search of API requests 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},
"options": {"showHeader": true},
"targets": [
{
"refId": "A",
"datasource": {"type": "tempo", "uid": "tempo"},
"queryType": "traceql",
"query": "{ resource.service.name =~ \"messenger-.*\" }",
"limit": 20,
"tableType": "traces"
}
]
}
]
}
+60
View File
@@ -0,0 +1,60 @@
# Источники Grafana (design change otel-telemetry, решение 16): постоянные uid,
# на которые ссылается dashboard; правка в интерфейсе запрещена. Переходы:
# запись Loki → трасса Tempo по полю trace_id (structured metadata OTLP), span
# Tempo → записи Loki той же трассы.
apiVersion: 1
prune: true
datasources:
- name: Prometheus
uid: prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
editable: false
jsonData:
httpMethod: POST
timeInterval: 15s
- name: Loki
uid: loki
type: loki
access: proxy
url: http://loki:3100
editable: false
jsonData:
maxLines: 1000
derivedFields:
- name: trace_id
datasourceUid: tempo
# поле записи OTLP, а не текст строки
matcherType: label
matcherRegex: trace_id
url: "$${__value.raw}"
urlDisplayLabel: Trace
- name: Tempo
uid: tempo
type: tempo
access: proxy
url: http://tempo:3200
editable: false
jsonData:
tracesToLogsV2:
datasourceUid: loki
spanStartTimeShift: "-5m"
spanEndTimeShift: "5m"
filterByTraceID: false
filterBySpanID: false
customQuery: true
query: '{service_name="$${__span.tags["service.name"]}"} | trace_id="$${__trace.traceId}"'
serviceMap:
datasourceUid: prometheus
nodeGraph:
enabled: false
search:
hide: false
lokiSearch:
datasourceUid: loki
+46
View File
@@ -0,0 +1,46 @@
# Loki 3.7.9 — хранилище логов (design change otel-telemetry, решение 15).
# Монолит из конфигурации образа (/etc/loki/local-config.yaml): filesystem,
# inmemory ring, schema v13 tsdb; плюс срок хранения 7 суток, compactor и без
# отчётов об использовании. Приём — родной OTLP (/otlp) от Collector, метки
# потока по умолчанию — service_name, service_instance_id,
# deployment_environment_name; поля записи — structured metadata. Порт не
# публикуется: Collector и Grafana ходят в сети telemetry.
auth_enabled: false
server:
http_listen_port: 3100
log_level: info
common:
instance_addr: 127.0.0.1
path_prefix: /loki
storage:
filesystem:
chunks_directory: /loki/chunks
rules_directory: /loki/rules
replication_factor: 1
ring:
kvstore:
store: inmemory
schema_config:
configs:
- from: 2020-10-24
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
# удаление данных старше срока делает compactor
compactor:
working_directory: /loki/compactor
retention_enabled: true
delete_request_store: filesystem
limits_config:
retention_period: 168h
analytics:
reporting_enabled: false
+30
View File
@@ -0,0 +1,30 @@
# Prometheus v3.15.1 — хранилище метрик (design change otel-telemetry,
# решения 3 и 15). Метрики приложения — scrape экспортёра prometheus
# Collector (honor_labels: job = service.name, instance = service.instance.id
# из OTLP), плюс собственные метрики Collector, Loki, Tempo и самого
# Prometheus: по ним видно, жив ли конвейер. Срок и предел объёма хранения,
# путь данных — флаги команды в docker-compose.yml. Приёмников remote write и
# OTLP, admin API и lifecycle нет; порт не публикуется.
global:
scrape_interval: 15s
scrape_timeout: 10s
evaluation_interval: 15s
scrape_configs:
# метрики API и worker, пришедшие в Collector по OTLP
- job_name: otel-collector-exporter
honor_labels: true
static_configs:
- targets: ["otel-collector:8889"]
- job_name: otel-collector
static_configs:
- targets: ["otel-collector:8888"]
- job_name: loki
static_configs:
- targets: ["loki:3100"]
- job_name: tempo
static_configs:
- targets: ["tempo:3200"]
- job_name: prometheus
static_configs:
- targets: ["127.0.0.1:9090"]
+41
View File
@@ -0,0 +1,41 @@
# Tempo 3.1.1 — хранилище трасс (design change otel-telemetry, решение 15).
# Монолит (-target=all) с локальным хранилищем, без Kafka, metrics-generator и
# MCP. Приём — OTLP/HTTP от Collector на :4318, запросы Grafana — :3200; оба
# порта только в сети telemetry. Блоки и WAL — volume tempo_data
# (/var/tempo), срок хранения блоков — 7 суток.
stream_over_http_enabled: true
server:
http_listen_port: 3200
log_level: info
distributor:
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
storage:
trace:
backend: local
wal:
path: /var/tempo/wal
local:
path: /var/tempo/blocks
# срок хранения блоков. В Tempo 3.x задания удаления ставит backend-scheduler
# (retention provider), выполняет backend-worker; у обоих свой ключ
# block_retention (по умолчанию 336h), поэтому оба — 7 суток
backend_scheduler:
provider:
compaction:
compaction:
block_retention: 168h
backend_worker:
compaction:
block_retention: 168h
usage_report:
reporting_enabled: false
+47
View File
@@ -487,3 +487,50 @@ Grafana; `telemetry-check` в CI нет (Grafana — только порт хо
Блокирующих нет. Решения без пользователя и вопросы, которые не меняют спеки и задачи, — `QUESTIONS.md`, раздел
`## otel-telemetry`.
## Уточнения apply
Apply 2026-11-11 (второй агент: первый прервался посреди работы; его правки сверены с design и доведены, а не
переписаны). Отклонения от решений и то, чего design не задавал:
1. **Версии (1).** `docker buildx imagetools inspect` дал те же digest индекса, что в таблице проб; следующих патчей тех
же линий (`0.164.1`, `v3.15.2`, `3.7.10`, `3.1.2`, `13.3.2`) в Docker Hub нет. Примечания к выпуску Grafana 13.3.1 из
песочницы не открылись (API Docker Hub и сайты недоступны curl агента) — выбор 13.3.1 оставлен по правилу решения 1.
2. **Нестандартный метод (10, сценарий «Необычный метод и неизвестный путь»).** HTTP-парсер uvicorn (httptools)
отклоняет `BREW` 400 текстом ещё до ASGI-приложения: ни span, ни ряда, ни записи — и ответ не в формате контракта
(дефект прежний, `KNOWN_ISSUES.md`). `telemetry-check` проверяет `_OTHER` без `http_route` на `PROPFIND` к
неизвестному пути с UUID (метод из списка llhttp вне стандартного набора), у `BREW` — только 400 и отсутствие метода
и UUID в метках. Сценарий спека с `BREW` по HTTP не воспроизводится; поправить его — вместе с правкой дефекта.
3. **Атрибуты сверх решения 12.** Valkey: исход `stored` у `SET` (решение называло `hit`, `miss`, `error`, `skipped`).
S3: `messenger.s3.result` (`ok`, `missing`, `error`) и `messenger.object.size` из `ContentLength` ответа, если размер
не передан. 5xx без исключения: `error.type` = код статуса строкой (как в semantic conventions HTTP). Процесс
обработки: `messenger.render.input_size`, `outcome`, `exit_code`, `peak_kib`.
4. **Закрытие SDK (13).** Три daemon-потока, по одному на провайдер, а не один последовательный: при замороженном
Collector каждый ждёт свой срок одновременно. Замер `telemetry-outage`: `docker stop` реплики — 1,55–1,58 с, worker —
0,72 с при остановленном и замороженном Collector.
5. **Подтверждение доставки** — внутри span и внутри места конкуренции (раньше `ack` шёл после выхода из семафора):
подтверждение — миллисекунды, место освобождается на них позже.
6. **Grafana (16).** Выключены 12 встроенных источников с backend (`cloudwatch`, `elasticsearch`,
`grafana-postgresql-datasource`, `grafana-pyroscope-datasource`, `influxdb`, `jaeger`, `mssql`, `mysql`, `opentsdb`,
`stackdriver`, `zipkin`) и встроенные в процесс `graphite`, `grafana-azure-monitor-datasource`,
`grafana-testdata-datasource`. Сверх решения: `GF_PLUGINS_PUBLIC_KEY_RETRIEVAL_DISABLED` (ключи подписи плагинов с
grafana.com), `GF_SNAPSHOTS_EXTERNAL_ENABLED=false`, `GF_ANALYTICS_FEEDBACK_LINKS_ENABLED=false`,
`GF_SECURITY_DISABLE_GRAVATAR`, `GF_USERS_ALLOW_ORG_CREATE=false`. В журнале старта обращений к grafana.com нет;
остаётся `warn` об устаревшей настройке `x_xss_protection` по умолчанию образа. Derived field Loki —
`matcherType: label` (поле `trace_id` — structured metadata, а не текст строки).
7. **Журналы хранилищ (задача 6.8).** Loki на старте пишет один `level=error` «empty ring» (кольцо ещё не собрано),
Tempo 3.1 в простое — `level=error` «no jobs found» раз в 15 с (backend-worker опрашивает backend-scheduler без
заданий). Это шум, не отказ: цели `up`, проверки источников проходят; названо в `REPORT.md`, «Ограничения
наблюдаемости».
8. **Tempo 3.1 API.** Неизвестный trace-id — 200 с пустой трассой, а не 404: `telemetry-check` считает span. Дочерние
span заканчиваются раньше корня и могут прийти другим пакетом: трасса без корня считается ещё не пришедшей.
9. **`telemetry-outage` (21).** Окно недоступности — не меньше 20 с, а не минута: правило «не чаще одной записи в минуту
на модуль» проверяется как «не больше ⌊окно / 60⌋ + 1 записей на логгер». Метрики «пришли снова» — ряд с отметкой
времени позже возврата Collector (`max(timestamp(…))`): рестарт Collector сбрасывает cumulative-ряды экспортёра.
10. **`stand-from-scratch` (21).** Рабочий стенд на время проверки останавливается `make stop`, после — `docker compose
start`: `make run_docker` проекта scratch пересобирает общий тег `mtusi-messenger:lab6`, и `up` рабочего стенда
пересоздал бы его реплики. Команда сверяет ID контейнеров рабочего стенда до и после.
11. **Бюджет (7).** Лимиты решения 7 не менялись: каждый не меньше 1,5 × измеренного пика (Grafana — 374 из 384 МиБ,
ближе всех); суммы прежние — 11,5 CPU / 7040 МиБ, с одноразовыми 12,5 / 7424 (`evidence/telemetry/budget.md`).
12. **Быстрые тесты (8.1–8.3)** написал прерванный агент вместе с кодом; красный прогон до кода не снимался и не
воспроизводился (git агенту запрещён). Проверяют поведение, а не вызовы: in-memory экспортёры SDK и временная база.
+40 -40
View File
@@ -6,16 +6,16 @@
## 1. Правило слоя, версии и зависимости
- [ ] 1.1 Прочитать (Read) правила `docker.md`, `infra.md`, `logging.md`, `settings.md`, `run-modes.md`, `worker.md`,
- [x] 1.1 Прочитать (Read) правила `docker.md`, `infra.md`, `logging.md`, `settings.md`, `run-modes.md`, `worker.md`,
`api-layer.md`, `service-layer.md`, `service-tests.md`, `bench.md`, `student-tests.md`, `balancer.md`; создать
`.claude/rules/telemetry.md` с `paths: ["src/infra/telemetry/**", "infra/otel/**"]` — решения 2–4, 8, 10–18 в форме
правил (что легко нарушить: правило корня, `OTEL_*`, запреты атрибутов, срок закрытия, файлы вместо каталогов для CI) — и
строку в таблице правил `AGENTS.md`. Проверка: файл есть, фронтматтер — как у соседних правил, строка в таблице.
- [ ] 1.2 Перепроверить кандидатов (1): `docker buildx imagetools inspect` для `otel/opentelemetry-collector-contrib:0.164.0`,
- [x] 1.2 Перепроверить кандидатов (1): `docker buildx imagetools inspect` для `otel/opentelemetry-collector-contrib:0.164.0`,
`prom/prometheus:v3.15.1`, `grafana/loki:3.7.9`, `grafana/tempo:3.1.1`, `grafana/grafana:13.3.1`; вышедшие позже патчи тех
же линий — по правилу решения 1. Проверка: digest в `docker-compose.yml` равен строке `Digest:` вывода, выбор — в разделе
«Уточнения apply» design.
- [ ] 1.3 `uv add` `opentelemetry-api`, `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http` с ограничением
- [x] 1.3 `uv add` `opentelemetry-api`, `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http` с ограничением
`>=1.45.2,<1.46` и комментарием в `pyproject.toml` (API логов Python без стабильного имени, библиотек
автоинструментирования нет — решение 4). Проверка: `uv lock --check`; `uv run python -c "import opentelemetry.sdk._logs,
opentelemetry.exporter.otlp.proto.http"`; в `uv.lock` нет `opentelemetry-instrumentation`; образ собирается (`docker
@@ -23,7 +23,7 @@
## 2. Настройки и шаблоны
- [ ] 2.1 Секция `Telemetry` в `src/config/settings.py` и поле `telemetry` (8): `enabled`, `otlp_endpoint` (валидатор схемы,
- [x] 2.1 Секция `Telemetry` в `src/config/settings.py` и поле `telemetry` (8): `enabled`, `otlp_endpoint` (валидатор схемы,
хоста, порта, без пути и query), `environment`, `metric_export_interval_seconds`, `export_timeout_seconds`,
`max_queue_size`, `max_export_batch_size` (не больше очереди), `schedule_delay_seconds`; `float` — `allow_inf_nan=False`.
Константы в `src/utils/constants.py`: имена сервисов, `SERVICE_VERSION = "1.6.0"`, имена метрик и атрибутов, границы
@@ -31,7 +31,7 @@
import settings; print(settings.telemetry.enabled, settings.telemetry.otlp_endpoint)"`; запуск с
`TELEMETRY__OTLP_ENDPOINT=collector:4318`, `TELEMETRY__METRIC_EXPORT_INTERVAL_SECONDS=-1`, пакетом больше очереди и `inf` —
ошибка проверки с именем поля (сценарий «Неверный параметр телеметрии»).
- [ ] 2.2 `config_example.toml` — секция `[telemetry]` с интервалами и очередями, без `enabled` и адреса; `.env.example` —
- [x] 2.2 `config_example.toml` — секция `[telemetry]` с интервалами и очередями, без `enabled` и адреса; `.env.example` —
`GRAFANA_ADMIN_PASSWORD=` и `GRAFANA_OUT_PORT=3000` с комментариями, в шапке — соответствие имён `OTEL_*` (8); `Makefile`
— `GRAFANA_ADMIN_PASSWORD` в `ENV_SECRETS` и `ENV_FILLED` (`openssl rand -hex 16`), в запросе `wipe_data` — «и хранилищ
телеметрии». Проверка: `make env_setup` на временной копии `.env` без этих строк дописывает обе под комментарием и печатает
@@ -39,17 +39,17 @@
## 3. Пакет `src/infra/telemetry/`
- [ ] 3.1 Запуск и закрытие (8, 9, 13): запуск по имени сервиса — при выключенной телеметрии ничего; при включённой —
- [x] 3.1 Запуск и закрытие (8, 9, 13): запуск по имени сервиса — при выключенной телеметрии ничего; при включённой —
удаление `OTEL_*` из окружения с `warning` по именам, ресурс из четырёх атрибутов, провайдеры трасс, метрик и логов с явными
параметрами (sampler `ALWAYS_ON`, лимиты span, очереди, сроки, `headers={}`, без сжатия, cumulative, View границ, без
exemplars, `shutdown_on_exit=False`), хуки журнала. Закрытие — `shutdown()` провайдеров в daemon-потоке и ожидание не
дольше срока. Проверка — тесты 8.1 (выключено, `OTEL_*`, ресурс, закрытие с блокирующим экспортёром не дольше срока).
- [ ] 3.2 Дочерний span (4, 12): создаётся только под записывающим родителем, ошибка — статус `ERROR` и `error.type` без
- [x] 3.2 Дочерний span (4, 12): создаётся только под записывающим родителем, ошибка — статус `ERROR` и `error.type` без
текста исключения. Проверка — тест 8.1 «правило корня».
- [ ] 3.3 PostgreSQL (12): `instrument_engine(engine)` — слушатели `before_cursor_execute`, `after_cursor_execute`,
- [x] 3.3 PostgreSQL (12): `instrument_engine(engine)` — слушатели `before_cursor_execute`, `after_cursor_execute`,
`handle_error` с атрибутами решения 12; span `COMMIT` в `SqlAlchemyUnitOfWork._commit`; фабрика engine о телеметрии не знает.
Проверка — тест 8.3 на временной базе.
- [ ] 3.4 Журнал (2, 12): в `src/infra/logger.py` — хуки в `processors` и `foreign_pre_chain` (экспорт записи, затем
- [x] 3.4 Журнал (2, 12): в `src/infra/logger.py` — хуки в `processors` и `foreign_pre_chain` (экспорт записи, затем
`trace_id` и `span_id` активного span в stdout), без импорта SDK; экспорт — в пакете телеметрии (тело, уровень, время,
атрибуты по типам, контекст; записи `opentelemetry.*` не экспортируются); фильтр частоты записей `opentelemetry.*` в stdout.
Проверка — тесты 8.1 (разбор записи, поля трассы, traceback записи `uvicorn.error`, записи SDK); при выключенной телеметрии
@@ -57,67 +57,67 @@
## 4. API
- [ ] 4.1 `RequestContextMiddleware` (10): server span и histogram `http.server.request.duration` — не для health; имя после
- [x] 4.1 `RequestContextMiddleware` (10): server span и histogram `http.server.request.duration` — не для health; имя после
маршрутизации; метод со стандартным набором и `_OTHER`; `http.route` — тот же полный шаблон, что в итоговой записи;
`messenger.request_id`; входящий `traceparent` не извлекается; 5xx и исключение — `ERROR`, `error.type`; итоговая запись — внутри
span. Проверка — тесты 8.1 (атрибуты, `_OTHER`, health, 5xx, `traceparent`); `make run_dev` + `make test` — PASS.
- [ ] 4.2 `src/main.py` (9, 13): `FastAPI(version=SERVICE_VERSION)`; в lifespan после `early_stop.disarm()` — запуск телеметрии
- [x] 4.2 `src/main.py` (9, 13): `FastAPI(version=SERVICE_VERSION)`; в lifespan после `early_stop.disarm()` — запуск телеметрии
`messenger-api` и `instrument_engine` глобального engine; «Started API» — `telemetry_enabled`, `telemetry_endpoint`,
`telemetry_environment` (сценарий «Включение окружением», запись о старте); после «Stopped API» — закрытие SDK со сроком
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS`. Проверка: `make run_dev` — запись о старте «выключена»; на стенде — «включена» с адресом
Collector; остановка — 11.2.
- [ ] 4.3 Span клиентов (12): `Cache.get` / `Cache.set` (`messenger.cache.result`), `ObjectStorage._call` (`S3.<Операция>`, без
- [x] 4.3 Span клиентов (12): `Cache.get` / `Cache.set` (`messenger.cache.result`), `ObjectStorage._call` (`S3.<Операция>`, без
ключа, `StoredObjectMissing` у HEAD — не ошибка). Проверка — тест 8.1 (фейковый клиент под родителем и без него); трасса
запроса и задания в 11.1.
## 5. Worker
- [ ] 5.1 Исход доставки (11): enum в `src/schemas/enums/` (`ready`, `failed`, `retry`, `skipped`, `requeued`, `dropped`) с
- [x] 5.1 Исход доставки (11): enum в `src/schemas/enums/` (`ready`, `failed`, `retry`, `skipped`, `requeued`, `dropped`) с
действием с сообщением; `AttachmentProcessingService.handle` и его ветки возвращают исход; быстрые тесты сервиса и
`test_worker_deliveries.py` проверяют исход каждой ветки вместо `ACK`. Проверка: `make service_test`.
- [ ] 5.2 `src/worker/main.py` (11, 13): запуск телеметрии `messenger-worker` после `early_stop.disarm()`,
- [x] 5.2 `src/worker/main.py` (11, 13): запуск телеметрии `messenger-worker` после `early_stop.disarm()`,
`instrument_engine`; в `_handle` после места конкуренции — span `CONSUMER` `process <очередь>` и histogram
`messenger.job.duration` по исходу (`error` при исключении), подтверждение внутри span; «Started worker» — поля телеметрии;
закрытие SDK в окне 0,5 с вместе с `gather` (худший случай — 9,5 с). Проверка — тест 8.2; остановка — 11.2.
- [ ] 5.3 Span процесса обработки в `ImageRenderer.render` (12): размер входа, исход, код выхода, пик памяти; окружение
- [x] 5.3 Span процесса обработки в `ImageRenderer.render` (12): размер входа, исход, код выхода, пик памяти; окружение
процесса по-прежнему без `OTEL_*` и адреса Collector. Проверка: трасса задания в 11.1; `driver.py --port <LB>
worker-process` — PASS.
## 6. Конфигурации наблюдаемости и стенд
- [ ] 6.1 `infra/otel/collector.yaml` (14): только OTLP HTTP, `memory_limiter`, `batch`, `prometheus`, `otlp_http/loki`,
- [x] 6.1 `infra/otel/collector.yaml` (14): только OTLP HTTP, `memory_limiter`, `batch`, `prometheus`, `otlp_http/loki`,
`otlp_http/tempo`, внутренние метрики на `:8888`, без расширений. Проверка: подкоманда `validate` бинарника Collector на
этом файле — без ошибок; в журнале старта нет `deprecated`.
- [ ] 6.2 `infra/otel/prometheus/prometheus.yml`, `infra/otel/loki/loki.yaml`, `infra/otel/tempo/tempo.yaml` (15). Проверка:
- [x] 6.2 `infra/otel/prometheus/prometheus.yml`, `infra/otel/loki/loki.yaml`, `infra/otel/tempo/tempo.yaml` (15). Проверка:
`promtool check config` в образе Prometheus; `-verify-config` Loki; Tempo стартует без ошибок; срок хранения 7 суток виден в
`/config` Loki и `/status/config` Tempo, `retention` — во флагах Prometheus (`/api/v1/status/flags`).
- [ ] 6.3 Grafana (16): `infra/otel/grafana/datasources.yaml`, `dashboards.yaml`, `dashboards/messenger-overview.json` —
- [x] 6.3 Grafana (16): `infra/otel/grafana/datasources.yaml`, `dashboards.yaml`, `dashboards/messenger-overview.json` —
источники с uid `prometheus`, `loki`, `tempo` и ссылками лог ↔ трасса, папка `Messenger`, панели уровня 3 из решения 16.
Проверка — шаги provisioning в 11.1 (источники, их проверка, dashboard provisioned, запросы панелей без ошибок и с данными).
- [ ] 6.4 `docker-compose.yml` (7, 8, 14–18): сервисы `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana` — образ с
- [x] 6.4 `docker-compose.yml` (7, 8, 14–18): сервисы `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana` — образ с
digest, команда, каждый конфиг — отдельный bind mount файла длинной записью (`read_only`, `create_host_path: false`),
volumes `prometheus_data`, `loki_data`, `tempo_data`, tmpfs Grafana, `GOMEMLIMIT`, лимиты решения 7, healthcheck решения
18, `restart: unless-stopped`; сеть `telemetry`; порт Grafana `127.0.0.1:${GRAFANA_OUT_PORT:-3000}`; `GF_*` решения 16;
якорь `x-telemetry-env` у `api` и `worker`; сервисы приложения без `depends_on` на телеметрию. Проверка: `docker compose
--env-file .env config --quiet`; сценарии `container-run` «Адрес публикации», «Секреты по сервисам», «Лимиты у всех
контейнеров» — `docker port`, `docker compose config`, `docker inspect` по всем контейнерам.
- [ ] 6.5 Healthcheck брокера через `gosu rabbitmq` (19). Проверка — 11.3 (`RestartCount` брокера 0 на пустом volume дважды).
- [ ] 6.6 Override CI (20): `.github/ci/compose.yml` — `configs` для семи новых файлов; у Prometheus, Loki и Tempo —
- [x] 6.5 Healthcheck брокера через `gosu rabbitmq` (19). Проверка — 11.3 (`RestartCount` брокера 0 на пустом volume дважды).
- [x] 6.6 Override CI (20): `.github/ci/compose.yml` — `configs` для семи новых файлов; у Prometheus, Loki и Tempo —
`volumes: !override` только с именованным volume (как у брокера), у Collector и Grafana — `volumes: !reset []` (tmpfs
Grafana остаётся); `ports: !reset []` у Grafana; `.github/ci/stand-env.sh` — переменные `CI_*` этих файлов. Проверка: с
`COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml` и `. .github/ci/stand-env.sh` — `docker compose config --quiet`, в
полном `config` у сервисов телеметрии нет bind mount и опубликованных портов.
- [ ] 6.7 Стенды без телеметрии (20): `TELEMETRY__ENABLED: "false"` у `api` и `worker` в `bench/bench.compose.yml` и
- [x] 6.7 Стенды без телеметрии (20): `TELEMETRY__ENABLED: "false"` у `api` и `worker` в `bench/bench.compose.yml` и
`student-tests/failures.compose.yml`; `GRAFANA_ADMIN_PASSWORD` в `compose_env` `bench/run.py`; `-e TELEMETRY__ENABLED=false`
у API и worker `student-tests/run_isolated.py`. Проверка: `make bench_quick` (рабочий стенд остановлен) проходит, в
`stand.app_env` паспорта — `TELEMETRY__ENABLED=false`; стенды отказов и временной базы — 11.5.
- [ ] 6.8 Поднять стенд: `make run_docker`; все сервисы работают, цели Prometheus `up` = 1, `/api/health` Grafana — 200, в
- [x] 6.8 Поднять стенд: `make run_docker`; все сервисы работают, цели Prometheus `up` = 1, `/api/health` Grafana — 200, в
журнале старта Grafana нет обращений к grafana.com, в журнале Collector, Loki и Tempo нет ошибок. Проверка: сценарий
«Стенд с телеметрией» (`observability`).
## 7. Драйвер скилла `run-mtusi-messenger`
- [ ] 7.1 `driver.py --port <LB> telemetry-check` (21): Grafana API с паролем из `.env` (вход: без учётных данных и с
- [x] 7.1 `driver.py --port <LB> telemetry-check` (21): Grafana API с паролем из `.env` (вход: без учётных данных и с
неверным паролем — 401, с верным — 200; источники по uid и их проверка; dashboard provisioned, сохранение изменённого
отклоняется; запросы панелей без ошибок); свой запрос → Loki → Tempo, ресурс, совпадение записи Loki со stdout реплики;
ответы 401 и 404 и запросы с `BREW`, путём с UUID и `traceparent`; загрузка → `ready` → лог и трасса worker; недекодируемый
@@ -127,12 +127,12 @@
пишет `warning` с именами; проба приватности (U, P, T, M, K, F, `Bearer `, `Basic `, запрещённые метки, UUID в значениях);
`docker compose restart` Collector и хранилищ → те же наблюдения снова. Таблица «шаг → ожидаемо → получено», коды 0 / 1 /
2, секретов в выводе нет; раздел в `SKILL.md`. Проверка — 11.1.
- [ ] 7.2 `driver.py --port <LB> telemetry-outage` (21): Collector `stop` → `make test`, загрузка до `ready`, записи SDK об
- [x] 7.2 `driver.py --port <LB> telemetry-outage` (21): Collector `stop` → `make test`, загрузка до `ready`, записи SDK об
отказе за минуту, `docker stop` одной реплики и `docker compose stop worker` (время, код, «Stopped API», «Stopped worker»),
`make replicas`, `docker compose start worker`; то же при `pause`; все сервисы телеметрии остановлены → реплики и worker
перезапущены → стартуют, `make test` — PASS; после возврата — сигналы приходят снова; восстановление в `finally`; раздел в
`SKILL.md`. Проверка — 11.2.
- [ ] 7.3 `driver.py stand-from-scratch [--runs 2]` (21): проект `mtusi-lab6-scratch` (`mtusi-lab6` — код 2), свободные порты
- [x] 7.3 `driver.py stand-from-scratch [--runs 2]` (21): проект `mtusi-lab6-scratch` (`mtusi-lab6` — код 2), свободные порты
хоста для `APP_OUT_PORT`, `POSTGRES_OUT_PORT`, `VALKEY_OUT_PORT`, `S3_OUT_PORT`, `RABBITMQ_OUT_PORT`, `GRAFANA_OUT_PORT`,
`make run_docker` с `COMPOSE_PROJECT_NAME`; код 0 с первой попытки, состояния сервисов, `RestartCount` брокера и хранилищ
телеметрии 0, нет `eacces` и `permission denied` в журналах, provisioning Grafana, `make test` через свой LB; затем свой
@@ -140,57 +140,57 @@
## 8. Быстрые тесты
- [ ] 8.1 `service-tests/unit/test_telemetry.py` на in-memory экспортёрах SDK, без сети: выключенная телеметрия — ни
- [x] 8.1 `service-tests/unit/test_telemetry.py` на in-memory экспортёрах SDK, без сети: выключенная телеметрия — ни
провайдеров, ни хуков, записи stdout прежние; `OTEL_*` удалены и названы в `warning` без значений; ресурс; middleware — имя,
атрибуты, `_OTHER`, health без span и метрики, 5xx — `ERROR` без текста исключения, `traceparent` не продолжен; запись
журнала — тело, уровень, атрибуты, `trace_id` и `span_id` в stdout, traceback записи `uvicorn.error` в экспорте, записи
`opentelemetry.*` не экспортируются и прорежены; правило корня; span Valkey и S3; закрытие с блокирующим экспортёром не
дольше срока. Проверка: `make service_test`.
- [ ] 8.2 Исход доставки → span `CONSUMER` и histogram с `messenger.job.outcome` для каждого исхода, включая `error`
- [x] 8.2 Исход доставки → span `CONSUMER` и histogram с `messenger.job.outcome` для каждого исхода, включая `error`
(`test_worker_deliveries.py` или новый модуль). Проверка: `make service_test`.
- [ ] 8.3 `service-tests/db/`: span запросов и `COMMIT` под родителем в асинхронной сессии на временной базе, без родителя —
- [x] 8.3 `service-tests/db/`: span запросов и `COMMIT` под родителем в асинхронной сессии на временной базе, без родителя —
ни одного span (проверка контекста greenlet). Проверка: `make service_test_db`.
## 9. Документы
- [ ] 9.1 Правила: `docker.md` (сервисы, сеть, healthcheck, суммы, секреты, брокер), `infra.md` (пакет телеметрии, span в
- [x] 9.1 Правила: `docker.md` (сервисы, сеть, healthcheck, суммы, секреты, брокер), `infra.md` (пакет телеметрии, span в
клиентах), `api-layer.md` (middleware), `logging.md` (экспорт и поля трассы, записи SDK), `settings.md` (`[telemetry]`,
`OTEL_*`), `run-modes.md` (консоль, остановка со сроком SDK), `worker.md` (consumer span, исход доставки), `bench.md` и
`student-tests.md` (телеметрия выключена, `GRAFANA_ADMIN_PASSWORD` для разбора compose). Проверка: в каждом правиле —
ссылка на design change и нет пересказа спека.
- [ ] 9.2 `AGENTS.md`: абзац о состоянии лабы, таблица важных файлов (`contracts/observability.md`, `infra/otel/`), карта кода
- [x] 9.2 `AGENTS.md`: абзац о состоянии лабы, таблица важных файлов (`contracts/observability.md`, `infra/otel/`), карта кода
(`src/infra/telemetry/`, `infra/otel/`, `evidence/telemetry/`, `evidence/stand/`), команды драйвера, число записей
`KNOWN_ISSUES.md`. Проверка: `grep` новых путей в `AGENTS.md`.
- [ ] 9.3 `REPORT.md` по требованию «Наблюдаемость в отчёте» (`observability`): назначение Collector и хранилищ, версии,
- [x] 9.3 `REPORT.md` по требованию «Наблюдаемость в отчёте» (`observability`): назначение Collector и хранилищ, версии,
таблица сигналов «контракт → SDK → Prometheus / Loki / Tempo → единица», запросы панелей, доля ошибок и исходы заданий,
соответствие ресурса меткам и `OTEL_*` настройкам, сумма лимитов и замер, ограничения; строки таблицы инфраструктуры для пяти
сервисов. Проверка: сценарий «Отчёт по наблюдаемости».
- [ ] 9.4 `QUESTIONS.md`, раздел `## otel-telemetry` — решения и вопросы apply; design — «Уточнения apply» с отклонениями от
- [x] 9.4 `QUESTIONS.md`, раздел `## otel-telemetry` — решения и вопросы apply; design — «Уточнения apply» с отклонениями от
решений. Проверка: каждое отклонение названо там.
## 10. Бюджет
- [ ] 10.1 Замер (7): `docker stats` и `memory.peak` сервисов телеметрии, реплики API и worker в простое и под `make test` +
- [x] 10.1 Замер (7): `docker stats` и `memory.peak` сервисов телеметрии, реплики API и worker в простое и под `make test` +
`make load` с включённой телеметрией и с выключенной (`TELEMETRY__ENABLED=false` у тех же контейнеров); лимит каждого
сервиса телеметрии — не меньше 1,5 × пика, иначе поднять и пересчитать суммы; реплика API в своём лимите. Проверка:
`evidence/telemetry/budget.md`, суммы в `docker.md` и `REPORT.md` совпадают с `docker inspect`.
## 11. Проверки на стенде
- [ ] 11.1 `driver.py --port 8080 telemetry-check` → код 0, вывод в `evidence/telemetry/check.md`. Проверка: сценарии
- [x] 11.1 `driver.py --port 8080 telemetry-check` → код 0, вывод в `evidence/telemetry/check.md`. Проверка: сценарии
`observability` (кроме отказов Collector), `service-logging` «Записи запроса ведут к трассе», «Записи задания ведут к
трассе», «Запись в Loki совпадает со stdout», `service-configuration` «Переменные OTEL_* не действуют».
- [ ] 11.2 `driver.py --port 8080 telemetry-outage` → код 0, вывод в `evidence/telemetry/collector-outage.md`. Проверка:
- [x] 11.2 `driver.py --port 8080 telemetry-outage` → код 0, вывод в `evidence/telemetry/collector-outage.md`. Проверка:
сценарии «Collector остановлен», «Collector заморожен», «Отказ отправки журнала», `container-run` «Приложение без
телеметрии», `graceful-shutdown` «docker stop при остановленном Collector» и «…при замороженном Collector».
- [ ] 11.3 `driver.py stand-from-scratch --runs 2` → код 0, вывод в `evidence/stand/from-scratch.md`; после него — удалить
- [x] 11.3 `driver.py stand-from-scratch --runs 2` → код 0, вывод в `evidence/stand/from-scratch.md`; после него — удалить
запись «Первый старт RabbitMQ…» из `KNOWN_ISSUES.md`. Проверка: сценарий «Стенд с нуля одной командой»; рабочий стенд —
прежние ID контейнеров.
- [ ] 11.4 Консоль: `make run_dev` и `make test` — PASS, запись о старте «телеметрия выключена», в записях нет `trace_id`, к
- [x] 11.4 Консоль: `make run_dev` и `make test` — PASS, запись о старте «телеметрия выключена», в записях нет `trace_id`, к
`127.0.0.1:4318` обращений нет. Проверка: сценарии «Консоль без телеметрии», «Телеметрия по умолчанию выключена».
- [ ] 11.5 Регрессия: `make lint`; `make service_test`; `make service_test_db`; `make test` и `make student_test` через LB
- [x] 11.5 Регрессия: `make lint`; `make service_test`; `make service_test_db`; `make test` и `make student_test` через LB
(красный только `test_exclusion_evidence_exists`); `make test-persistence ACTION_SCRIPT=scripts/restart.sh` — PASS и прежнее
`StartedAt` у сервисов телеметрии; `make test_isolated` и `make failure_checks` — прежние результаты, в «Started API» их API
телеметрия выключена; `docker compose config --quiet` — рабочий стенд, CI, `bench/`, стенд отказов. Проверка: выводы команд;
причины любых падений — в отчёте apply до правок.
- [ ] 11.6 `graphify update .` после закрытия задач. Проверка: в графе есть узлы `src/infra/telemetry`.
- [x] 11.6 `graphify update .` после закрытия задач. Проверка: в графе есть узлы `src/infra/telemetry`.
+8
View File
@@ -27,6 +27,14 @@ dependencies = [
"aio-pika>=10.2.1,<11",
# варианты в процессе обработки; импортирует только src/utils/image_variants.py
"pillow>=13,<14",
# телеметрия API и worker (design change otel-telemetry, решения 2 и 4):
# только SDK и экспортёр OTLP/HTTP, библиотек автоинструментирования нет.
# Узко в пределах 1.45.x: API логов Python (`opentelemetry._logs`,
# `opentelemetry.sdk._logs`) без стабильного имени, разбор записи журнала
# покрыт быстрым тестом
"opentelemetry-api>=1.45.2,<1.46",
"opentelemetry-sdk>=1.45.2,<1.46",
"opentelemetry-exporter-otlp-proto-http>=1.45.2,<1.46",
]
[project.optional-dependencies]
+131
View File
@@ -0,0 +1,131 @@
"""Span запросов PostgreSQL и фиксации на временной базе (design change
`otel-telemetry`, решения 4 и 12): слушатели engine видят контекст задачи в
greenlet асинхронной сессии, без записывающего родителя span нет."""
from collections.abc import Iterator
import pytest
from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
from opentelemetry.sdk.metrics.export import InMemoryMetricReader
from opentelemetry.sdk.trace import ReadableSpan
from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter,
)
from opentelemetry.trace import SpanKind, StatusCode
from sqlalchemy import text
from sqlalchemy.exc import DBAPIError
from builders import PASSWORD_HASH, user_dto
from conftest import make_engine, make_factory, make_uow, truncate_all
from src.config import settings
from src.infra import telemetry
from src.infra.telemetry import core
pytestmark = pytest.mark.anyio
@pytest.fixture
def spans() -> Iterator[InMemorySpanExporter]:
exporter = InMemorySpanExporter()
assert telemetry.start_process_telemetry(
"messenger-api",
exporters=telemetry.Exporters(
spans=exporter,
metrics=InMemoryMetricReader(),
logs=InMemoryLogRecordExporter(),
),
)
try:
yield exporter
finally:
for thread in telemetry.begin_shutdown():
thread.join(5)
telemetry.remove_log_hooks()
def _finished(exporter: InMemorySpanExporter) -> list[ReadableSpan]:
for thread in telemetry.begin_shutdown():
thread.join(5)
return list(exporter.get_finished_spans())
@pytest.fixture
async def engine(spans: InMemorySpanExporter):
await truncate_all()
created = make_engine(pool_size=1)
telemetry.instrument_engine(created)
yield created
await created.dispose()
async def test_queries_and_commit_under_parent(
spans: InMemorySpanExporter,
engine,
) -> None:
uow = make_uow(make_factory(engine))
user = user_dto()
with core.tracer().start_as_current_span("parent") as parent:
async with uow:
await uow.users.insert_user(user=user, password_hash=PASSWORD_HASH)
await uow.commit()
async with uow:
await uow.users.get_user_credentials(username=user.username)
finished = _finished(spans)
parent_id = parent.get_span_context().span_id
children = [span for span in finished if span.name != "parent"]
names = [span.name for span in children]
assert "INSERT" in names
assert "COMMIT" in names
assert "SELECT" in names
for span in children:
assert span.parent is not None
assert span.parent.span_id == parent_id
assert span.kind == SpanKind.CLIENT
assert span.attributes["db.system.name"] == "postgresql"
insert = next(span for span in children if span.name == "INSERT")
assert insert.attributes["db.namespace"] == settings.database.name
assert insert.attributes["db.operation.name"] == "INSERT"
assert insert.attributes["server.port"] == settings.database.port
# параметризованный SQL: ни имени пользователя, ни хэша пароля
query = insert.attributes["db.query.text"]
assert user.username not in query
assert PASSWORD_HASH not in query
# запрос закончился раньше фиксации, оба — внутри родителя
commit = next(span for span in children if span.name == "COMMIT")
assert insert.end_time <= commit.start_time
async def test_no_spans_without_parent(
spans: InMemorySpanExporter,
engine,
) -> None:
uow = make_uow(make_factory(engine))
async with uow:
await uow.users.get_user_credentials(username="nobody_here")
async with engine.connect() as connection:
await connection.execute(text("SELECT 1"))
assert _finished(spans) == []
async def test_failed_query_marks_error(
spans: InMemorySpanExporter,
engine,
) -> None:
uow = make_uow(make_factory(engine))
with (
core.tracer().start_as_current_span("parent"),
pytest.raises(DBAPIError),
):
async with uow:
await uow._current_session().execute(
text("SELECT 1 / 0 AS secret_marker"),
)
(failed,) = [
span
for span in _finished(spans)
if span.status.status_code == StatusCode.ERROR
]
assert failed.name == "SELECT"
assert failed.attributes["error.type"]
assert failed.status.description is None
assert failed.events == ()
@@ -27,6 +27,7 @@ from src.schemas.enums import (
AttachmentJobState,
AttachmentStatus,
AttachmentVariantName,
JobDeliveryOutcome,
JobOutcome,
)
from src.schemas.jobs import build_job_body
@@ -34,6 +35,8 @@ from src.utils.utc import utcnow
pytestmark = pytest.mark.anyio
Outcome = JobDeliveryOutcome
SOURCE = b"source-bytes"
@@ -102,10 +105,27 @@ def _body(job: dataclasses.AttachmentJobDTO) -> bytes:
async def _handle(
service: AttachmentProcessingService,
job: dataclasses.AttachmentJobDTO,
) -> JobOutcome:
) -> JobDeliveryOutcome:
return await service.handle(body=_body(job), redelivered=False)
@pytest.mark.parametrize(
("outcome", "action"),
[
(Outcome.READY, JobOutcome.ACK),
(Outcome.FAILED, JobOutcome.ACK),
(Outcome.RETRY, JobOutcome.ACK),
(Outcome.SKIPPED, JobOutcome.ACK),
(Outcome.REQUEUED, JobOutcome.REQUEUE),
(Outcome.DROPPED, JobOutcome.DROP),
(Outcome.ERROR, JobOutcome.REQUEUE),
],
)
def test_outcome_action(outcome: Outcome, action: JobOutcome) -> None:
"""Исход доставки → действие с сообщением: прежние ack, requeue, drop."""
assert outcome.action == action
def _set_job(database: FakeDatabase, job_id: UUID, **fields) -> None:
database.jobs[job_id] = replace(database.jobs[job_id], **fields)
@@ -117,7 +137,7 @@ async def test_success_commits_ready_with_variants(
queued: dataclasses.AttachmentJobDTO,
) -> None:
outcome = await _handle(service, queued)
assert outcome == JobOutcome.ACK
assert outcome == Outcome.READY
row = database.attachments[queued.attachment_id]
job = database.jobs[queued.id]
assert row.status == AttachmentStatus.READY
@@ -167,7 +187,7 @@ async def test_malformed_message_dropped(
database: FakeDatabase,
) -> None:
outcome = await service.handle(body=b"not json", redelivered=False)
assert outcome == JobOutcome.DROP
assert outcome == Outcome.DROPPED
assert database.events == []
@@ -177,7 +197,7 @@ async def test_unknown_job_acked_without_attempt(
queued: dataclasses.AttachmentJobDTO,
) -> None:
other = replace(queued, id=uuid4())
assert await _handle(service, other) == JobOutcome.ACK
assert await _handle(service, other) == Outcome.SKIPPED
assert database.jobs[queued.id].attempt == 0
@@ -187,7 +207,7 @@ async def test_foreign_attachment_acked_without_attempt(
queued: dataclasses.AttachmentJobDTO,
) -> None:
other = replace(queued, attachment_id=uuid4())
assert await _handle(service, other) == JobOutcome.ACK
assert await _handle(service, other) == Outcome.SKIPPED
assert database.jobs[queued.id].attempt == 0
@@ -199,12 +219,12 @@ async def test_finished_jobs_acked_without_write(
await _handle(service, queued)
database.events.clear()
# повторная доставка завершённого
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.SKIPPED
assert database.jobs[queued.id].attempt == 1
assert "commit" not in database.events
_set_job(database, queued.id, state=AttachmentJobState.FAILED)
database.events.clear()
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.SKIPPED
assert "commit" not in database.events
@@ -218,7 +238,7 @@ async def test_not_due_acked_without_attempt(
queued.id,
next_attempt_at=utcnow() + timedelta(seconds=30),
)
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.SKIPPED
assert database.jobs[queued.id].attempt == 0
@@ -250,7 +270,7 @@ async def test_live_lease_acked_without_attempt(
attempt=1,
lease_expires_at=utcnow() + timedelta(seconds=30),
)
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.SKIPPED
assert database.jobs[queued.id].attempt == 1
assert "renderer.render" not in database.events
@@ -280,7 +300,7 @@ async def test_budget_spent_fails_without_attempt(
) -> None:
attempts = settings.worker.max_attempts
_set_job(database, queued.id, attempt=attempts)
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.FAILED
job = database.jobs[queued.id]
row = database.attachments[queued.attachment_id]
assert job.state == AttachmentJobState.FAILED
@@ -333,7 +353,7 @@ async def test_permanent_error_fails_at_once(
database.fail_on["renderer.render"] = exceptions.ImageRejected(
reason=AttachmentJobReason.UNDECODABLE,
)
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.FAILED
row = database.attachments[queued.attachment_id]
job = database.jobs[queued.id]
assert row.status == AttachmentStatus.FAILED
@@ -365,7 +385,7 @@ async def test_damaged_source_fails_at_once(
storage.seed(key, b"other size bytes!")
else:
storage.seed(key, b"X" * len(SOURCE))
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.FAILED
row = database.attachments[queued.attachment_id]
assert row.status == AttachmentStatus.FAILED
assert row.error_code == AttachmentErrorCode.PROCESSING_FAILED
@@ -410,7 +430,7 @@ async def test_temporary_error_returns_to_queue(
) -> None:
database.fail_on[event] = failure
before = utcnow()
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.RETRY
job = database.jobs[queued.id]
row = database.attachments[queued.attachment_id]
assert job.state == AttachmentJobState.QUEUED
@@ -428,7 +448,7 @@ async def test_temporary_error_after_budget_is_failed(
) -> None:
_set_job(database, queued.id, attempt=settings.worker.max_attempts - 1)
database.fail_on["storage.get"] = exceptions.ObjectStorageUnavailable()
assert await _handle(service, queued) == JobOutcome.ACK
assert await _handle(service, queued) == Outcome.FAILED
row = database.attachments[queued.attachment_id]
assert row.error_code == AttachmentErrorCode.RETRY_EXHAUSTED
assert database.jobs[queued.id].state == AttachmentJobState.FAILED
@@ -441,7 +461,7 @@ async def _with_supersede(
queued: dataclasses.AttachmentJobDTO,
*,
failure: BaseException | None = None,
) -> tuple[JobOutcome, dataclasses.AttachmentJobDTO]:
) -> tuple[JobDeliveryOutcome, dataclasses.AttachmentJobDTO]:
"""Пока попытка работает, задание взяла следующая попытка."""
async def render(data: bytes) -> dataclasses.RenderedVariantsDTO:
@@ -463,7 +483,7 @@ async def test_superseded_on_ready_no_effect(
queued: dataclasses.AttachmentJobDTO,
) -> None:
outcome, job = await _with_supersede(service, database, renderer, queued)
assert outcome == JobOutcome.ACK
assert outcome == Outcome.SKIPPED
assert job.state == AttachmentJobState.PROCESSING
assert database.attachments[queued.attachment_id].status == (
AttachmentStatus.PROCESSING
@@ -486,7 +506,7 @@ async def test_superseded_on_failed_no_effect(
reason=AttachmentJobReason.UNDECODABLE,
),
)
assert outcome == JobOutcome.ACK
assert outcome == Outcome.SKIPPED
assert job.state == AttachmentJobState.PROCESSING
assert database.attachments[queued.attachment_id].error_code is None
@@ -506,7 +526,7 @@ async def test_superseded_on_return_no_effect(
reason=AttachmentJobReason.RENDER_KILLED,
),
)
assert outcome == JobOutcome.ACK
assert outcome == Outcome.SKIPPED
assert job.state == AttachmentJobState.PROCESSING
assert database.attachments[queued.attachment_id].status == (
AttachmentStatus.PROCESSING
@@ -519,7 +539,7 @@ async def test_database_failure_requeues_and_pauses(
queued: dataclasses.AttachmentJobDTO,
) -> None:
database.fail_on["jobs.lock_job"] = exceptions.ServiceUnavailable()
assert await _handle(service, queued) == JobOutcome.REQUEUE
assert await _handle(service, queued) == Outcome.REQUEUED
assert database.jobs[queued.id].attempt == 0
@@ -537,7 +557,7 @@ async def test_stop_interrupts_pause(
service = AttachmentProcessingService(uow, storage, renderer, stop)
database.fail_on["jobs.lock_job"] = exceptions.ServiceUnavailable()
async with asyncio.timeout(1):
assert await _handle(service, queued) == JobOutcome.REQUEUE
assert await _handle(service, queued) == Outcome.REQUEUED
def test_retry_delay_bounds() -> None:
+673
View File
@@ -0,0 +1,673 @@
"""Телеметрия на in-memory экспортёрах SDK, без сети (design change
`otel-telemetry`, решение 21): выключенная телеметрия, `OTEL_*`, ресурс,
server span и метрика HTTP, запись журнала, правило корня, span Valkey и S3,
закрытие со сроком, исход доставки worker → span и histogram."""
import asyncio
import io
import json
import logging
import time
from collections.abc import Iterator
from dataclasses import dataclass, field
from typing import Any
import httpx
import pytest
from botocore.exceptions import ClientError
from fastapi import APIRouter, FastAPI
from opentelemetry import trace
from opentelemetry._logs import SeverityNumber
from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
from opentelemetry.sdk.metrics.export import InMemoryMetricReader
from opentelemetry.sdk.trace import ReadableSpan
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter,
)
from opentelemetry.trace import SpanKind, StatusCode
from redis.exceptions import RedisError
from src.api.middlewares import RequestContextMiddleware
from src.config import settings
from src.infra import logger as app_logger
from src.infra import telemetry
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.utils.constants import (
ATTACHMENT_JOB_TYPE,
METRIC_HTTP_SERVER_DURATION,
METRIC_JOB_DURATION,
SERVICE_VERSION,
)
from src.worker import main as worker_main
pytestmark = pytest.mark.anyio
SERVICE = "messenger-api"
SECRET_TEXT = "secret-text-in-exception"
@dataclass
class Signals:
spans: InMemorySpanExporter
metrics: InMemoryMetricReader
logs: InMemoryLogRecordExporter
closed: bool = False
def finish(self) -> None:
"""Закрыть провайдеры: батчи отправлены в in-memory экспортёры."""
if self.closed:
return
self.closed = True
for thread in telemetry.begin_shutdown():
thread.join(5)
def finished_spans(self) -> list[ReadableSpan]:
self.finish()
return list(self.spans.get_finished_spans())
def finished_logs(self) -> list[Any]:
self.finish()
return [item.log_record for item in self.logs.get_finished_logs()]
def points(self, name: str) -> list[Any]:
data = self.metrics.get_metrics_data()
if data is None:
return []
return [
point
for resource in data.resource_metrics
for scope in resource.scope_metrics
for metric in scope.metrics
if metric.name == name
for point in metric.data.data_points
]
@pytest.fixture
def stdout() -> Iterator[io.StringIO]:
"""Вывод handler журнала (он пишет в sys.stdout, взятый при настройке)."""
get_logger()
handler = logging.getLogger("src").handlers[0]
buffer = io.StringIO()
previous = handler.setStream(buffer)
try:
yield buffer
finally:
handler.setStream(previous)
@pytest.fixture
def signals(monkeypatch: pytest.MonkeyPatch) -> Iterator[Signals]:
monkeypatch.setattr(settings.telemetry, "environment", "lab")
collected = Signals(
spans=InMemorySpanExporter(),
metrics=InMemoryMetricReader(),
logs=InMemoryLogRecordExporter(),
)
started = telemetry.start_process_telemetry(
SERVICE,
exporters=telemetry.Exporters(
spans=collected.spans,
metrics=collected.metrics,
logs=collected.logs,
),
)
assert started
try:
yield collected
finally:
collected.finish()
telemetry.remove_log_hooks()
def _records(buffer: io.StringIO) -> list[dict[str, Any]]:
return [json.loads(line) for line in buffer.getvalue().splitlines()]
# --- выключенная телеметрия ---------------------------------------------
def test_disabled_has_no_providers_and_hooks(
monkeypatch: pytest.MonkeyPatch,
stdout: io.StringIO,
) -> None:
monkeypatch.setattr(settings.telemetry, "enabled", False)
monkeypatch.setenv("OTEL_SDK_DISABLED", "true")
assert telemetry.start_process_telemetry(SERVICE) is False
assert not telemetry.is_enabled()
assert app_logger._export_hook is None
assert app_logger._trace_fields_hook is None
# выключенная телеметрия окружение не трогает
assert "OTEL_SDK_DISABLED" in __import__("os").environ
with telemetry.child_span("GET") as span:
assert span is None
get_logger().info("Plain record", answer=42)
(record,) = _records(stdout)
assert "trace_id" not in record
assert "span_id" not in record
assert record["event"] == "Plain record"
assert record["answer"] == 42
def test_disabled_record_fields_unchanged(stdout: io.StringIO) -> None:
"""Поля записи без телеметрии — прежние: полей трассы нет."""
get_logger().bind(module="probe").info("Plain record", value=1)
(record,) = _records(stdout)
assert list(record)[:2] == ["event", "instance_id"]
assert set(record) == {
"event",
"instance_id",
"module",
"value",
"level",
"timestamp",
"filename",
"func_name",
"lineno",
}
# --- запуск, OTEL_*, ресурс ----------------------------------------------
def test_otel_environment_removed_and_named(
monkeypatch: pytest.MonkeyPatch,
stdout: io.StringIO,
) -> None:
monkeypatch.setenv("OTEL_SDK_DISABLED", "true")
monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://elsewhere:9")
collected = Signals(
spans=InMemorySpanExporter(),
metrics=InMemoryMetricReader(),
logs=InMemoryLogRecordExporter(),
)
try:
telemetry.start_process_telemetry(
SERVICE,
exporters=telemetry.Exporters(
spans=collected.spans,
metrics=collected.metrics,
logs=collected.logs,
),
)
import os
assert "OTEL_SDK_DISABLED" not in os.environ
assert "OTEL_EXPORTER_OTLP_ENDPOINT" not in os.environ
# SDK не выключен переменной: span пишется
with core.tracer().start_as_current_span("probe"):
pass
assert [span.name for span in collected.finished_spans()] == ["probe"]
finally:
collected.finish()
telemetry.remove_log_hooks()
output = stdout.getvalue()
assert "elsewhere" not in output
(warning,) = [
record
for record in _records(stdout)
if record["event"] == "Ignored OpenTelemetry environment variables"
]
assert warning["level"] == "warning"
assert warning["names"] == [
"OTEL_EXPORTER_OTLP_ENDPOINT",
"OTEL_SDK_DISABLED",
]
def test_resource_has_four_attributes(signals: Signals) -> None:
with core.tracer().start_as_current_span("probe"):
pass
(span,) = signals.finished_spans()
assert dict(span.resource.attributes) == {
"service.name": SERVICE,
"service.version": SERVICE_VERSION,
"service.instance.id": "test-instance",
"deployment.environment.name": "lab",
}
# --- server span и метрика HTTP -------------------------------------------
def _app() -> FastAPI:
app = FastAPI()
v1 = APIRouter(prefix="/api/v1")
items = APIRouter(prefix="/items")
@items.get("/{item_id}")
async def get_item(item_id: str) -> dict[str, str]:
get_logger().info("Inside handler")
return {"id": item_id}
@items.get("/{item_id}/boom")
async def boom(item_id: str) -> None:
raise RuntimeError(SECRET_TEXT)
@app.get("/health/live")
async def live() -> dict[str, str]:
return {"status": "ok"}
v1.include_router(items)
app.include_router(v1)
app.add_middleware(RequestContextMiddleware)
return app
async def _request(
method: str,
path: str,
headers: dict[str, str] | None = None,
) -> httpx.Response:
transport = httpx.ASGITransport(app=_app(), raise_app_exceptions=False)
async with httpx.AsyncClient(
transport=transport,
base_url="http://test",
) as client:
return await client.request(method, path, headers=headers)
async def test_server_span_and_metric(
signals: Signals,
stdout: io.StringIO,
) -> None:
response = await _request("GET", "/api/v1/items/abc")
assert response.status_code == 200
request_id = response.headers["x-request-id"]
points = signals.points(METRIC_HTTP_SERVER_DURATION)
(span,) = signals.finished_spans()
assert span.name == "GET /api/v1/items/{item_id}"
assert span.kind == SpanKind.SERVER
assert span.parent is None
assert dict(span.attributes) == {
"http.request.method": "GET",
"http.route": "/api/v1/items/{item_id}",
"http.response.status_code": 200,
"messenger.request_id": request_id,
}
(point,) = points
assert dict(point.attributes) == {
"http.request.method": "GET",
"http.route": "/api/v1/items/{item_id}",
"http.response.status_code": 200,
}
assert point.count == 1
# записи запроса, включая итоговую, — с trace_id и span_id этого span
trace_id = format(span.context.trace_id, "032x")
span_id = format(span.context.span_id, "016x")
records = [r for r in _records(stdout) if r.get("request_id")]
assert {r["event"] for r in records} == {
"Inside handler",
"HTTP request completed",
}
for record in records:
assert record["trace_id"] == trace_id
assert record["span_id"] == span_id
async def test_unknown_method_and_path(signals: Signals) -> None:
uuid_path = "/nope/6f1c2d3e-0000-4000-8000-000000000000"
await _request("BREW", uuid_path)
points = signals.points(METRIC_HTTP_SERVER_DURATION)
spans = signals.finished_spans()
(span,) = spans
assert span.name == "_OTHER"
assert "http.route" not in span.attributes
assert span.attributes["http.request.method"] == "_OTHER"
(point,) = points
assert "http.route" not in point.attributes
values = " ".join(str(value) for value in point.attributes.values())
assert "BREW" not in values
assert "6f1c2d3e" not in values
async def test_health_has_no_span_and_metric(signals: Signals) -> None:
response = await _request("GET", "/health/live")
assert response.status_code == 200
assert signals.points(METRIC_HTTP_SERVER_DURATION) == []
assert signals.finished_spans() == []
async def test_5xx_marks_error_without_text(signals: Signals) -> None:
response = await _request("GET", "/api/v1/items/x/boom")
assert response.status_code == 500
(span,) = signals.finished_spans()
assert span.status.status_code == StatusCode.ERROR
assert span.attributes["error.type"] == "RuntimeError"
assert span.attributes["http.response.status_code"] == 500
assert span.events == ()
dumped = json.dumps(
{
"attributes": dict(span.attributes),
"status": span.status.description,
},
)
assert SECRET_TEXT not in dumped
async def test_incoming_traceparent_is_not_continued(
signals: Signals,
) -> None:
foreign = "0af7651916cd43dd8448eb211c80319c"
await _request(
"GET",
"/api/v1/items/abc",
headers={"traceparent": f"00-{foreign}-b7ad6b7169203331-01"},
)
(span,) = signals.finished_spans()
assert span.parent is None
assert format(span.context.trace_id, "032x") != foreign
# --- журнал ---------------------------------------------------------------
def test_log_record_export(signals: Signals, stdout: io.StringIO) -> None:
log = get_logger().bind(module="probe")
with core.tracer().start_as_current_span("parent") as parent:
log.info(
"Exported record",
count=3,
ratio=0.5,
flag=True,
nothing=None,
variants=[{"name": "thumbnail", "width": 10}],
)
log.warning("Outside span")
exported = signals.finished_logs()
inside, outside = exported
assert inside.body == "Exported record"
assert inside.severity_number == SeverityNumber.INFO
assert inside.severity_text == "info"
assert inside.trace_id == parent.get_span_context().trace_id
assert inside.span_id == parent.get_span_context().span_id
attributes = dict(inside.attributes)
assert attributes["count"] == 3
assert attributes["ratio"] == 0.5
assert attributes["flag"] is True
assert "nothing" not in attributes
assert json.loads(attributes["variants"]) == [
{"name": "thumbnail", "width": 10},
]
assert attributes["module"] == "probe"
assert attributes["instance_id"] == "test-instance"
assert "event" not in attributes
assert "trace_id" not in attributes
assert outside.severity_number == SeverityNumber.WARN
assert not outside.trace_id
first, second = _records(stdout)
assert first["trace_id"] == format(
parent.get_span_context().trace_id,
"032x",
)
assert len(first["span_id"]) == 16
assert "trace_id" not in second
def test_uvicorn_traceback_is_exported(signals: Signals) -> None:
try:
raise ValueError("boom")
except ValueError as e:
logging.getLogger("uvicorn.error").error(
"Exception in ASGI application",
exc_info=e,
)
(record,) = signals.finished_logs()
assert record.body == "Exception in ASGI application"
assert record.severity_number == SeverityNumber.ERROR
assert "Traceback" in record.attributes["exception"]
assert record.attributes["logger"] == "uvicorn.error"
def test_sdk_records_not_exported_and_thinned(
signals: Signals,
stdout: io.StringIO,
) -> None:
sdk = logging.getLogger("opentelemetry.probe.thinned")
for _ in range(5):
sdk.warning("Failed to export batch")
assert signals.finished_logs() == []
records = [r for r in _records(stdout) if r.get("logger") == sdk.name]
assert len(records) == 1
# --- правило корня и клиенты ----------------------------------------------
def test_child_span_needs_recording_parent(signals: Signals) -> None:
with telemetry.child_span("SELECT") as orphan:
assert orphan is None
with (
core.tracer().start_as_current_span("parent") as parent,
telemetry.child_span("SELECT") as child,
):
assert child is not None
spans = {span.name: span for span in signals.finished_spans()}
assert set(spans) == {"parent", "SELECT"}
assert spans["SELECT"].parent.span_id == (
parent.get_span_context().span_id
)
def test_child_span_error_has_class_only(signals: Signals) -> None:
with (
core.tracer().start_as_current_span("parent"),
pytest.raises(RuntimeError),
telemetry.child_span("GET"),
):
raise RuntimeError(SECRET_TEXT)
spans = {span.name: span for span in signals.finished_spans()}
child = spans["GET"]
assert child.status.status_code == StatusCode.ERROR
assert child.attributes["error.type"] == "RuntimeError"
assert child.events == ()
class _Redis:
def __init__(self, values: dict[str, str], fail: bool = False) -> None:
self.values = values
self.fail = fail
async def get(self, key: str) -> str | None:
if self.fail:
raise RedisError("down")
return self.values.get(key)
async def set(self, key: str, value: str, *, ex: int) -> None:
if self.fail:
raise RedisError("down")
self.values[key] = value
async def test_cache_spans(signals: Signals) -> None:
cache = Cache(
_Redis({"k": "v"}),
namespace="db",
timeout_seconds=1,
retry_after_seconds=60,
)
await cache.get("k") # без родителя — span нет
with core.tracer().start_as_current_span("parent"):
await cache.get("k")
await cache.get("absent-chat-key")
await cache.set("k2", "v2", ttl_seconds=10)
cache._client.fail = True
await cache.get("k")
await cache.get("k") # окно пропуска
spans = [s for s in signals.finished_spans() if s.name != "parent"]
results = [(s.name, s.attributes["messenger.cache.result"]) for s in spans]
assert results == [
("GET", "hit"),
("GET", "miss"),
("SET", "stored"),
("GET", "error"),
("GET", "skipped"),
]
assert spans[3].status.status_code == StatusCode.ERROR
for span in spans:
assert span.attributes["db.system.name"] == "valkey"
assert "absent-chat-key" not in json.dumps(dict(span.attributes))
class _S3Client:
async def put_object(self, **params: Any) -> dict[str, Any]:
return {}
async def head_object(self, **params: Any) -> dict[str, Any]:
raise ClientError(
{"Error": {"Code": "404"}, "ResponseMetadata": {}},
"HeadObject",
)
async def test_s3_spans_without_key(
signals: Signals,
monkeypatch: pytest.MonkeyPatch,
) -> None:
storage = ObjectStorage(settings.s3, namespace="db")
async def client() -> _S3Client:
return _S3Client()
monkeypatch.setattr(storage, "_get_client", client)
key = "db/attachments/6f1c2d3e-0000-4000-8000-000000000000/original"
with core.tracer().start_as_current_span("parent"):
await storage.put(key, io.BytesIO(b"abc"), size=3, content_type="x")
assert await storage.head(key) is None
spans = {s.name: s for s in signals.finished_spans()}
put = spans["S3.PutObject"]
head = spans["S3.HeadObject"]
assert put.attributes["rpc.method"] == "PutObject"
assert put.attributes["messenger.object.size"] == 3
assert put.attributes["messenger.s3.result"] == "ok"
assert head.attributes["messenger.s3.result"] == "missing"
assert head.status.status_code == StatusCode.UNSET
for span in (put, head):
assert "6f1c2d3e" not in json.dumps(dict(span.attributes))
# --- закрытие -------------------------------------------------------------
class _BlockingExporter(SpanExporter):
def export(self, spans: Any) -> SpanExportResult:
time.sleep(5)
return SpanExportResult.SUCCESS
def shutdown(self) -> None:
time.sleep(5)
async def test_shutdown_is_bounded() -> None:
telemetry.start_process_telemetry(
SERVICE,
exporters=telemetry.Exporters(
spans=_BlockingExporter(),
metrics=InMemoryMetricReader(),
logs=InMemoryLogRecordExporter(),
),
)
try:
with core.tracer().start_as_current_span("queued"):
pass
started = time.monotonic()
await telemetry.shutdown(timeout=0.3)
assert time.monotonic() - started < 1
assert not telemetry.is_enabled()
finally:
telemetry.remove_log_hooks()
# --- исход доставки worker ------------------------------------------------
@dataclass
class _Delivery:
body: bytes = b"{}"
redelivered: bool = False
settled: list[str] = field(default_factory=list)
async def ack(self) -> None:
self.settled.append("ack")
async def drop(self) -> None:
self.settled.append("drop")
async def requeue(self) -> None:
self.settled.append("requeue")
class _Service:
def __init__(self, outcome: JobDeliveryOutcome | None) -> None:
self.outcome = outcome
async def handle(self, *, body: bytes, redelivered: bool) -> Any:
if self.outcome is None:
raise RuntimeError(SECRET_TEXT)
return self.outcome
@pytest.mark.parametrize(
("outcome", "settled"),
[
(JobDeliveryOutcome.READY, "ack"),
(JobDeliveryOutcome.FAILED, "ack"),
(JobDeliveryOutcome.RETRY, "ack"),
(JobDeliveryOutcome.SKIPPED, "ack"),
(JobDeliveryOutcome.REQUEUED, "requeue"),
(JobDeliveryOutcome.DROPPED, "drop"),
(None, "requeue"),
],
ids=lambda value: getattr(value, "value", value or "error"),
)
async def test_delivery_outcome_span_and_histogram(
signals: Signals,
outcome: JobDeliveryOutcome | None,
settled: str,
) -> None:
delivery = _Delivery()
await worker_main._handle(
lambda: _Service(outcome),
delivery,
asyncio.Semaphore(1),
asyncio.Event(),
)
expected = "error" if outcome is None else outcome.value
assert delivery.settled == [settled]
(point,) = signals.points(METRIC_JOB_DURATION)
assert dict(point.attributes) == {
"messenger.job.type": ATTACHMENT_JOB_TYPE,
"messenger.job.outcome": expected,
}
assert point.count == 1
(span,) = signals.finished_spans()
assert span.kind == SpanKind.CONSUMER
assert span.name.startswith("process ")
assert span.name.endswith(".attachment.process.v1")
assert span.parent is None
assert span.attributes["messenger.job.outcome"] == expected
assert span.attributes["messaging.system"] == "rabbitmq"
assert span.attributes["messaging.operation.type"] == "process"
if outcome is None:
assert span.status.status_code == StatusCode.ERROR
assert span.attributes["error.type"] == "RuntimeError"
assert SECRET_TEXT not in json.dumps(dict(span.attributes))
else:
assert span.status.status_code == StatusCode.UNSET
async def test_delivery_without_telemetry_has_no_signals() -> None:
delivery = _Delivery()
await worker_main._handle(
lambda: _Service(JobDeliveryOutcome.READY),
delivery,
asyncio.Semaphore(1),
asyncio.Event(),
)
assert delivery.settled == ["ack"]
assert not trace.get_current_span().is_recording()
+31 -12
View File
@@ -1,7 +1,9 @@
"""Request id, instance id и итоговая запись о запросе — чистое ASGI-middleware.
Без `BaseHTTPMiddleware`: тот на каждый запрос создаёт отдельную задачу и
поток памяти для тела ответа (design, решение 7).
поток памяти для тела ответа (design, решение 7). С лабы 6 здесь же server span
и histogram `http.server.request.duration` (design change `otel-telemetry`,
решение 10): шаблон пути решён здесь, health исключён тем же списком.
"""
import time
@@ -12,6 +14,7 @@ from fastapi.routing import iter_route_contexts
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from src.config import settings
from src.infra import telemetry
from src.infra.logger import AbstractLogger, get_logger, http_request_id
from src.utils.constants import (
HEALTH_PATHS,
@@ -84,23 +87,39 @@ class RequestContextMiddleware:
message = {**message, "headers": headers}
await send(message)
try:
if scope["path"] in HEALTH_PATHS:
# ни записи, ни span, ни метрики: проверки LB раз в секунду
await self.app(scope, receive, send_with_ids)
finally:
if scope["path"] not in HEALTH_PATHS:
return
# server span — корень трассы (входящий traceparent не продолжается),
# итоговая запись пишется внутри него и получает trace_id
with telemetry.server_span() as span:
error: BaseException | None = None
try:
await self.app(scope, receive, send_with_ids)
except BaseException as e:
error = e
raise
finally:
# шаблон пути, а не фактический: id в пути не попадают в лог
if self._route_templates is None:
self._route_templates = _route_templates(scope["app"])
route = self._route_templates.get(id(scope.get("route")))
duration = time.perf_counter() - started
telemetry.finish_request(
span,
method=scope["method"],
route=route,
status_code=status_code,
request_id=request_id,
duration_seconds=duration,
error=error,
)
logger.info(
"HTTP request completed",
method=scope["method"],
path=self._route_templates.get(
id(scope.get("route")),
_UNMATCHED_PATH,
),
path=route if route is not None else _UNMATCHED_PATH,
status=status_code,
duration_ms=round(
(time.perf_counter() - started) * 1000,
3,
),
duration_ms=round(duration * 1000, 3),
)
+76
View File
@@ -2,6 +2,7 @@ import re
import socket
from pathlib import Path
from typing import Annotated, Literal
from urllib.parse import urlsplit
from pydantic import (
BaseModel,
@@ -445,6 +446,80 @@ class Relay(BaseModel):
)
class Telemetry(BaseModel):
"""Телеметрия API и worker (design change `otel-telemetry`, решение 8).
Включает её стенд compose окружением `TELEMETRY__ENABLED` и
`TELEMETRY__OTLP_ENDPOINT` у реплик API и worker; интервалы и очереди — из
`config.toml`. Переменные `OTEL_*` настройками не являются: SDK собирается
только из этих полей. Relay, уборщик и миграции секцию не читают.
"""
# выключена — ни провайдеров SDK, ни отправки, ни полей трассы в журнале
enabled: bool = False
# адрес OTLP/HTTP Collector: схема, хост и порт, без пути и query
otlp_endpoint: str = "http://127.0.0.1:4318"
# deployment.environment.name ресурса
environment: str = Field(default="lab", pattern=r"^[a-z0-9._-]{1,32}$")
# секунды между отправками метрик
metric_export_interval_seconds: float = Field(
default=15,
gt=0,
allow_inf_nan=False,
)
# секунды на одну отправку пакета экспортёром
export_timeout_seconds: float = Field(
default=2,
gt=0,
allow_inf_nan=False,
)
# span и записей журнала в очереди процессора; сверх — теряются
max_queue_size: int = Field(default=2048, ge=1)
# span и записей журнала в одной отправке; не больше очереди
max_export_batch_size: int = Field(default=512, ge=1)
# секунды паузы процессора между пакетами
schedule_delay_seconds: float = Field(
default=1,
gt=0,
allow_inf_nan=False,
)
@field_validator("otlp_endpoint")
@classmethod
def endpoint_without_path(cls, value: str) -> str:
"""Схема `http` или `https`, хост и порт; путь сигнала добавляет
код (`/v1/traces` и др.)."""
parsed = urlsplit(value)
try:
port = parsed.port
except ValueError:
port = None
if (
parsed.scheme not in {"http", "https"}
or not parsed.hostname
or port is None
or parsed.path not in {"", "/"}
or parsed.query
or parsed.fragment
or parsed.username is not None
or parsed.password is not None
):
raise ValueError(
"must be http(s)://host:port without path, query or "
"credentials",
)
return f"{parsed.scheme}://{parsed.netloc}"
@field_validator("max_export_batch_size")
@classmethod
def batch_not_above_queue(cls, value: int, info: ValidationInfo) -> int:
"""Пакет больше очереди не собрать."""
queue = info.data.get("max_queue_size")
if queue is not None and value > queue:
raise ValueError("must not be greater than max_queue_size")
return value
class Settings(BaseSettings):
model_config = SettingsConfigDict(
extra="ignore",
@@ -466,6 +541,7 @@ class Settings(BaseSettings):
broker: Broker = Broker()
worker: Worker = Worker()
relay: Relay = Relay()
telemetry: Telemetry = Telemetry()
@classmethod
def settings_customise_sources(
+39 -31
View File
@@ -3,8 +3,9 @@
Design change `async-attachments`, решения 2 и 7; `pipeline-reliability`, решения
3, 4, 6, 7. `handle` разбирает сообщение, берёт задание по таблице claim, публикует
оригинал из staging в конечный ключ, получает варианты от процесса обработки,
пишет их объекты и одной транзакцией фиксирует `ready`; что делать с сообщением
(`JobOutcome`) решает итог, подтверждает его `src/worker/main.py`.
пишет их объекты и одной транзакцией фиксирует `ready`. Итог — исход доставки
(`JobDeliveryOutcome`, design change `otel-telemetry`, решение 11): из него
`src/worker/main.py` выводит действие с сообщением и пишет метрику.
Сообщение — подсказка, истина в строке задания. Worker не публикует: следующую
попытку и возврат зависшей публикует relay. Дубль при живой аренде и сообщение
@@ -38,7 +39,7 @@ from src.schemas.enums import (
AttachmentJobState,
AttachmentStatus,
AttachmentVariantName,
JobOutcome,
JobDeliveryOutcome,
)
from src.schemas.jobs import AttachmentJobMessage
from src.utils.constants import ATTACHMENT_PIPELINE_VERSION
@@ -95,15 +96,20 @@ class AttachmentProcessingService:
self.renderer = renderer
self.stop = stop
async def handle(self, *, body: bytes, redelivered: bool) -> JobOutcome:
"""Одна доставка; непредвиденная ошибка до попытки — `error` с
traceback, пауза и возврат в очередь: не немой повтор."""
async def handle(
self,
*,
body: bytes,
redelivered: bool,
) -> JobDeliveryOutcome:
"""Одна доставка и её исход; отказ PostgreSQL — пауза и возврат в
очередь."""
try:
message = AttachmentJobMessage.model_validate_json(body)
except ValidationError:
# содержимое сообщения и текст ошибки с его значениями — не в журнал
logger.error("Dropped malformed job message", size_bytes=len(body))
return JobOutcome.DROP
return JobDeliveryOutcome.DROPPED
# задача доставки своя, контекст не уходит к другим заданиям
http_request_id.set(str(message.job_id))
log = logger.bind(
@@ -121,7 +127,7 @@ class AttachmentProcessingService:
# Причину уже записала единица работы
log.warning("Job waits for database")
await self._pause()
return JobOutcome.REQUEUE
return JobDeliveryOutcome.REQUEUED
async def _run(
self,
@@ -129,9 +135,9 @@ class AttachmentProcessingService:
message: AttachmentJobMessage,
redelivered: bool,
log: AbstractLogger,
) -> JobOutcome:
) -> JobDeliveryOutcome:
claim = await self._claim(message=message, log=log)
if isinstance(claim, JobOutcome):
if isinstance(claim, JobDeliveryOutcome):
return claim
job, attachment, queue_wait_ms = claim
log = log.bind(attempt=job.attempt)
@@ -208,7 +214,8 @@ class AttachmentProcessingService:
render_memory_limit_applied=rendered.memory_limit_applied,
duration_ms=round((time.monotonic() - started) * 1000),
)
return JobOutcome.ACK
return JobDeliveryOutcome.READY
return JobDeliveryOutcome.SKIPPED
async def _claim(
self,
@@ -221,7 +228,7 @@ class AttachmentProcessingService:
dataclasses.AttachmentFullDTO,
int | None,
]
| JobOutcome
| JobDeliveryOutcome
):
"""Взять задание под блокировкой (таблица решения 3) или вернуть итог
без попытки. Сообщение без работы подтверждается: живую попытку ведёт её
@@ -230,13 +237,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 JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
if job.state == AttachmentJobState.SUCCEEDED:
await self._check_finished(job=job, log=log)
return JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
if job.state == AttachmentJobState.FAILED:
log.info("Skipped job message", reason="finished")
return JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
now = utcnow()
if (
job.state == AttachmentJobState.QUEUED
@@ -245,14 +252,14 @@ class AttachmentProcessingService:
and job.next_attempt_at > now
):
log.info("Skipped job message", reason="not_due")
return JobOutcome.ACK
return JobDeliveryOutcome.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 JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
if self._budget_spent(job):
# попытка потеряна при исчерпанном бюджете: сообщение пришло, а
# попытка уже посчитана
@@ -268,12 +275,12 @@ class AttachmentProcessingService:
reason=job.last_error_code,
attempt=job.attempt,
)
return JobOutcome.ACK
return JobDeliveryOutcome.FAILED
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 JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
started, attachment = taken
queue_wait_ms = (
None
@@ -498,26 +505,27 @@ class AttachmentProcessingService:
error_code: AttachmentErrorCode,
reason: AttachmentJobReason,
log: AbstractLogger,
) -> JobOutcome:
) -> JobDeliveryOutcome:
"""`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 JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
written = await self._write_failed(
job=job,
error_code=error_code,
reason=reason,
)
await self.uow.commit()
if written:
log.warning(
"Attachment failed",
error_code=error_code.value,
reason=reason.value,
)
return JobOutcome.ACK
if not written:
return JobDeliveryOutcome.SKIPPED
log.warning(
"Attachment failed",
error_code=error_code.value,
reason=reason.value,
)
return JobDeliveryOutcome.FAILED
@staticmethod
def _own_attempt(
@@ -537,7 +545,7 @@ class AttachmentProcessingService:
job: dataclasses.AttachmentJobDTO,
reason: AttachmentJobReason,
log: AbstractLogger,
) -> JobOutcome:
) -> JobDeliveryOutcome:
"""Временная ошибка: `queued` со сроком следующей попытки и ACK; её
сообщение опубликует relay, пауза места конкуренции не занимает.
Попытки исчерпаны — `failed`."""
@@ -566,7 +574,7 @@ class AttachmentProcessingService:
)
if not own:
log.info("Skipped job message", reason="superseded")
return JobOutcome.ACK
return JobDeliveryOutcome.SKIPPED
await self.uow.attachments.return_to_queued(
attachment_id=job.attachment_id,
updated_at=now,
@@ -578,7 +586,7 @@ class AttachmentProcessingService:
delay_seconds=round(delay, 3),
next_attempt_at=next_attempt_at.isoformat(),
)
return JobOutcome.ACK
return JobDeliveryOutcome.RETRY
async def _pause(self) -> None:
"""Пауза перед возвратом сообщения при отказе PostgreSQL; её прерывает
+56 -20
View File
@@ -13,7 +13,9 @@ Valkey переоткрывается сразу, а таймаут не пов
import asyncio
import time
from types import MappingProxyType
from opentelemetry.trace import Span
from redis.asyncio import BlockingConnectionPool, Redis
from redis.asyncio.retry import Retry
from redis.backoff import NoBackoff
@@ -21,10 +23,34 @@ from redis.exceptions import ConnectionError as RedisConnectionError
from redis.exceptions import RedisError
from src.config.settings import Cache as CacheSettings
from src.infra import telemetry
from src.infra.logger import AbstractLogger, get_logger
from src.utils.constants import ATTR_CACHE_RESULT
logger: AbstractLogger = get_logger().bind(module="cache")
# исход команды в span (`messenger.cache.result`)
CACHE_HIT = "hit"
CACHE_MISS = "miss"
CACHE_STORED = "stored"
CACHE_ERROR = "error"
# окно пропуска после отказа: команды не было
CACHE_SKIPPED = "skipped"
_SPAN_ATTRIBUTES = MappingProxyType({"db.system.name": "valkey"})
def _result(
span: Span | None,
result: str,
*,
error: BaseException | None = None,
) -> None:
if span is None:
return
span.set_attribute(ATTR_CACHE_RESULT, result)
if error is not None:
telemetry.mark_error(span, error)
class Cache:
"""Кэш поверх клиента Valkey: отказ — промах, а не исключение.
@@ -50,29 +76,39 @@ class Cache:
async def get(self, key: str) -> str | None:
"""Значение ключа; `None` — промах, в том числе из-за отказа."""
if self._skipping():
return None
try:
async with asyncio.timeout(self._timeout_seconds):
value = await self._client.get(key)
except (RedisError, OSError) as e:
self._failed(e)
return None
self._succeeded()
return value
# span без ключа: в нём chat_id (design change otel-telemetry,
# решение 12); исход — атрибут, отказ — ещё и статус ошибки
with telemetry.child_span("GET", attributes=_SPAN_ATTRIBUTES) as span:
if self._skipping():
_result(span, CACHE_SKIPPED)
return None
try:
async with asyncio.timeout(self._timeout_seconds):
value = await self._client.get(key)
except (RedisError, OSError) as e:
self._failed(e)
_result(span, CACHE_ERROR, error=e)
return None
self._succeeded()
_result(span, CACHE_MISS if value is None else CACHE_HIT)
return value
async def set(self, key: str, value: str, *, ttl_seconds: int) -> bool:
"""Записать со сроком; `False` — не записано из-за отказа."""
if self._skipping():
return False
try:
async with asyncio.timeout(self._timeout_seconds):
await self._client.set(key, value, ex=ttl_seconds)
except (RedisError, OSError) as e:
self._failed(e)
return False
self._succeeded()
return True
with telemetry.child_span("SET", attributes=_SPAN_ATTRIBUTES) as span:
if self._skipping():
_result(span, CACHE_SKIPPED)
return False
try:
async with asyncio.timeout(self._timeout_seconds):
await self._client.set(key, value, ex=ttl_seconds)
except (RedisError, OSError) as e:
self._failed(e)
_result(span, CACHE_ERROR, error=e)
return False
self._succeeded()
_result(span, CACHE_STORED)
return True
async def aclose(self) -> None:
await self._client.aclose()
+5 -1
View File
@@ -27,6 +27,7 @@ from src.core.repos.idempotency import SqlAlchemyIdempotencyRepository
from src.core.repos.message import SqlAlchemyMessageRepository
from src.core.repos.session import SqlAlchemySessionRepository
from src.core.repos.user import SqlAlchemyUserRepository
from src.infra import telemetry
from src.infra.db.scope import session_scope
@@ -76,7 +77,10 @@ class SqlAlchemyUnitOfWork(AbstractUnitOfWork):
return await scope.__aexit__(exc_type, exc, tb)
async def _commit(self) -> None:
await self._current_session().commit()
# COMMIT asyncpg идёт мимо событий курсора: свой span (design change
# otel-telemetry, решение 12), только под span запроса или задания
with telemetry.commit_span():
await self._current_session().commit()
async def _rollback(self) -> None:
await self._current_session().rollback()
+84
View File
@@ -7,7 +7,9 @@
import enum
import logging
import logging.config
import time
from abc import ABC, abstractmethod
from collections.abc import Callable
from contextvars import ContextVar
from typing import Any
from uuid import UUID
@@ -17,6 +19,10 @@ from structlog.processors import CallsiteParameter
from structlog.typing import EventDict, WrappedLogger
from src.config import settings
from src.utils.constants import (
TELEMETRY_SDK_LOG_WINDOW_SECONDS,
TELEMETRY_SDK_LOGGER_PREFIX,
)
# ставит request-id middleware, значение совпадает с X-Request-Id
http_request_id: ContextVar[str] = ContextVar("http_request_id", default="")
@@ -98,6 +104,70 @@ def normalize_values(
return event_dict
# хуки телеметрии (design change `otel-telemetry`, решения 2 и 12): ставит
# запуск телеметрии процесса, без неё их нет и записи прежние. Логгер SDK не
# импортирует
_export_hook: Callable[[EventDict], None] | None = None
_trace_fields_hook: Callable[[], tuple[str, str] | None] | None = None
def set_telemetry_hooks(
*,
export: Callable[[EventDict], None] | None,
trace_fields: Callable[[], tuple[str, str] | None] | None,
) -> None:
global _export_hook, _trace_fields_hook
_export_hook = export
_trace_fields_hook = trace_fields
def export_to_telemetry(
logger: WrappedLogger, # noqa: ARG001
method_name: str, # noqa: ARG001
event_dict: EventDict,
) -> EventDict:
"""Та же запись — в хранилище логов через SDK; раньше полей трассы."""
hook = _export_hook
if hook is not None:
hook(event_dict)
return event_dict
def add_trace_fields(
logger: WrappedLogger, # noqa: ARG001
method_name: str, # noqa: ARG001
event_dict: EventDict,
) -> EventDict:
"""`trace_id` и `span_id` активного span; вне span полей нет."""
hook = _trace_fields_hook
if hook is not None:
ids = hook()
if ids is not None:
event_dict["trace_id"], event_dict["span_id"] = ids
return event_dict
class RateLimitFilter(logging.Filter):
"""Не больше одной записи за окно на логгер с префиксом: отказ отправки
телеметрии без Collector не превращается в поток записей."""
def __init__(self, prefix: str, window_seconds: float) -> None:
super().__init__()
self._prefix = prefix
self._window = window_seconds
self._last: dict[str, float] = {}
def filter(self, record: logging.LogRecord) -> bool:
if not record.name.startswith(self._prefix):
return True
now = time.monotonic()
last = self._last.get(record.name)
if last is not None and now - last < self._window:
return False
self._last[record.name] = now
return True
def configure_logger() -> None:
timestamper = structlog.processors.TimeStamper(fmt="iso", utc=True)
structlog.configure_once(
@@ -120,6 +190,8 @@ def configure_logger() -> None:
add_request_context,
reorder_keys,
normalize_values,
export_to_telemetry,
add_trace_fields,
structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
],
logger_factory=structlog.stdlib.LoggerFactory(),
@@ -147,14 +219,26 @@ def configure_logger() -> None:
structlog.processors.format_exc_info,
add_request_context,
reorder_keys,
export_to_telemetry,
add_trace_fields,
],
},
},
"filters": {
# записи самого SDK OpenTelemetry — только stdout и не чаще
# одной в минуту на логгер
"telemetry_sdk": {
"()": RateLimitFilter,
"prefix": TELEMETRY_SDK_LOGGER_PREFIX,
"window_seconds": TELEMETRY_SDK_LOG_WINDOW_SECONDS,
},
},
"handlers": {
"json": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "json",
"filters": ["telemetry_sdk"],
},
},
# предупреждения прочих библиотек тоже в JSON
+58 -2
View File
@@ -17,15 +17,31 @@ import time
from contextlib import suppress
from pathlib import Path
from opentelemetry import trace
from opentelemetry.trace import Span, SpanKind
from src.config.settings import Worker as WorkerSettings
from src.core.exceptions import ImageRejected, RenderInterrupted
from src.infra import telemetry
from src.infra.logger import AbstractLogger, get_logger
from src.schemas.dataclasses import RenderedVariantDTO, RenderedVariantsDTO
from src.schemas.enums import AttachmentJobReason, AttachmentVariantName
from src.utils.constants import ATTACHMENT_MAX_PIXELS
from src.utils.constants import (
ATTACHMENT_MAX_PIXELS,
ATTR_RENDER_EXIT_CODE,
ATTR_RENDER_INPUT_SIZE,
ATTR_RENDER_OUTCOME,
ATTR_RENDER_PEAK_KIB,
)
logger: AbstractLogger = get_logger().bind(module="image_renderer")
# исход процесса обработки в span (`messenger.render.outcome`)
RENDER_OK = "ok"
RENDER_REJECTED = "rejected"
RENDER_INTERRUPTED = "interrupted"
RENDER_TIMEOUT = "timeout"
_RENDER_MODULE = "src.worker.render"
# корень приложения: `-m src.worker.render` ищет пакет от рабочего каталога
_APP_ROOT = Path(__file__).resolve().parent.parent.parent.parent
@@ -68,7 +84,34 @@ class ImageRenderer:
async def render(self, data: bytes) -> RenderedVariantsDTO:
"""Варианты из байтов оригинала. Изображение не прошло —
`ImageRejected`, процесс убит или упал — `RenderInterrupted`, срок —
`TimeoutError`."""
`TimeoutError`.
Span процесса (design change `otel-telemetry`, решение 12) — в
worker: процесс SDK не запускает, его окружение прежнее."""
with telemetry.child_span(
"render attachment variants",
kind=SpanKind.INTERNAL,
attributes={ATTR_RENDER_INPUT_SIZE: len(data)},
# отказ изображения — исход задания, а не сбой процесса
expected=(ImageRejected,),
) as span:
try:
rendered = await self._run(data)
except ImageRejected:
_outcome(span, RENDER_REJECTED)
raise
except RenderInterrupted:
_outcome(span, RENDER_INTERRUPTED)
raise
except TimeoutError:
_outcome(span, RENDER_TIMEOUT)
raise
_outcome(span, RENDER_OK)
if span is not None:
span.set_attribute(ATTR_RENDER_PEAK_KIB, rendered.peak_kib)
return rendered
async def _run(self, data: bytes) -> RenderedVariantsDTO:
started = time.monotonic()
process = await asyncio.create_subprocess_exec(
sys.executable,
@@ -87,6 +130,7 @@ class ImageRenderer:
finally:
await _reap(process)
code = process.returncode
_exit_code(code)
if code == 0:
return _parse(stdout, started=started)
reason = _EXIT_REASONS.get(code or 0)
@@ -102,6 +146,18 @@ class ImageRenderer:
)
def _outcome(span: Span | None, outcome: str) -> None:
if span is not None:
span.set_attribute(ATTR_RENDER_OUTCOME, outcome)
def _exit_code(code: int | None) -> None:
"""Код выхода процесса — в текущий span (span процесса обработки)."""
span = trace.get_current_span()
if code is not None and span.is_recording():
span.set_attribute(ATTR_RENDER_EXIT_CODE, code)
async def _reap(process: asyncio.subprocess.Process) -> None:
if process.returncode is not None:
return
+66 -17
View File
@@ -61,8 +61,13 @@ from botocore.exceptions import ConnectionError as BotoConnectionError
from src.config.settings import S3 as S3Settings
from src.core.exceptions import ObjectStorageUnavailable, StoredObjectMissing
from src.infra import telemetry
from src.infra.logger import AbstractLogger, get_logger
from src.utils.constants import S3_KEEPALIVE_TIMEOUT_SECONDS
from src.utils.constants import (
ATTR_OBJECT_SIZE,
ATTR_S3_RESULT,
S3_KEEPALIVE_TIMEOUT_SECONDS,
)
logger: AbstractLogger = get_logger().bind(module="object_storage")
@@ -107,6 +112,18 @@ OPERATION_NAMES = MappingProxyType(
"put_object": "put",
},
)
# имя операции botocore → `rpc.method` и имя span (`S3.<Операция>`)
SPAN_OPERATION_NAMES = MappingProxyType(
{
"list_objects_v2": "ListObjectsV2",
"head_object": "HeadObject",
"get_object": "GetObject",
"delete_object": "DeleteObject",
"put_object": "PutObject",
},
)
# операции, у которых нет объекта — штатный исход
_MISSING_IS_OUTCOME = frozenset({"head_object", "delete_object"})
@dataclass(frozen=True, slots=True)
@@ -392,23 +409,55 @@ class ObjectStorage:
if key is not None:
params["Key"] = key
target = key if key is not None else params.get("Prefix")
try:
async with asyncio.timeout(self._timeout_seconds):
response = await getattr(client, operation)(
Bucket=self.bucket,
**params,
method = SPAN_OPERATION_NAMES.get(operation, operation)
attributes: dict[str, Any] = {
"rpc.system": "aws-api",
"rpc.service": "S3",
"rpc.method": method,
"aws.s3.bucket": self.bucket,
}
if size is not None:
attributes[ATTR_OBJECT_SIZE] = size
# span без ключа: в нём id вложения (design change otel-telemetry,
# решение 12); нет объекта у HEAD и DELETE — исход, а не ошибка
with telemetry.child_span(
f"S3.{method}",
attributes=attributes,
expected=(
(StoredObjectMissing,)
if operation in _MISSING_IS_OUTCOME
else ()
),
) as span:
try:
async with asyncio.timeout(self._timeout_seconds):
response = await getattr(client, operation)(
Bucket=self.bucket,
**params,
)
except TRANSLATED_ERRORS as e:
failure = self._failure(
e,
operation=operation,
key=target,
started=started,
listing=key is None,
)
except TRANSLATED_ERRORS as e:
failure = self._failure(
e,
operation=operation,
key=target,
started=started,
listing=key is None,
)
if failure is None:
raise
raise failure from e
if span is not None:
span.set_attribute(
ATTR_S3_RESULT,
"missing"
if isinstance(failure, StoredObjectMissing)
else "error",
)
if failure is None:
raise
raise failure from e
if span is not None:
span.set_attribute(ATTR_S3_RESULT, "ok")
length = response.get("ContentLength")
if size is None and isinstance(length, int):
span.set_attribute(ATTR_OBJECT_SIZE, length)
logger.debug(
"Called object storage",
operation=operation,
+45
View File
@@ -0,0 +1,45 @@
"""Телеметрия процессов API и worker (design change `otel-telemetry`).
Правила — `.claude/rules/telemetry.md`. Без включённой телеметрии все вызовы
ничего не делают: ни провайдеров, ни хуков журнала, ни обращений к Collector.
"""
from src.infra.telemetry.core import (
Exporters,
JobObservation,
begin_shutdown,
child_span,
consumer_span,
finish_request,
http_method,
is_enabled,
mark_error,
remove_otel_environment,
server_span,
shutdown,
wait_closed,
)
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.setup import start_process_telemetry
__all__ = [
"Exporters",
"JobObservation",
"begin_shutdown",
"child_span",
"commit_span",
"consumer_span",
"finish_request",
"http_method",
"install_log_hooks",
"instrument_engine",
"is_enabled",
"mark_error",
"remove_log_hooks",
"remove_otel_environment",
"server_span",
"shutdown",
"start_process_telemetry",
"wait_closed",
]
+498
View File
@@ -0,0 +1,498 @@
"""Запуск и закрытие SDK OpenTelemetry, span и метрики процесса.
Design change `otel-telemetry`, решения 4, 8–13; правила —
`.claude/rules/telemetry.md`. Провайдеры глобальными не ставятся: их держит
состояние модуля, а вызовы ниже при выключенной телеметрии ничего не делают.
SDK собирается только из `[telemetry]`: переменные `OTEL_*` удаляются из
окружения до создания провайдеров (`OTEL_SDK_DISABLED` провайдеры читают в
конструкторе), ресурс — конструктором без детекторов, у всех параметров
явные значения, `atexit` SDK выключен.
"""
import asyncio
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 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 src.config.settings import Telemetry as TelemetrySettings
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,
SERVICE_VERSION,
TELEMETRY_LOG_ATTRIBUTE_LENGTH,
TELEMETRY_LOGS_PATH,
TELEMETRY_MAX_ATTRIBUTES,
TELEMETRY_METRICS_PATH,
TELEMETRY_SCOPE,
TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
TELEMETRY_TRACES_PATH,
)
_OTEL_ENV_PREFIX = "OTEL_"
# все инструменты — cumulative: Prometheus забирает накопленное (решение 3)
_CUMULATIVE = dict.fromkeys(
(
Counter,
UpDownCounter,
Histogram,
ObservableCounter,
ObservableUpDownCounter,
ObservableGauge,
),
AggregationTemporality.CUMULATIVE,
)
@dataclass(frozen=True, slots=True)
class Exporters:
"""Получатели сигналов вместо OTLP — только для быстрых тестов
(in-memory экспортёры SDK)."""
spans: SpanExporter
metrics: MetricReader
logs: LogRecordExporter
@dataclass(slots=True)
class _State:
tracer: Tracer
otel_logger: OtelLogger
http_duration: Any
job_duration: Any
tracer_provider: TracerProvider
meter_provider: MeterProvider
logger_provider: LoggerProvider
_state: _State | None = None
def is_enabled() -> bool:
return _state is not None
def remove_otel_environment() -> list[str]:
"""Удалить `OTEL_*` из окружения процесса; имена — для записи
`warning` (без значений)."""
names = sorted(
name for name in os.environ if name.startswith(_OTEL_ENV_PREFIX)
)
for name in names:
os.environ.pop(name, None)
return names
def start(
*,
service_name: str,
instance_id: str,
config: TelemetrySettings,
exporters: Exporters | None = None,
) -> bool:
"""Провайдеры трасс, метрик и логов процесса. Выключено — ничего.
Вызывающий до этого удаляет `OTEL_*` (`remove_otel_environment`) и
пишет `warning`; хуки журнала ставит `src.infra.telemetry.logs`."""
global _state
if _state is not None:
return True
if not config.enabled and exporters is None:
return False
resource = Resource(
{
"service.name": service_name,
"service.version": SERVICE_VERSION,
"service.instance.id": instance_id,
"deployment.environment.name": config.environment,
},
)
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,
),
)
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(
TELEMETRY_SCOPE,
SERVICE_VERSION,
),
http_duration=meter.create_histogram(
METRIC_HTTP_SERVER_DURATION,
unit="s",
description="Duration of HTTP server requests",
),
job_duration=meter.create_histogram(
METRIC_JOB_DURATION,
unit="s",
description="Duration of job deliveries handled by the worker",
),
tracer_provider=tracer_provider,
meter_provider=meter_provider,
logger_provider=logger_provider,
)
return True
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,
),
metrics=PeriodicExportingMetricReader(
OTLPMetricExporter(
endpoint=endpoint + TELEMETRY_METRICS_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
preferred_temporality=_CUMULATIVE,
),
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,
),
)
def begin_shutdown() -> list[threading.Thread]:
"""Закрытие провайдеров в daemon-потоках, по одному на сигнал: при
замороженном Collector каждый ждёт свой срок отправки, а записи журнала
не стоят за метриками. Новые span и записи после вызова не создаются.
Вызывающий ждёт потоки не дольше своего срока (`wait_closed`)."""
global _state
state, _state = _state, None
if state is None:
return []
threads = [
threading.Thread(
target=_quiet_shutdown,
args=(provider,),
name=f"telemetry-shutdown-{name}",
daemon=True,
)
for name, provider in (
("logs", state.logger_provider),
("traces", state.tracer_provider),
("metrics", state.meter_provider),
)
]
for thread in threads:
thread.start()
return threads
def _quiet_shutdown(provider: Any) -> None:
# отказ отправки при остановке не должен ронять поток с traceback
with suppress(Exception):
provider.shutdown()
async def wait_closed(
threads: Sequence[threading.Thread],
*,
timeout: float,
) -> None:
"""Ждать закрытия, не блокируя цикл событий, не дольше `timeout`: что не
ушло — теряется, daemon-потоки выход процесса не держат."""
with suppress(TimeoutError):
async with asyncio.timeout(timeout):
while any(thread.is_alive() for thread in threads):
await asyncio.sleep(0.01)
async def shutdown(*, timeout: float) -> None:
await wait_closed(begin_shutdown(), timeout=timeout)
def mark_error(span: Span, error: BaseException) -> None:
"""Статус ошибки и класс ошибки — без текста исключения: в нём бывают
данные (сообщение ошибки ограничения), traceback пишет журнал."""
span.set_status(Status(StatusCode.ERROR))
span.set_attribute(ATTR_ERROR_TYPE, type(error).__name__)
@contextmanager
def child_span(
name: str,
*,
kind: SpanKind = SpanKind.CLIENT,
attributes: Mapping[str, Any] | None = None,
expected: tuple[type[BaseException], ...] = (),
) -> Iterator[Span | None]:
"""Дочерний span обращения к хранилищу или процессу — только под
записывающим родителем (правило корня, решение 4): проверка готовности
и фоновые циклы трасс не создают. `expected` — исключения-исходы, а не
ошибки (нет объекта у HEAD)."""
state = _state
if state is None or not trace.get_current_span().is_recording():
yield None
return
with state.tracer.start_as_current_span(
name,
kind=kind,
attributes=attributes,
record_exception=False,
set_status_on_exception=False,
) as span:
try:
yield span
except BaseException as e:
if not isinstance(e, expected):
mark_error(span, e)
raise
def http_method(method: str) -> str:
"""Стандартный метод HTTP или `_OTHER`: метод выбирает клиент."""
return method if method in HTTP_KNOWN_METHODS else HTTP_OTHER_METHOD
@contextmanager
def server_span() -> Iterator[Span | None]:
"""Span `SERVER` запроса, корень трассы: входящие `traceparent` и
`tracestate` не извлекаются (решение 10). Имя и атрибуты — после
маршрутизации (`finish_request`)."""
state = _state
if state is None:
yield None
return
span = state.tracer.start_span(
"HTTP",
context=Context(),
kind=SpanKind.SERVER,
)
with trace.use_span(
span,
end_on_exit=True,
record_exception=False,
set_status_on_exception=False,
):
yield span
def finish_request(
span: Span | None,
*,
method: str,
route: str | None,
status_code: int,
request_id: str,
duration_seconds: float,
error: BaseException | None,
) -> None:
"""Имя, атрибуты и статус server span и наблюдение histogram HTTP."""
state = _state
if state is None or span is None:
return
method = http_method(method)
attributes: dict[str, Any] = {
ATTR_HTTP_METHOD: method,
ATTR_HTTP_STATUS: status_code,
}
if route is not None:
attributes[ATTR_HTTP_ROUTE] = route
span.update_name(f"{method} {route}" if route is not None else method)
span.set_attributes(attributes)
span.set_attribute(ATTR_REQUEST_ID, request_id)
if error is not None:
mark_error(span, error)
elif status_code >= 500:
span.set_status(Status(StatusCode.ERROR))
span.set_attribute(ATTR_ERROR_TYPE, str(status_code))
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},
)
@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 tracer() -> Tracer | None:
state = _state
return None if state is None else state.tracer
def otel_logger() -> OtelLogger | None:
state = _state
return None if state is None else state.otel_logger
+114
View File
@@ -0,0 +1,114 @@
"""Span запросов PostgreSQL — слушатели событий engine (решения 4 и 12).
`instrumentation-sqlalchemy` 0.66b2 требует `sqlalchemy<2.1`, а у нас 2.1:
поэтому свои слушатели `before_cursor_execute`, `after_cursor_execute` и
`handle_error`. Их ставит точка входа процесса (`instrument_engine`), фабрика
engine о телеметрии не знает. Запрос асинхронной сессии выполняется в
greenlet с контекстом задачи: родитель — span запроса или задания, без него
span нет (правило корня). Фиксацию (`COMMIT` asyncpg идёт мимо событий
курсора) пишет `SqlAlchemyUnitOfWork._commit`.
"""
from typing import Any
from opentelemetry import trace
from opentelemetry.trace import SpanKind
from sqlalchemy import event
from sqlalchemy.engine import ExceptionContext
from sqlalchemy.ext.asyncio import AsyncEngine
from src.infra.telemetry import core
DB_SYSTEM = "postgresql"
# атрибут контекста выполнения со span запроса
_SPAN_ATTR = "_messenger_span"
def db_attributes(engine_url: Any) -> dict[str, Any]:
attributes: dict[str, Any] = {
"db.system.name": DB_SYSTEM,
"db.namespace": engine_url.database or "",
"server.address": engine_url.host or "",
}
if engine_url.port is not None:
attributes["server.port"] = engine_url.port
return attributes
def operation_name(statement: str) -> str:
"""Первое слово запроса: `SELECT`, `INSERT`, `WITH`…"""
words = statement.split(None, 1)
return words[0].upper() if words else "QUERY"
def instrument_engine(engine: AsyncEngine) -> None:
"""Слушатели span на engine процесса; телеметрия выключена — ничего."""
if not core.is_enabled():
return
sync_engine = engine.sync_engine
base = db_attributes(sync_engine.url)
def before(
_conn: Any,
_cursor: Any,
statement: str,
_parameters: Any,
context: Any,
_executemany: bool,
) -> None:
tracer = core.tracer()
if (
tracer is None
or context is None
or not trace.get_current_span().is_recording()
):
return
operation = operation_name(statement)
span = tracer.start_span(
operation,
kind=SpanKind.CLIENT,
attributes={
**base,
"db.operation.name": operation,
# параметризованный SQL: значения — плейсхолдеры
"db.query.text": statement,
},
)
setattr(context, _SPAN_ATTR, span)
def after(
_conn: Any,
_cursor: Any,
_statement: str,
_parameters: Any,
context: Any,
_executemany: bool,
) -> None:
span = getattr(context, _SPAN_ATTR, None)
if span is not None:
setattr(context, _SPAN_ATTR, None)
span.end()
def on_error(exception_context: ExceptionContext) -> None:
context = exception_context.execution_context
span = getattr(context, _SPAN_ATTR, None)
if span is None:
return
setattr(context, _SPAN_ATTR, None)
core.mark_error(span, exception_context.original_exception)
span.end()
event.listen(sync_engine, "before_cursor_execute", before)
event.listen(sync_engine, "after_cursor_execute", after)
event.listen(sync_engine, "handle_error", on_error)
def commit_span() -> Any:
"""Span фиксации транзакции единицы работы."""
return core.child_span(
"COMMIT",
attributes={
"db.system.name": DB_SYSTEM,
"db.operation.name": "COMMIT",
},
)
+108
View File
@@ -0,0 +1,108 @@
"""Запись журнала → запись OpenTelemetry и поля трассы в stdout (решения 2,
12).
`src/infra/logger.py` SDK не импортирует: его процессоры зовут хуки, которые
ставит `install_log_hooks` при включённой телеметрии. Экспорт стоит раньше
полей трассы: в отправленной записи `trace_id` и `span_id` — поля контекста,
а не атрибуты. Записи логгеров `opentelemetry.*` не экспортируются: их отказ
отправки шёл бы в ту же очередь.
"""
import json
import time
from datetime import datetime
from typing import Any
from opentelemetry import context as otel_context
from opentelemetry import trace
from opentelemetry._logs import SeverityNumber
from src.infra import logger as app_logger
from src.infra.telemetry import core
from src.utils.constants import TELEMETRY_SDK_LOGGER_PREFIX
_SEVERITY = {
"debug": SeverityNumber.DEBUG,
"info": SeverityNumber.INFO,
"warning": SeverityNumber.WARN,
"warn": SeverityNumber.WARN,
"error": SeverityNumber.ERROR,
"exception": SeverityNumber.ERROR,
"critical": SeverityNumber.FATAL,
}
# поля записи, которые становятся не атрибутами, а телом, уровнем и временем
_RECORD_FIELDS = frozenset({"event", "level", "timestamp"})
def install_log_hooks() -> None:
app_logger.set_telemetry_hooks(export=export_event, trace_fields=trace_ids)
def remove_log_hooks() -> None:
app_logger.set_telemetry_hooks(export=None, trace_fields=None)
def trace_ids() -> tuple[str, str] | None:
"""`trace_id` и `span_id` (hex) активного записывающего span."""
span = trace.get_current_span()
span_context = span.get_span_context()
if not (span_context.is_valid and span.is_recording()):
return None
return (
format(span_context.trace_id, "032x"),
format(span_context.span_id, "016x"),
)
def export_event(event_dict: dict[str, Any]) -> None:
"""Запись structlog — в логгер SDK: тело — `event`, уровень — `level`,
время — `timestamp`, остальные поля — атрибутами, контекст — текущий."""
otel_logger = core.otel_logger()
if otel_logger is None:
return
record = event_dict.get("_record")
name = record.name if record is not None else event_dict.get("logger")
if isinstance(name, str) and name.startswith(TELEMETRY_SDK_LOGGER_PREFIX):
return
level = str(event_dict.get("level", "info")).lower()
attributes = {
key: converted
for key, value in event_dict.items()
if key not in _RECORD_FIELDS
and not key.startswith("_")
and (converted := attribute_value(value)) is not None
}
otel_logger.emit(
timestamp=_timestamp_ns(event_dict.get("timestamp")),
observed_timestamp=time.time_ns(),
context=otel_context.get_current(),
severity_number=_SEVERITY.get(level, SeverityNumber.INFO),
severity_text=level,
body=str(event_dict.get("event", "")),
attributes=attributes,
)
def attribute_value(value: Any) -> str | int | float | bool | None:
"""`str`, `int`, `float`, `bool` — как есть, `None` — пропуск, список и
словарь — JSON (варианты вложения), прочее — строкой."""
if value is None:
return None
if isinstance(value, str | bool | int | float):
return value
if isinstance(value, list | tuple | dict):
return json.dumps(value, ensure_ascii=False, default=str)
return str(value)
def _timestamp_ns(value: Any) -> int:
"""ISO 8601 UTC записи (`TimeStamper`) → наносекунды; нет — сейчас."""
if isinstance(value, str):
try:
moment = datetime.fromisoformat(value)
except ValueError:
return time.time_ns()
return int(moment.timestamp()) * 1_000_000_000 + (
moment.microsecond * 1000
)
return time.time_ns()
+36
View File
@@ -0,0 +1,36 @@
"""Запуск телеметрии точкой входа процесса (API, worker)."""
from src.config import settings
from src.infra.logger import AbstractLogger, get_logger
from src.infra.telemetry import core
from src.infra.telemetry.core import Exporters
from src.infra.telemetry.logs import install_log_hooks
logger: AbstractLogger = get_logger().bind(module="telemetry")
def start_process_telemetry(
service_name: str,
*,
exporters: Exporters | None = None,
) -> bool:
"""По `[telemetry]`: выключено — ничего. Включено — `OTEL_*` удаляются
из окружения с `warning` (имена без значений), затем провайдеры и хуки
журнала. `True` — телеметрия работает."""
config = settings.telemetry
if not config.enabled and exporters is None:
return False
ignored = core.remove_otel_environment()
started = core.start(
service_name=service_name,
instance_id=settings.app.instance_id,
config=config,
exporters=exporters,
)
install_log_hooks()
if ignored:
logger.warning(
"Ignored OpenTelemetry environment variables",
names=ignored,
)
return started
+29 -3
View File
@@ -8,13 +8,18 @@ from src.api import errors
from src.api.middlewares import RequestContextMiddleware
from src.api.routers import health_router, v1_router
from src.config import settings
from src.infra import early_stop
from src.infra import early_stop, telemetry
from src.infra.cache.instance import cache
from src.infra.db.session import engine
from src.infra.logger import AbstractLogger, get_logger
from src.infra.password import prepare_dummy_hash
from src.infra.s3.instance import object_storage
from src.schemas.enums import RunModeEnum
from src.utils.constants import (
SERVICE_VERSION,
TELEMETRY_SERVICE_API,
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS,
)
logger: AbstractLogger = get_logger().bind(module="startup")
@@ -27,6 +32,12 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
early_stop.disarm()
database = settings.database
s3 = settings.s3
# выключена — ни провайдеров, ни хуков журнала (design change
# otel-telemetry, решение 8); включена — слушатели span на engine
telemetry_enabled = telemetry.start_process_telemetry(
TELEMETRY_SERVICE_API,
)
telemetry.instrument_engine(engine)
# engine, кэш и S3 подключаются лениво: без Postgres сервис стартует, а
# /health/ready отвечает 503; без Valkey запросы идут в Postgres; без
# S3 — 503 только на путях вложений. Брокера у реплик нет
@@ -62,6 +73,13 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
uploads_wait_timeout_seconds=settings.uploads.wait_timeout_seconds,
uploads_body_timeout_seconds=settings.uploads.body_timeout_seconds,
uploads_max_unfinished_jobs=settings.uploads.max_unfinished_jobs,
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
),
)
try:
yield
@@ -70,11 +88,19 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
await cache.aclose()
await object_storage.aclose()
logger.info("Stopped API")
# после записи об остановке: она уходит последним пакетом, если
# Collector жив; ожидание — своим сроком внутри 10 с (решение 13)
await telemetry.shutdown(timeout=TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS)
def create_app() -> FastAPI:
# версия — info.version контракта (contracts/openapi.json)
app = FastAPI(title="MTUSI Messenger", version="1.5.0", lifespan=lifespan)
# версия — info.version контракта (contracts/openapi.json), она же
# service.version телеметрии
app = FastAPI(
title="MTUSI Messenger",
version=SERVICE_VERSION,
lifespan=lifespan,
)
app.add_middleware(RequestContextMiddleware)
errors.register(app)
app.include_router(health_router)
+2
View File
@@ -5,6 +5,7 @@ from .attachment import (
AttachmentStatus,
AttachmentVariantName,
ImageType,
JobDeliveryOutcome,
JobOutcome,
ReconcileAction,
ReconcileFinding,
@@ -19,6 +20,7 @@ __all__ = [
"AttachmentStatus",
"AttachmentVariantName",
"ImageType",
"JobDeliveryOutcome",
"JobOutcome",
"ReconcileAction",
"ReconcileFinding",
+31
View File
@@ -74,6 +74,37 @@ class JobOutcome(StrEnum):
DROP = "drop"
class JobDeliveryOutcome(StrEnum):
"""Исход доставки worker (design change `otel-telemetry`, решение 11): его
называет сервис, точка входа выводит из него действие с сообщением и пишет
метку `messenger.job.outcome`. В БД не хранится."""
# вложение стало ready
READY = "ready"
# вложение стало failed: постоянная ошибка или исчерпан бюджет попыток
FAILED = "failed"
# попытка не удалась, назначена следующая
RETRY = "retry"
# подтверждено без попытки и без эффекта: задание завершено или
# неизвестно, живая попытка, срок не наступил, задание ведёт другая
SKIPPED = "skipped"
# PostgreSQL недоступен, сообщение возвращено в очередь
REQUEUED = "requeued"
# сообщение не по схеме
DROPPED = "dropped"
# непредвиденная ошибка до итога; назначает src/worker/main.py
ERROR = "error"
@property
def action(self) -> JobOutcome:
"""Что сделать с сообщением."""
if self is JobDeliveryOutcome.DROPPED:
return JobOutcome.DROP
if self in (JobDeliveryOutcome.REQUEUED, JobDeliveryOutcome.ERROR):
return JobOutcome.REQUEUE
return JobOutcome.ACK
class ImageType(StrEnum):
"""Тип изображения, определённый по содержимому."""
+77
View File
@@ -141,6 +141,83 @@ DB_CLOSE_TIMEOUT_SECONDS = 2
# не читаются без чистки кэша
CACHE_KEY_PREFIX = "messenger:v1"
# телеметрия (с лабы 6, design change `otel-telemetry`, решения 8–12)
# service.name ресурса: процесс API и процесс worker
TELEMETRY_SERVICE_API = "messenger-api"
TELEMETRY_SERVICE_WORKER = "messenger-worker"
# service.version — info.version контракта, который реализует код
# (contracts/openapi.json); из неё же версия приложения FastAPI
SERVICE_VERSION = "1.6.0"
# имя инструментирования (otel_scope_name в Prometheus)
TELEMETRY_SCOPE = "mtusi-messenger"
# пути OTLP/HTTP сигналов от адреса Collector
TELEMETRY_TRACES_PATH = "/v1/traces"
TELEMETRY_METRICS_PATH = "/v1/metrics"
TELEMETRY_LOGS_PATH = "/v1/logs"
# секунды, которые процесс ждёт закрытия SDK при остановке; что не ушло —
# теряется (решение 13): API — 8 с дренажа + закрытие клиентов + 1 с < 10 с
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS = 1
# секунды: не больше одной записи логгера `opentelemetry.*` в stdout за окно
TELEMETRY_SDK_LOG_WINDOW_SECONDS = 60
# префикс логгеров самого SDK: их записи не экспортируются
TELEMETRY_SDK_LOGGER_PREFIX = "opentelemetry"
# лимиты span и записей журнала: длина значения атрибута (запрос SQL,
# traceback) и число атрибутов
TELEMETRY_MAX_ATTRIBUTES = 128
TELEMETRY_SPAN_ATTRIBUTE_LENGTH = 4096
TELEMETRY_LOG_ATTRIBUTE_LENGTH = 32768
# метрики (имена OpenTelemetry; в Prometheus — с единицей и подчёркиваниями)
METRIC_HTTP_SERVER_DURATION = "http.server.request.duration"
METRIC_JOB_DURATION = "messenger.job.duration"
# границы buckets, секунды: чтение 2–10 мс, вход с Argon2id 0,1–0,5 с,
# загрузки до 5 с, срок JSON-запроса 6 с, timeout server LB 10 и 30 с
HTTP_DURATION_BUCKETS = (
0.005,
0.01,
0.025,
0.05,
0.1,
0.25,
0.5,
1,
2.5,
5,
10,
30,
)
# процесс обработки 0,2–1 с, его срок 40 с, срок попытки 60 с
JOB_DURATION_BUCKETS = (0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 20, 40, 60)
# стандартные методы HTTP (semantic conventions); прочие — `_OTHER`
HTTP_KNOWN_METHODS = frozenset(
{
"CONNECT",
"DELETE",
"GET",
"HEAD",
"OPTIONS",
"PATCH",
"POST",
"PUT",
"TRACE",
},
)
HTTP_OTHER_METHOD = "_OTHER"
# атрибуты span и метрик (semantic conventions и свои `messenger.*`)
ATTR_HTTP_METHOD = "http.request.method"
ATTR_HTTP_ROUTE = "http.route"
ATTR_HTTP_STATUS = "http.response.status_code"
ATTR_ERROR_TYPE = "error.type"
ATTR_REQUEST_ID = "messenger.request_id"
ATTR_JOB_TYPE = "messenger.job.type"
ATTR_JOB_OUTCOME = "messenger.job.outcome"
ATTR_CACHE_RESULT = "messenger.cache.result"
ATTR_OBJECT_SIZE = "messenger.object.size"
ATTR_S3_RESULT = "messenger.s3.result"
ATTR_RENDER_INPUT_SIZE = "messenger.render.input_size"
ATTR_RENDER_OUTCOME = "messenger.render.outcome"
ATTR_RENDER_EXIT_CODE = "messenger.render.exit_code"
ATTR_RENDER_PEAK_KIB = "messenger.render.peak_kib"
# хранилище объектов (S3)
# имя bucket по правилам S3: 3–63 символа, строчные латинские буквы,
# цифры, точка и дефис, по краям — буква или цифра
+59 -17
View File
@@ -25,6 +25,7 @@ SIGTERM: новые сообщения не принимаются, начаты
import asyncio
import signal
import time
from collections.abc import Callable
from contextlib import suppress
@@ -34,14 +35,15 @@ from src.config import settings
from src.core.services.attachment_processing import (
AttachmentProcessingService,
)
from src.infra import early_stop
from src.infra import early_stop, telemetry
from src.infra.broker import JobConsumer, JobDelivery, queue_name
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.infra.render import ImageRenderer
from src.infra.s3 import ObjectStorage, create_object_storage
from src.schemas.enums import JobOutcome
from src.schemas.enums import JobDeliveryOutcome, JobOutcome
from src.utils.constants import ATTACHMENT_JOB_TYPE, TELEMETRY_SERVICE_WORKER
logger: AbstractLogger = get_logger().bind(module="worker")
@@ -89,7 +91,11 @@ async def run() -> int:
worker = settings.worker
namespace = settings.database.name
telemetry_enabled = telemetry.start_process_telemetry(
TELEMETRY_SERVICE_WORKER,
)
engine = create_engine(settings.database)
telemetry.instrument_engine(engine)
session_factory = create_session_factory(engine)
storage = create_object_storage(settings.s3, namespace=namespace)
@@ -132,17 +138,32 @@ 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(make_service, namespace=namespace, stop=stop)
finally:
# одним сроком, а не по очереди: сумма не растёт с числом клиентов (S5)
# одним сроком, а не по очереди: сумма не растёт с числом клиентов
# (S5). Закрытие SDK — в том же окне: потоки стартуют до gather и
# ждутся вместе с ним, что не ушло — теряется (решение 13)
closing = telemetry.begin_shutdown()
with suppress(Exception):
async with asyncio.timeout(_CLOSE_TIMEOUT_SECONDS):
await asyncio.gather(
engine.dispose(),
storage.aclose(),
telemetry.wait_closed(
closing,
timeout=_CLOSE_TIMEOUT_SECONDS,
),
return_exceptions=True,
)
# после закрытия SDK — только stdout
logger.info("Stopped worker", exit_code=EXIT_OK)
return EXIT_OK
@@ -239,22 +260,43 @@ async def _handle(
async with slots:
if stop.is_set():
return
try:
outcome = await make_service().handle(
body=delivery.body,
redelivered=delivery.redelivered,
)
except Exception as e:
logger.error("Job handling failed", exc_info=e)
with suppress(TimeoutError):
await asyncio.wait_for(
stop.wait(),
timeout=settings.worker.reconnect_seconds,
# 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()
try:
outcome = await make_service().handle(
body=delivery.body,
redelivered=delivery.redelivered,
)
outcome = JobOutcome.REQUEUE
if outcome == JobOutcome.ACK:
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,
)
await _settle(delivery, outcome.action)
async def _settle(delivery: JobDelivery, action: JobOutcome) -> None:
if action == JobOutcome.ACK:
await delivery.ack()
elif outcome == JobOutcome.DROP:
elif action == JobOutcome.DROP:
await delivery.drop()
else:
await delivery.requeue()
+7
View File
@@ -37,6 +37,12 @@ services:
stop_grace_period: 2s
haproxy:
ports: !reset []
# API (docker compose run) и worker — без телеметрии: сервисы телеметрии
# стенд не запускает, методика и сроки прежние (design change
# otel-telemetry, решение 20)
api:
environment:
TELEMETRY__ENABLED: "false"
# свой брокер со своим volume, порт AMQP не публикуется
rabbitmq:
ports: !reset []
@@ -64,6 +70,7 @@ services:
WORKER__RENDER_TIMEOUT_SECONDS: "8"
WORKER__RENDER_CPU_LIMIT_SECONDS: "3"
WORKER__GRACEFUL_SHUTDOWN_SECONDS: "2"
TELEMETRY__ENABLED: "false"
# уборщик с grace и интервалом, сравнимыми со временем теста (design
# change upload-consistency, решение 10). Grace 20 с больше границы живой
# загрузки при сроках по умолчанию (2 × 6 + 5 = 17 с): занижать сроки ради
+6
View File
@@ -298,6 +298,10 @@ def main() -> int:
container,
"-e",
f"DATABASE__NAME={test_db}",
# временный прогон — без телеметрии: в Loki и Prometheus рабочего
# стенда не попадает (design change otel-telemetry, решение 20)
"-e",
"TELEMETRY__ENABLED=false",
"-p",
f"127.0.0.1:{port}:{app_port}",
"api",
@@ -315,6 +319,8 @@ def main() -> int:
worker,
"-e",
f"DATABASE__NAME={test_db}",
"-e",
"TELEMETRY__ENABLED=false",
"worker",
quiet=True,
)
Generated
+145
View File
@@ -531,6 +531,18 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" },
]
[[package]]
name = "googleapis-common-protos"
version = "1.76.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "protobuf" },
]
sdist = { url = "https://files.pythonhosted.org/packages/62/b6/bc095b23a3e0d978e75c8c18cabe4c11f791837410670e4486f0d539bfba/googleapis_common_protos-1.76.0.tar.gz", hash = "sha256:71db0e44a1d4c2dd024ebad44ca67129cc1e2892e4861df466764749d5ef8642", size = 156250, upload-time = "2026-10-22T23:43:36.263Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/05/6d/78dc67a9e779e594b49bf62604034d3a6aa428a55afc729cafda4b7333e1/googleapis_common_protos-1.76.0-py3-none-any.whl", hash = "sha256:59e13344a9f3651aa201a03e2bee815a3bf43a4baf1f9ff8a9b62a840ce25fac", size = 307707, upload-time = "2026-10-22T23:43:10.445Z" },
]
[[package]]
name = "greenlet"
version = "3.5.6"
@@ -777,6 +789,9 @@ dependencies = [
{ name = "argon2-cffi" },
{ name = "asyncpg" },
{ name = "fastapi", extra = ["all"] },
{ name = "opentelemetry-api" },
{ name = "opentelemetry-exporter-otlp-proto-http" },
{ name = "opentelemetry-sdk" },
{ name = "pillow" },
{ name = "pydantic" },
{ name = "pydantic-settings" },
@@ -809,6 +824,9 @@ requires-dist = [
{ name = "argon2-cffi", specifier = ">=25.1.0,<26" },
{ name = "asyncpg", specifier = ">=0.31.0,<0.32" },
{ name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" },
{ name = "opentelemetry-api", specifier = ">=1.45.2,<1.46" },
{ name = "opentelemetry-exporter-otlp-proto-http", specifier = ">=1.45.2,<1.46" },
{ name = "opentelemetry-sdk", specifier = ">=1.45.2,<1.46" },
{ name = "pillow", specifier = ">=13,<14" },
{ name = "pydantic", specifier = ">=2.6.3,<3.0.0" },
{ name = "pydantic-settings", specifier = ">=2.15.0,<3.0.0" },
@@ -906,6 +924,118 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/27/dd/b3fd642260cb17532f66cc1e8250f3507d1e580483e209dc1e9d13bd980d/openapi_spec_validator-0.7.2-py3-none-any.whl", hash = "sha256:4bbdc0894ec85f1d1bea1d6d9c8b2c3c8d7ccaa13577ef40da9c006c9fd0eb60", size = 39713, upload-time = "2025-06-07T14:48:54.077Z" },
]
[[package]]
name = "opentelemetry-api"
version = "1.45.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "typing-extensions" },
]
sdist = { url = "https://files.pythonhosted.org/packages/19/14/cf3a6b6448849656e1e5f4e2101f3988dc6789724050096aba1bc5ccf592/opentelemetry_api-1.45.2.tar.gz", hash = "sha256:d7b0008e21e5fd61cbe7a7f34ca3b6905a78ab677d9bc395e299359c75cda6b4", size = 73277, upload-time = "2026-10-29T17:29:37.888Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/a9/2d/610db864d7513158cebb8f36cc88e67e73bd6c7aa1905ef18d89e1281c81/opentelemetry_api-1.45.2-py3-none-any.whl", hash = "sha256:2cbd737377e710ee740d261c94e93fa0f08e6d037c18f17513cc0a2d94479a34", size = 60335, upload-time = "2026-10-29T17:29:06.955Z" },
]
[[package]]
name = "opentelemetry-exporter-http-transport"
version = "0.66b2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "opentelemetry-api" },
]
sdist = { url = "https://files.pythonhosted.org/packages/a6/e6/dbeb3e217418071656232a4028c791060d219f218cef1249b664049d12c0/opentelemetry_exporter_http_transport-0.66b2.tar.gz", hash = "sha256:66d6ed810a515432c8891da9a834464332fd70badeca45bdeeae81b4280c903b", size = 11693, upload-time = "2026-10-29T17:29:39.444Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/a1/b2/c622a101f31c0e6670b82f4264c4e77c161bce415bc6fc158fda0b82e218/opentelemetry_exporter_http_transport-0.66b2-py3-none-any.whl", hash = "sha256:fd5f5b490c099acda1cd7b909d5e8981436bf18cc8c6098d302d114c271720e9", size = 12154, upload-time = "2026-10-29T17:29:10.244Z" },
]
[package.optional-dependencies]
requests = [
{ name = "requests" },
]
[[package]]
name = "opentelemetry-exporter-otlp-common"
version = "0.66b2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "opentelemetry-sdk" },
]
sdist = { url = "https://files.pythonhosted.org/packages/5a/3c/3f2cc8c42bde2620e65024d71e2eb025f7bd0821bb363b52bcc5a3260dbd/opentelemetry_exporter_otlp_common-0.66b2.tar.gz", hash = "sha256:06f5a9b88638e310efa1f1d206cdf6b75393e112aba4e174a963416192bd1028", size = 14325, upload-time = "2026-10-29T17:29:41.701Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/a8/47/b3049e30b339c82e3c7ec1fc692185a5d5a3ba65a94c570bb39b2c0b8424/opentelemetry_exporter_otlp_common-0.66b2-py3-none-any.whl", hash = "sha256:ace86efb75489f925f1ef809856ae5f0c7db534e4afdc624530222228b1236a5", size = 12385, upload-time = "2026-10-29T17:29:13.667Z" },
]
[[package]]
name = "opentelemetry-exporter-otlp-proto-common"
version = "1.45.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "opentelemetry-proto" },
]
sdist = { url = "https://files.pythonhosted.org/packages/69/58/239c98b36d9ea317098769957043c251703636a26189c884fba46c1dad84/opentelemetry_exporter_otlp_proto_common-1.45.2.tar.gz", hash = "sha256:f1f2806f3f28ce7938033823e50934fcd91595a39de38e69a28a51e19f40fc6d", size = 18873, upload-time = "2026-10-29T17:29:44.496Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/e6/d6/0f30d38120a949aef70528f845bf539f80df62abb4b8e62fdf69c2b6df5a/opentelemetry_exporter_otlp_proto_common-1.45.2-py3-none-any.whl", hash = "sha256:af483b24217028892f017096731b794b196b785025d2e6808874720fd0b05a80", size = 15392, upload-time = "2026-10-29T17:29:17.913Z" },
]
[[package]]
name = "opentelemetry-exporter-otlp-proto-http"
version = "1.45.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "googleapis-common-protos" },
{ name = "opentelemetry-api" },
{ name = "opentelemetry-exporter-http-transport", extra = ["requests"] },
{ name = "opentelemetry-exporter-otlp-common" },
{ name = "opentelemetry-exporter-otlp-proto-common" },
{ name = "opentelemetry-proto" },
{ name = "opentelemetry-sdk" },
{ name = "requests" },
{ name = "typing-extensions" },
]
sdist = { url = "https://files.pythonhosted.org/packages/db/07/b7b01ecb69d02f540e679a9e36f7413d081f225bbbed4469d212ada10bb7/opentelemetry_exporter_otlp_proto_http-1.45.2.tar.gz", hash = "sha256:5984a3fb46bc4628e4e2b85d4a6e72637e03962aae6cf372791137768a4ad939", size = 28843, upload-time = "2026-10-29T17:29:46.15Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/32/65/f64d7d2450217e2989714e1dee15e19bf79a77a313387abac0cac77bc10e/opentelemetry_exporter_otlp_proto_http-1.45.2-py3-none-any.whl", hash = "sha256:6e4d025138829d0ee57946930c2ccad6491ad4d92a958e9c7eea69278fe60cfc", size = 22180, upload-time = "2026-10-29T17:29:20.154Z" },
]
[[package]]
name = "opentelemetry-proto"
version = "1.45.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "protobuf" },
]
sdist = { url = "https://files.pythonhosted.org/packages/24/9c/1aa4ce60e9bc72af20dc49c92cc0566825092d92b3d6a277439fb5fb7c01/opentelemetry_proto-1.45.2.tar.gz", hash = "sha256:bd8d23cf770605b0af9b7be2071d26a464fea289d35429abfd2a66226114ad64", size = 46486, upload-time = "2026-10-29T17:29:53.007Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/7e/0d/a0b8f2b9efe2ec1abdf639d3696db9b1563ebeb11d91aac08ba7341e9122/opentelemetry_proto-1.45.2-py3-none-any.whl", hash = "sha256:03a7ca1b43f89fd5b965d5975902bb2515c0c86e2428b456836e9a6149c6235a", size = 72484, upload-time = "2026-10-29T17:29:31.403Z" },
]
[[package]]
name = "opentelemetry-sdk"
version = "1.45.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "opentelemetry-api" },
{ name = "opentelemetry-semantic-conventions" },
{ name = "typing-extensions" },
]
sdist = { url = "https://files.pythonhosted.org/packages/7b/1a/74a21d4d6969fb8b432ac397e66112a8167a6deb267ea4559dbaf2fe91ef/opentelemetry_sdk-1.45.2.tar.gz", hash = "sha256:7eec4de13dd21ff3a1670dcb0e02079e692736f94d733dfdce5af461d884248d", size = 221705, upload-time = "2026-10-29T17:29:54.685Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/9f/a5/9a3b793ef48245f2336a16beb2324c2397dbb3f987cd68942f77cca06156/opentelemetry_sdk-1.45.2-py3-none-any.whl", hash = "sha256:ff974ea70ee4f1d51e2ec152db37c2b626c7bf82bb3f7d86114fd8704e7199c6", size = 141756, upload-time = "2026-10-29T17:29:33.722Z" },
]
[[package]]
name = "opentelemetry-semantic-conventions"
version = "0.66b2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "opentelemetry-api" },
{ name = "typing-extensions" },
]
sdist = { url = "https://files.pythonhosted.org/packages/37/3f/50f95972b50e8e353f5b9342034c9cd17730f1956f009ce6a3fbbd89f9ce/opentelemetry_semantic_conventions-0.66b2.tar.gz", hash = "sha256:7da5f1a5dc4383eb66711d4d3d3e71824d9403ac1559fea021cc103c1a4c4976", size = 150246, upload-time = "2026-10-29T17:29:55.682Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/67/bd/6bf33ed31521c565931c037e9e81bac47c1acb000e850c6e24220e2a0c00/opentelemetry_semantic_conventions-0.66b2-py3-none-any.whl", hash = "sha256:4cbe61e5f9275d57ab31708446e7938ef4291ebbe6a7fca6f7a629c5acae87d8", size = 206280, upload-time = "2026-10-29T17:29:35.062Z" },
]
[[package]]
name = "packaging"
version = "26.3"
@@ -1024,6 +1154,21 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/f5/cd/785c64ed382f3f04201870267b02783f63b4678c2acfddc177a3ebcc2727/propcache-0.5.4-py3-none-any.whl", hash = "sha256:62c60aec739ed00124573cce1178138fd690c7676352d67a37328c1cf51d7468", size = 16338, upload-time = "2026-09-16T00:17:13.106Z" },
]
[[package]]
name = "protobuf"
version = "7.36.2"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/d9/89/5b8517baa72f84a67b8a307ba953c91057af618bf40bf676f3c03551f8f0/protobuf-7.36.2.tar.gz", hash = "sha256:497d0463ff3316681da6c0b9e8d06cb465d61abce00b613ab42226175644d1bb", size = 512737, upload-time = "2026-09-17T20:07:59.326Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/32/72/98342feb672507c8f3a69e34b4fa8961f608edba5c1a48a6f47156d92cb5/protobuf-7.36.2-cp310-abi3-macosx_10_9_universal2.whl", hash = "sha256:cbc70b17ee27e28894c7fee8bb04be1abead49e936bc70eb60052531eee2079e", size = 456039, upload-time = "2026-09-17T20:07:51.542Z" },
{ url = "https://files.pythonhosted.org/packages/b6/ea/91fdf7c2b8bbd49cde056f00a9df6773532987e1c00fe2830b895af95c7e/protobuf-7.36.2-cp310-abi3-manylinux2014_aarch64.whl", hash = "sha256:e11e1f0180583a2af89db6a2ecd9e8dc40aa6d2988ca175bfd0e6d12ea72d74e", size = 344219, upload-time = "2026-09-17T20:07:52.914Z" },
{ url = "https://files.pythonhosted.org/packages/17/ab/5fd5f8ece73fad885c5a09aa849b32d70472f954ba3a92d3bb5974ea953b/protobuf-7.36.2-cp310-abi3-manylinux2014_s390x.whl", hash = "sha256:f4fee11ec330d238b34a05c9b675f693c20415d1c5bd7d5320cc2f8a798eb9cf", size = 357223, upload-time = "2026-09-17T20:07:53.985Z" },
{ url = "https://files.pythonhosted.org/packages/db/f3/3996583dd2906297a637af12114deddf7658af6e683fedb83be061983fb5/protobuf-7.36.2-cp310-abi3-manylinux2014_x86_64.whl", hash = "sha256:89f23aa53c24553a2416fd4fd1ec06f74fa42b14b546d8883128813f775bbfd2", size = 343223, upload-time = "2026-09-17T20:07:54.931Z" },
{ url = "https://files.pythonhosted.org/packages/fc/1b/dcc64f358fcb51811b58ae40b3d28f820725f116d86487cc20bd4b130701/protobuf-7.36.2-cp310-abi3-win32.whl", hash = "sha256:912c1221170e16c08d1f086762f563dd61ff83c18b5fa6652952dfaded66f728", size = 442998, upload-time = "2026-09-17T20:07:55.826Z" },
{ url = "https://files.pythonhosted.org/packages/8a/55/b77bda4e5e5f5971fb51b07663694690e9afdb9402136c16a522bd621cad/protobuf-7.36.2-cp310-abi3-win_amd64.whl", hash = "sha256:a300819d441e078a5608c0d3c709796bb548136058fda017ae51d425b44fd353", size = 456514, upload-time = "2026-09-17T20:07:57.188Z" },
{ url = "https://files.pythonhosted.org/packages/e4/04/d52c7016b04b6c5108f26691f9d33ec82a9b65d041f1a9c771137693d618/protobuf-7.36.2-py3-none-any.whl", hash = "sha256:bdb3a345d48db958e6ce1f18e508beb0cc981d64f24088427549c866cd039f1e", size = 179806, upload-time = "2026-09-17T20:07:58.211Z" },
]
[[package]]
name = "pycparser"
version = "3.0"