From a4497e3f32f11bed673cb1d099618d2d7abd679b Mon Sep 17 00:00:00 2001 From: roman Date: Wed, 11 Nov 2026 10:19:50 +0300 Subject: [PATCH] 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 --- .claude/rules/api-layer.md | 9 + .claude/rules/bench.md | 7 + .claude/rules/docker.md | 33 +- .claude/rules/infra.md | 9 + .claude/rules/logging.md | 14 + .claude/rules/run-modes.md | 11 + .claude/rules/settings.md | 18 + .claude/rules/student-tests.md | 9 + .claude/rules/telemetry.md | 90 + .claude/rules/worker.md | 9 + .claude/skills/run-mtusi-messenger/SKILL.md | 45 +- .claude/skills/run-mtusi-messenger/driver.py | 2002 +++++++++++++++++ .env.example | 23 +- .github/ci/compose.yml | 55 + .github/ci/stand-env.sh | 10 + AGENTS.md | 60 +- KNOWN_ISSUES.md | 33 +- Makefile | 8 +- QUESTIONS.md | 16 + REPORT.md | 115 + bench/bench.compose.yml | 7 + bench/run.py | 6 +- config_example.toml | 18 + docker-compose.yml | 215 +- evidence/stand/from-scratch.md | 91 + evidence/telemetry/budget.md | 63 + evidence/telemetry/check.md | 148 ++ evidence/telemetry/collector-outage.md | 89 + infra/otel/collector.yaml | 70 + infra/otel/grafana/dashboards.yaml | 17 + .../dashboards/messenger-overview.json | 238 ++ infra/otel/grafana/datasources.yaml | 60 + infra/otel/loki/loki.yaml | 46 + infra/otel/prometheus/prometheus.yml | 30 + infra/otel/tempo/tempo.yaml | 41 + openspec/changes/otel-telemetry/design.md | 47 + openspec/changes/otel-telemetry/tasks.md | 80 +- pyproject.toml | 8 + service-tests/db/test_telemetry_db.py | 131 ++ .../unit/test_attachment_processing.py | 60 +- service-tests/unit/test_telemetry.py | 673 ++++++ src/api/middlewares/request_context.py | 43 +- src/config/settings.py | 76 + src/core/services/attachment_processing.py | 70 +- src/infra/cache/client.py | 76 +- src/infra/db/uow.py | 6 +- src/infra/logger.py | 84 + src/infra/render/client.py | 60 +- src/infra/s3/client.py | 83 +- src/infra/telemetry/__init__.py | 45 + src/infra/telemetry/core.py | 498 ++++ src/infra/telemetry/db.py | 114 + src/infra/telemetry/logs.py | 108 + src/infra/telemetry/setup.py | 36 + src/main.py | 32 +- src/schemas/enums/__init__.py | 2 + src/schemas/enums/attachment.py | 31 + src/utils/constants.py | 77 + src/worker/main.py | 76 +- student-tests/failures.compose.yml | 7 + student-tests/run_isolated.py | 6 + uv.lock | 145 ++ 62 files changed, 6175 insertions(+), 214 deletions(-) create mode 100644 .claude/rules/telemetry.md create mode 100644 evidence/stand/from-scratch.md create mode 100644 evidence/telemetry/budget.md create mode 100644 evidence/telemetry/check.md create mode 100644 evidence/telemetry/collector-outage.md create mode 100644 infra/otel/collector.yaml create mode 100644 infra/otel/grafana/dashboards.yaml create mode 100644 infra/otel/grafana/dashboards/messenger-overview.json create mode 100644 infra/otel/grafana/datasources.yaml create mode 100644 infra/otel/loki/loki.yaml create mode 100644 infra/otel/prometheus/prometheus.yml create mode 100644 infra/otel/tempo/tempo.yaml create mode 100644 service-tests/db/test_telemetry_db.py create mode 100644 service-tests/unit/test_telemetry.py create mode 100644 src/infra/telemetry/__init__.py create mode 100644 src/infra/telemetry/core.py create mode 100644 src/infra/telemetry/db.py create mode 100644 src/infra/telemetry/logs.py create mode 100644 src/infra/telemetry/setup.py diff --git a/.claude/rules/api-layer.md b/.claude/rules/api-layer.md index 785d06b..6daa002 100644 --- a/.claude/rules/api-layer.md +++ b/.claude/rules/api-layer.md @@ -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 процесса, в diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 6573e32..d107d53 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -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.<конфигурация>`); diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index b525d51..46abbfc 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -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` после пересборки пересоздаёт реплики, образ которых diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index bf21073..9a82ed8 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -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`, без diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index 33db48f..7b10275 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -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: сигнал diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index f97097e..ffd5c91 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -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` → diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index a7c66d8..c9fe6a2 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -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`, diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 8cbbcb9..8d437c8 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -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`, diff --git a/.claude/rules/telemetry.md b/.claude/rules/telemetry.md new file mode 100644 index 0000000..fa0b804 --- /dev/null +++ b/.claude/rules/telemetry.md @@ -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 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). diff --git a/.claude/rules/worker.md b/.claude/rules/worker.md index b9cfad4..e6b20f6 100644 --- a/.claude/rules/worker.md +++ b/.claude/rules/worker.md @@ -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)`. diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 00a6f38..c45c5cb 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -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/` сервисы вызываются поверх единицы работы, сервер не diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index e13ee1c..332f4fb 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -224,6 +224,32 @@ загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; сеть и контейнеры удаляются при любом исходе; код 1 при расхождении + telemetry-check только стенд с LB и телеметрией (design change + otel-telemetry, решение 21): через HTTP API Grafana с паролем из + .env — вход (401, 401, 200), порт на 127.0.0.1, источники по uid + и их проверка, dashboard provisioned и неизменяем, цели + Prometheus; свой запрос → stdout → Loki → Tempo (ресурс, span + PostgreSQL и COMMIT), traceparent, BREW, 401, 404; загрузка → + ready → Loki и трасса worker; недекодируемый JPEG → failed; рост + счётчиков по обеим репликам и по исходам; S3 заморожен → 503 и + span S3 с ошибкой; нет трасс health и чужих корней; сети + хранилищ из api и worker; разовый контейнер с OTEL_*; проба + приватности; рестарт Collector и хранилищ → те же наблюдения; + unpause s3 в finally; код 1 при расхождении, 2 — нет стенда + telemetry-outage только стенд с LB и телеметрией: Collector stop, затем + pause — make test, загрузка до ready, записи SDK в stdout за окно, + docker stop реплики и docker compose stop worker (время, код, + запись об остановке), make replicas, возврат Collector и новые + сигналы; все сервисы телеметрии остановлены — restart api worker, + make test, возврат; в finally — unpause и start телеметрии, make + replicas, worker и relay; код 1 при расхождении, 2 — нет стенда + stand-from-scratch [--project P] [--runs 2] свой проект compose (по + умолчанию mtusi-lab6-scratch; рабочий — код 2) на свободных портах + хоста: make run_docker на пустых volumes — код 0, состояния + сервисов, RestartCount брокера и телеметрии 0, нет eacces и + permission denied, provisioning Grafana, make test через свой LB; + затем проект удаляется вместе с volumes при любом исходе, в том + числе по Ctrl+C; код 1 при расхождении stop остановить свой экземпляр на порту all start → flow → smoke → student (если есть student-tests/) → stop @@ -9427,6 +9453,1971 @@ def freeze_lb_rounds( ] +# --- телеметрия (design change otel-telemetry, решение 21) ------------------ + +TELEMETRY_SERVICES = ( + "otel-collector", + "prometheus", + "loki", + "tempo", + "grafana", +) +# Collector и хранилища: их рестарт проверяет историю +TELEMETRY_STORES = ("otel-collector", "prometheus", "loki", "tempo") +GRAFANA_USER = "admin" +GRAFANA_DEFAULT_PORT = 3000 +DATASOURCE_UIDS = ("prometheus", "loki", "tempo") +DASHBOARD_UID = "messenger-overview" +PROMETHEUS_JOBS = ( + "otel-collector", + "otel-collector-exporter", + "loki", + "tempo", + "prometheus", +) +API_SERVICE_NAME = "messenger-api" +WORKER_SERVICE_NAME = "messenger-worker" +# SDK отправляет метрики раз в 15 с, Prometheus забирает раз в 15 с: изменение +# доходит не позже ~30 с; «тихо» — 35 с без изменения +METRIC_QUIET_S = 35 +METRIC_WAIT_S = 120 +# запись и трасса доходят до Loki и Tempo через пакеты SDK (1 с) и Collector +# (1 с); Tempo отдаёт трассу по id после её завершения +SIGNAL_WAIT_S = 60 +SIGNAL_POLL_S = 2 +# сколько GET карточки чата пишет проверка: счёт должен вырасти ровно на столько +TC_CHAT_GETS = 10 +# срок вызова S3 стенда ([s3] timeout_seconds = 5): span S3 при заморозке +TC_S3_SPAN_RANGE = (4.0, 7.5) +UUID_TEXT = re.compile( + r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-" + r"[0-9a-fA-F]{12}", +) +# метки, которых у метрик быть не должно (contracts/observability.md) +FORBIDDEN_LABELS = frozenset( + { + "user_id", + "chat_id", + "message_id", + "attachment_id", + "job_id", + "request_id", + "messenger_request_id", + "url", + "url_full", + "url_path", + "url_query", + "path", + "query", + "filename", + "text", + }, +) +# имя корня трассы: запрос API (метод и шаблон или только метод) и доставка +HTTP_METHODS = ( + "GET", + "POST", + "PUT", + "PATCH", + "DELETE", + "HEAD", + "OPTIONS", + "CONNECT", + "TRACE", + "_OTHER", +) +OTEL_PROBE_VARS = { + "OTEL_SDK_DISABLED": "true", + "OTEL_EXPORTER_OTLP_ENDPOINT": "http://elsewhere.invalid:4318", +} +JPEG_PRECISION_12_PY = """\ +import sys +sys.path.insert(0, "/tmp") +import images +sys.stdout.buffer.write(images.jpeg_precision_12()) +""" +NET_PROBE_PY = """\ +import json, socket +out = {} +for host, port in (("prometheus", 9090), ("loki", 3100), ("tempo", 3200), + ("grafana", 3000), ("otel-collector", 4318)): + try: + addr = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)[0][4] + except OSError: + out[host] = "unresolved" + continue + sock = socket.socket(socket.AF_INET if len(addr) == 2 else socket.AF_INET6) + sock.settimeout(2) + try: + sock.connect(addr) + out[host] = "connected" + except OSError: + out[host] = "unreachable" + finally: + sock.close() +print(json.dumps(out)) +""" +PROBE_REQUEST_PY = """\ +import urllib.error, urllib.request +try: + urllib.request.urlopen("http://127.0.0.1:8080/api/v1/users/me", timeout=5) +except urllib.error.HTTPError as e: + print(e.code) +""" + + +def dotenv_value(name: str, default: str = "") -> str: + """Значение переменной из `.env` рабочего стенда (без раскрытия `${}`); + в вывод не печатается.""" + path = ROOT / ".env" + if not path.exists(): + return default + for line in path.read_text().splitlines(): + if line.startswith(f"{name}="): + return line.split("=", 1)[1].strip() + return default + + +class Grafana: + """HTTP API Grafana на 127.0.0.1 с паролем администратора из `.env`; к + Prometheus, Loki и Tempo — только через её источники (proxy по uid).""" + + def __init__(self) -> None: + self.port = int( + dotenv_value("GRAFANA_OUT_PORT", str(GRAFANA_DEFAULT_PORT)), + ) + self._password = dotenv_value("GRAFANA_ADMIN_PASSWORD") + + def request( + self, + method: str, + path: str, + *, + params: dict[str, object] | None = None, + body: object = None, + auth: str = "admin", + timeout: float = 20, + ) -> tuple[int, object]: + """`auth`: `admin` — пароль из `.env`, `wrong` — неверный, `none` — + без учётных данных.""" + if params: + path += "?" + urllib.parse.urlencode(params) + authorization = None + if auth == "admin": + authorization = basic(GRAFANA_USER, self._password) + elif auth == "wrong": + authorization = basic( + GRAFANA_USER, + "wrong-" + secrets.token_hex(8), + ) + status, _, payload = call( + self.port, + method, + path, + authorization=authorization, + body=body, + timeout=timeout, + ) + return status, payload + + def proxy( + self, + uid: str, + path: str, + params: dict[str, object] | None = None, + ) -> tuple[int, object]: + return self.request( + "GET", + f"/api/datasources/proxy/uid/{uid}{path}", + params=params, + ) + + def prom(self, expr: str, at: float | None = None) -> list[dict]: + params: dict[str, object] = {"query": expr} + if at is not None: + params["time"] = f"{at:.3f}" + status, payload = self.proxy("prometheus", "/api/v1/query", params) + if status != 200 or not isinstance(payload, dict): + raise RuntimeError(f"prometheus query: {status}") + return list(payload["data"]["result"]) + + def prom_sum(self, expr: str, at: float | None = None) -> float: + return sum(float(item["value"][1]) for item in self.prom(expr, at)) + + def prom_by( + self, + expr: str, + label: str, + at: float | None = None, + ) -> dict[str, float]: + out: dict[str, float] = {} + for item in self.prom(expr, at): + key = str(item["metric"].get(label, "")) + out[key] = out.get(key, 0.0) + float(item["value"][1]) + return out + + def series(self, match: str, start: float, end: float) -> list[dict]: + status, payload = self.proxy( + "prometheus", + "/api/v1/series", + {"match[]": match, "start": f"{start:.0f}", "end": f"{end:.0f}"}, + ) + if status != 200 or not isinstance(payload, dict): + raise RuntimeError(f"prometheus series: {status}") + return list(payload["data"]) + + def loki( + self, + query: str, + start: float, + end: float, + *, + limit: int = 1000, + ) -> list[tuple[int, str, dict[str, str]]]: + """Записи Loki по возрастанию времени: (нс, строка, метки и + structured metadata).""" + status, payload = self.proxy( + "loki", + "/loki/api/v1/query_range", + { + "query": query, + "start": str(int(start * 1e9)), + "end": str(int(end * 1e9)), + "limit": str(limit), + "direction": "forward", + }, + ) + if status != 200 or not isinstance(payload, dict): + raise RuntimeError(f"loki query: {status}") + records = [ + (int(ts), line, dict(stream["stream"])) + for stream in payload["data"]["result"] + for ts, line in stream["values"] + ] + return sorted(records, key=lambda record: record[0]) + + def loki_all( + self, + query: str, + start: float, + end: float, + ) -> list[tuple[int, str, dict[str, str]]]: + """Все записи окна страницами по 5000.""" + out: list[tuple[int, str, dict[str, str]]] = [] + cursor = start + for _ in range(100): + page = self.loki(query, cursor, end, limit=5000) + out.extend(page) + if len(page) < 5000: + break + cursor = page[-1][0] / 1e9 + 1e-9 + return out + + def trace(self, trace_id: str) -> tuple[int, object]: + return self.proxy("tempo", f"/api/v2/traces/{trace_id}") + + def search( + self, + query: str, + start: float, + end: float, + *, + limit: int = 500, + ) -> list[dict]: + status, payload = self.proxy( + "tempo", + "/api/search", + { + "q": query, + "start": f"{start:.0f}", + "end": f"{end + 1:.0f}", + "limit": str(limit), + "spss": "1", + }, + ) + if status != 200 or not isinstance(payload, dict): + raise RuntimeError(f"tempo search: {status}") + return list(payload.get("traces") or []) + + +def otlp_value(value: dict) -> object: + for kind in ("stringValue", "boolValue", "doubleValue"): + if kind in value: + return value[kind] + if "intValue" in value: + return int(value["intValue"]) + return json.dumps(value) + + +def otlp_attrs(items: list[dict] | None) -> dict[str, object]: + return {item["key"]: otlp_value(item["value"]) for item in items or []} + + +def b64_hex(value: str) -> str: + """id span в ответе Tempo — base64; пусто — пусто.""" + if not value: + return "" + return base64.b64decode(value).hex() + + +def trace_spans(payload: object) -> list[dict[str, object]]: + """Span трассы Tempo: имя, вид, id, родитель, статус, атрибуты, ресурс, + длительность в секундах.""" + if not isinstance(payload, dict): + return [] + spans = [] + trace = payload.get("trace", payload) + for resource_spans in trace.get("resourceSpans") or []: + resource = otlp_attrs(resource_spans["resource"].get("attributes")) + for scope in resource_spans.get("scopeSpans") or []: + for span in scope.get("spans") or []: + spans.append( + { + "name": span["name"], + "kind": span.get("kind", ""), + "id": b64_hex(span.get("spanId", "")), + "parent": b64_hex(span.get("parentSpanId", "")), + "status": (span.get("status") or {}).get("code", ""), + "attrs": otlp_attrs(span.get("attributes")), + "resource": resource, + "duration": ( + int(span["endTimeUnixNano"]) + - int(span["startTimeUnixNano"]) + ) + / 1e9, + }, + ) + return spans + + +def poll( + fetch: Callable[[], object], + *, + timeout: float = SIGNAL_WAIT_S, + interval: float = SIGNAL_POLL_S, +) -> object: + """Первый непустой результат `fetch` или последний за срок.""" + deadline = time.monotonic() + timeout + while True: + try: + result = fetch() + except (RuntimeError, OSError, http.client.HTTPException): + result = None + if result or time.monotonic() >= deadline: + return result + time.sleep(interval) + + +def settled( + grafana: Grafana, + exprs: dict[str, str], +) -> tuple[dict[str, float], float]: + """Значения выражений Prometheus, которые METRIC_QUIET_S не менялись + (SDK и scrape донесли всё прежнее), и момент снимка.""" + deadline = time.monotonic() + METRIC_WAIT_S + last: dict[str, float] | None = None + since = time.monotonic() + while True: + now = time.time() + values = {name: grafana.prom_sum(e) for name, e in exprs.items()} + if values != last: + last, since = values, time.monotonic() + elif time.monotonic() - since >= METRIC_QUIET_S: + return values, now + if time.monotonic() >= deadline: + return values, now + time.sleep(5) + + +def service_records( + service: str, + since: float, + container: str | None = None, +) -> list[dict[str, object]]: + """Записи stdout сервиса (или контейнера) с момента `since`.""" + stamp = datetime.fromtimestamp(since - 1, UTC).strftime( + "%Y-%m-%dT%H:%M:%SZ", + ) + if container is not None: + args = ["docker", "logs", "--since", stamp, container] + else: + args = [ + "docker", + "compose", + "logs", + "--no-log-prefix", + "--since", + stamp, + service, + ] + proc = subprocess.run( + args, + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + return json_records(proc.stdout + proc.stderr) + + +def short_ids(service: str) -> list[str]: + """Короткие id работающих контейнеров сервиса — их `X-Instance-Id`.""" + return [item[:12] for item in service_ids(service)] + + +def undecodable_jpeg() -> bytes | None: + """JPEG с 12 битами на компоненту тем же генератором, что у тестов: структура + верна, процесс обработки его не декодирует (`invalid_image`).""" + source = ROOT / "student-tests" / "images.py" + proc = subprocess.run( + [ + "docker", + "run", + "--rm", + "--network", + "none", + "-v", + f"{source}:/tmp/images.py:ro", + "--entrypoint", + "python", + "mtusi-messenger:lab6", + "-I", + "-c", + JPEG_PRECISION_12_PY, + ], + capture_output=True, + check=False, + ) + return proc.stdout if proc.returncode == 0 and proc.stdout else None + + +def contract_version() -> str: + spec = json.loads((ROOT / "contracts" / "openapi.json").read_text()) + return str(spec["info"]["version"]) + + +def grafana_ready(grafana: Grafana) -> bool: + status, _ = grafana.request("GET", "/api/health", auth="none") + return status == 200 + + +def datasources_ok(grafana: Grafana) -> bool: + for uid in DATASOURCE_UIDS: + status, payload = grafana.request( + "GET", + f"/api/datasources/uid/{uid}/health", + ) + if status != 200 or not isinstance(payload, dict): + return False + if payload.get("status") != "OK": + return False + return True + + +def targets_up(grafana: Grafana) -> dict[str, str]: + """Цель Prometheus → `up` (1 / 0 / нет).""" + results = grafana.prom("up") + up = {str(item["metric"].get("job")): item["value"][1] for item in results} + return {job: str(up.get(job, "absent")) for job in PROMETHEUS_JOBS} + + +def loki_request( + grafana: Grafana, + request_id: str, + start: float, + *, + service: str = API_SERVICE_NAME, + event: str | None = None, +) -> list[tuple[int, str, dict[str, str]]]: + """Записи запроса R в Loki (поле `request_id` — structured metadata).""" + query = f'{{service_name="{service}"}} | request_id="{request_id}"' + + def fetch() -> list[tuple[int, str, dict[str, str]]]: + records = grafana.loki(query, start, time.time() + 5) + if event is not None: + records = [r for r in records if r[1] == event] + return records + + return poll(fetch) or [] # type: ignore[return-value] + + +def tempo_trace(grafana: Grafana, trace_id: str) -> list[dict[str, object]]: + """Трасса с корнем: дочерние span заканчиваются раньше корня и могут прийти + другим пакетом, поэтому трасса без корня — ещё не вся.""" + + def fetch() -> list[dict[str, object]]: + status, payload = grafana.trace(trace_id) + spans = trace_spans(payload) if status == 200 else [] + return spans if root_span(spans) else [] + + return poll(fetch) or [] # type: ignore[return-value] + + +def root_span(spans: list[dict[str, object]]) -> dict[str, object]: + roots = [span for span in spans if not span["parent"]] + return roots[0] if len(roots) == 1 else {} + + +def cmd_telemetry_check(port: int) -> int: + """Спеки `observability`, `service-logging`, `service-configuration` на + рабочем стенде (design change `otel-telemetry`, решение 21). Всё — через + HTTP API Grafana с паролем из `.env`; секретов и токенов в выводе нет.""" + if not stand_answers(port, "telemetry-check"): + return 2 + grafana = Grafana() + if not grafana_ready(grafana): + print(f"telemetry-check: no Grafana on 127.0.0.1:{grafana.port}") + return 2 + paused: list[str] = [] + + def body() -> int: + try: + return telemetry_check(port, grafana, paused) + finally: + with signals_ignored(): + for service in paused: + detached("docker", "compose", "unpause", service) + print(f"unpaused {service}", flush=True) + + return rc_signals(body) + + +def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: + started = time.time() + rows: list[tuple[str, str, str]] = [] + + def step(name: str, expected: object, got: object) -> None: + rows.append((name, str(expected), str(got))) + mark = "" if str(expected) == str(got) else " <- differs" + print(f"{name}: {got}{mark}", flush=True) + + version = contract_version() + # --- Grafana: вход, порт, источники, dashboard ------------------------- + step( + "grafana without credentials", + 401, + grafana.request("GET", "/api/datasources", auth="none")[0], + ) + step( + "grafana wrong password", + 401, + grafana.request("GET", "/api/datasources", auth="wrong")[0], + ) + step( + "grafana password from .env", + 200, + grafana.request("GET", "/api/datasources")[0], + ) + published = compose("port", "grafana", "3000").strip() + step( + "grafana published only on 127.0.0.1", + "yes", + yes( + bool(published) + and all( + line.startswith("127.0.0.1:") + for line in published.splitlines() + ), + ), + ) + for uid in DATASOURCE_UIDS: + status, payload = grafana.request("GET", f"/api/datasources/uid/{uid}") + step( + f"datasource {uid}", + f"200 {uid}", + f"{status} {payload.get('type') if isinstance(payload, dict) else ''}", + ) + status, payload = grafana.request( + "GET", + f"/api/datasources/uid/{uid}/health", + ) + step( + f"datasource {uid} health", + "OK", + payload.get("status") if isinstance(payload, dict) else status, + ) + status, dashboard = grafana.request( + "GET", + f"/api/dashboards/uid/{DASHBOARD_UID}", + ) + meta = dashboard.get("meta", {}) if isinstance(dashboard, dict) else {} + step("dashboard from git", 200, status) + step("dashboard provisioned", "True", meta.get("provisioned")) + step("dashboard folder", "Messenger", meta.get("folderTitle")) + model = ( + dashboard.get("dashboard", {}) if isinstance(dashboard, dict) else {} + ) + title = model.get("title") + changed = {**model, "title": f"{title} edited"} + status, _ = grafana.request( + "POST", + "/api/dashboards/db", + body={"dashboard": changed, "overwrite": True}, + ) + step( + "save of the provisioned dashboard rejected", + "yes", + yes(status >= 400), + ) + _, again = grafana.request("GET", f"/api/dashboards/uid/{DASHBOARD_UID}") + step( + "dashboard equals git after the attempt", + "yes", + yes(isinstance(again, dict) and again["dashboard"]["title"] == title), + ) + expressions = [ + target["expr"] + for panel in model.get("panels", []) + for target in panel.get("targets", []) + if (target.get("datasource") or {}).get("uid") == "prometheus" + ] + up = targets_up(grafana) + for job, value in up.items(): + step(f"prometheus target {job} up", "1", value) + + # --- база метрик до своего трафика ----------------------------------- + chat_route = '"/api/v1/chats/{chat_id}"' + chat_expr = ( + "http_server_request_duration_seconds_count" + f'{{job="{API_SERVICE_NAME}",http_route={chat_route},' + 'http_request_method="GET",http_response_status_code="200"}' + ) + jobs_expr = ( + "messenger_job_duration_seconds_count" + f'{{job="{WORKER_SERVICE_NAME}",' + 'messenger_job_type="attachment.process.v1",' + 'messenger_job_outcome="{outcome}"}' + ) + exprs = { + "chat": chat_expr, + "ready": jobs_expr.replace("{outcome}", "ready"), + "failed": jobs_expr.replace("{outcome}", "failed"), + } + print("waiting for metrics to settle before own traffic", flush=True) + base, _ = settled(grafana, exprs) + base_by = grafana.prom_by(chat_expr, "instance") + + # --- свой трафик: проба приватности, запрос, задание -------------------- + username = f"tcu_{secrets.token_hex(6)}" + password = f"TcPw-{secrets.token_hex(12)}" + status, _, user = call( + port, + "POST", + USERS, + body={ + "username": username, + "display_name": "Telemetry check", + "password": password, + }, + ) + step("register probe user", 201, status) + status, _, session = call( + port, + "POST", + SESSIONS, + authorization=basic(username, password), + ) + step("login by Basic", 201, status) + if not isinstance(user, dict) or not isinstance(session, dict): + return report_reconcile(rows) + token = str(session["token"]) + status, _, chat = call( + port, + "POST", + CHATS, + token=token, + body={"title": "telemetry", "member_ids": [user["id"]]}, + ) + step("create chat", 201, status) + if not isinstance(chat, dict): + return report_reconcile(rows) + chat_id = str(chat["id"]) + text = f"tc-message-{secrets.token_hex(8)}" + key = f"tc-key-{secrets.token_hex(8)}" + status, hdrs, message = call( + port, + "POST", + f"{CHATS}/{chat_id}/messages", + token=token, + body={"text": text}, + extra=key_header(key), + ) + step("send message", 201, status) + request_id = hdrs.get("x-request-id", "") + instance_id = hdrs.get("x-instance-id", "") + print(f"message request {request_id} via {instance_id}", flush=True) + for _ in range(TC_CHAT_GETS): + call(port, "GET", f"{CHATS}/{chat_id}", token=token) + step("401 without token", 401, call(port, "GET", f"{USERS}/me")[0]) + step( + "404 of an unknown chat", + 404, + call(port, "GET", f"{CHATS}/{uuid.uuid4()}", token=token)[0], + ) + odd_uuid = str(uuid.uuid4()) + # BREW парсер HTTP uvicorn (httptools) отклоняет 400 ещё до приложения: + # ни span, ни ряда — проверяется только отсутствие BREW и UUID в метках. + # Метод вне стандартного набора, который доходит до приложения, — + # PROPFIND (design change otel-telemetry, «Уточнения apply») + status, _, _ = call(port, "BREW", f"/api/v1/teapots/{odd_uuid}") + step("BREW rejected by the HTTP parser before the app", 400, status) + status, _, _ = call(port, "PROPFIND", f"/api/v1/teapots/{odd_uuid}") + step("PROPFIND of an unknown path with a UUID", 404, status) + foreign = secrets.token_hex(16) + status, tp_hdrs, _ = call( + port, + "GET", + f"{USERS}/me", + token=token, + extra={"traceparent": f"00-{foreign}-{secrets.token_hex(8)}-01"}, + ) + step("request with traceparent", 200, status) + filename = f"tc-file-{secrets.token_hex(6)}.png" + data = FIXTURE_PNG.read_bytes() + status, _, accepted = upload_bytes( + port, + token, + chat_id, + data, + content_type="image/png", + filename=filename, + ) + step("upload sample.png", ATTACHMENT_ACCEPTED, status) + attachment_id = ( + str(accepted["id"]) if isinstance(accepted, dict) else "missing" + ) + ready = wait_attachment(port, token, attachment_id) + step("attachment becomes ready", "ready", ready.get("status")) + jpeg = undecodable_jpeg() + step("undecodable JPEG generated", "yes", yes(jpeg is not None)) + failed_id = "" + if jpeg is not None: + status, _, accepted = upload_bytes( + port, + token, + chat_id, + jpeg, + content_type="image/jpeg", + filename="tc-undecodable.jpg", + ) + step("upload undecodable JPEG", ATTACHMENT_ACCEPTED, status) + if isinstance(accepted, dict): + failed_id = str(accepted["id"]) + failed = wait_attachment(port, token, failed_id) + step( + "undecodable JPEG becomes failed", + "failed", + failed.get("status"), + ) + + # --- stdout и Loki: записи запроса ------------------------------------ + stdout = [ + record + for record in service_records("api", started) + if record.get("request_id") == request_id + ] + pairs = {(r.get("trace_id"), r.get("span_id")) for r in stdout} + step("stdout records of the request", "yes", yes(len(stdout) >= 2)) + step("one trace_id and span_id in them", "1", len(pairs)) + trace_id = str(next(iter(pairs))[0]) if len(pairs) == 1 else "" + step( + "trace_id format", + "yes", + yes(bool(re.fullmatch("[0-9a-f]{32}", trace_id))), + ) + final = next( + (r for r in stdout if r.get("event") == "HTTP request completed"), + {}, + ) + found = loki_request( + grafana, + request_id, + started, + event="HTTP request completed", + ) + step("Loki record of the request", "1", len(found)) + if found: + _, line, labels = found[0] + step("Loki service_name", API_SERVICE_NAME, labels.get("service_name")) + step( + "Loki service_instance_id = X-Instance-Id", + instance_id, + labels.get("service_instance_id"), + ) + step( + "Loki instance_id = X-Instance-Id", + instance_id, + labels.get("instance_id"), + ) + step("Loki trace_id = stdout", trace_id, labels.get("trace_id")) + same = all( + str(labels.get(field)) == str(final.get(field)) + for field in ("method", "path", "status", "duration_ms") + ) + step( + "Loki event, method, path, status, duration = stdout", + "yes", + yes(same and line == final.get("event")), + ) + spans = tempo_trace(grafana, trace_id) if trace_id else [] + root = root_span(spans) + step( + "Tempo server span", + "POST /api/v1/chats/{chat_id}/messages SPAN_KIND_SERVER", + f"{root.get('name')} {root.get('kind')}", + ) + attrs = root.get("attrs", {}) if root else {} + step( + "server span status code", + "201", + attrs.get("http.response.status_code"), + ) + step( + "server span request id = X-Request-Id", + request_id, + attrs.get("messenger.request_id"), + ) + resource = root.get("resource", {}) if root else {} + step( + "resource service.name", + API_SERVICE_NAME, + resource.get("service.name"), + ) + step( + "resource service.instance.id", + instance_id, + resource.get("service.instance.id"), + ) + step( + "resource service.version = contract", + version, + resource.get("service.version"), + ) + step( + "resource deployment.environment.name", + "lab", + resource.get("deployment.environment.name"), + ) + children = [span for span in spans if span["parent"] == root.get("id")] + step( + "PostgreSQL query spans under it", + "yes", + yes( + any( + span["attrs"].get("db.system.name") == "postgresql" + and span["name"] != "COMMIT" + for span in children + ), + ), + ) + step( + "COMMIT span under it", + "yes", + yes(any(span["name"] == "COMMIT" for span in children)), + ) + + # --- чужой traceparent ------------------------------------------------- + tp_records = loki_request( + grafana, + tp_hdrs.get("x-request-id", ""), + started, + ) + tp_trace = tp_records[0][2].get("trace_id") if tp_records else "" + step( + "traceparent request has its own trace", + "yes", + yes(bool(tp_trace) and tp_trace != foreign), + ) + # неизвестный id Tempo 3.1 отдаёт 200 с пустой трассой + step( + "spans of the foreign trace-id in Tempo", + "0", + len(trace_spans(grafana.trace(foreign)[1])), + ) + tp_spans = tempo_trace(grafana, str(tp_trace)) if tp_trace else [] + step( + "its server span has no parent", + "yes", + yes(bool(root_span(tp_spans))), + ) + + # --- worker: запись и трасса задания ----------------------------------- + worker_found = ( + poll( + lambda: [ + r + for r in grafana.loki( + f'{{service_name="{WORKER_SERVICE_NAME}"}} ' + f'| attachment_id="{attachment_id}"', + started, + time.time() + 5, + ) + if r[1] == "Attachment became ready" + ], + ) + or [] + ) + step("Loki worker record of the attachment", "1", len(worker_found)) + job_trace = worker_found[0][2].get("trace_id", "") if worker_found else "" + worker_stdout = [ + r + for r in service_records("worker", started) + if r.get("attachment_id") == attachment_id + and r.get("event") + in ("Started job attempt", "Attachment became ready") + ] + step( + "worker stdout records carry the job trace_id", + "yes", + yes( + len(worker_stdout) >= 2 + and all(r.get("trace_id") == job_trace for r in worker_stdout), + ), + ) + job_spans = tempo_trace(grafana, str(job_trace)) if job_trace else [] + job_root = root_span(job_spans) + step( + "Tempo consumer span", + "SPAN_KIND_CONSUMER ready", + f"{job_root.get('kind')} " + f"{(job_root.get('attrs') or {}).get('messenger.job.outcome')}", + ) + step( + "worker resource service.name", + WORKER_SERVICE_NAME, + (job_root.get("resource") or {}).get("service.name"), + ) + names = [str(span["name"]) for span in job_spans] + step( + "job spans: PostgreSQL", + "yes", + yes( + any( + s["attrs"].get("db.system.name") == "postgresql" + for s in job_spans + ), + ), + ) + step( + "job spans: S3.GetObject (staging)", + "yes", + yes("S3.GetObject" in names), + ) + step( + "job spans: S3.PutObject (original and 3 variants)", + "yes", + yes(names.count("S3.PutObject") >= 4), + ) + step( + "job spans: render process", + "yes", + yes("render attachment variants" in names), + ) + + # --- S3 заморожен: 503 и span S3 с ошибкой ------------------------------ + paused.append("s3") + compose("pause", "s3") + try: + status, s3_hdrs, _ = upload_bytes( + port, + token, + chat_id, + data, + content_type="image/png", + filename="tc-s3-paused.png", + ) + finally: + compose("unpause", "s3") + paused.remove("s3") + step("upload with S3 paused", 503, status) + # итоговая запись пишется после отправки ответа: ждать её + s3_records = ( + poll( + lambda: [ + r + for r in service_records("api", started) + if r.get("request_id") == s3_hdrs.get("x-request-id") + and r.get("trace_id") + ], + timeout=10, + interval=0.5, + ) + or [] + ) + s3_spans = ( + tempo_trace(grafana, str(s3_records[0]["trace_id"])) + if s3_records + else [] + ) + s3_root = root_span(s3_spans) + step("its server span status", "STATUS_CODE_ERROR", s3_root.get("status")) + s3_failed = [ + s + for s in s3_spans + if str(s["name"]).startswith("S3.") + and s["status"] == "STATUS_CODE_ERROR" + ] + step("S3 span with error", "yes", yes(bool(s3_failed))) + low, high = TC_S3_SPAN_RANGE + step( + f"S3 span duration within {low}-{high} s", + "yes", + yes(any(low <= float(s["duration"]) <= high for s in s3_failed)), + ) + step( + "error.type of the S3 span set", + "yes", + yes( + all("error.type" in s["attrs"] for s in s3_failed) + and bool(s3_failed), + ), + ) + + # --- трассы health и корни из одного span PostgreSQL -------------------- + now = time.time() + health = grafana.search('{ span.http.route =~ "/health.*" }', started, now) + health += grafana.search('{ name =~ ".*/health/.*" }', started, now) + step("health traces in Tempo", "0", len(health)) + roots = grafana.search("{ }", started, now, limit=2000) + odd_roots = [] + for item in roots: + name = str(item.get("rootTraceName", "")) + head = name.split(" ", 1)[0] + if head in HTTP_METHODS or name.startswith("process "): + # имя из одного метода — и запрос без маршрута, и span Valkey + # (GET) или SQL (DELETE): решает вид корня + if " " not in name: + spans_of = trace_spans(grafana.trace(item["traceID"])[1]) + if root_span(spans_of).get("kind") != "SPAN_KIND_SERVER": + odd_roots.append(name) + continue + odd_roots.append(name) + step("trace roots other than requests and deliveries", "0", len(odd_roots)) + if odd_roots: + print(f" odd roots: {sorted(set(odd_roots))[:10]}") + + # --- сети: хранилища недоступны приложению ----------------------------- + for service in ("api", "worker"): + ids = service_ids(service) + if not ids: + step(f"{service} container", "running", "missing") + continue + proc = subprocess.run( + ["docker", "exec", "-i", ids[0], "python", "-I", "-"], + input=NET_PROBE_PY, + capture_output=True, + text=True, + check=False, + ) + try: + reach = json.loads(proc.stdout.strip().splitlines()[-1]) + except (json.JSONDecodeError, IndexError): + reach = {} + for host in ("prometheus", "loki", "tempo", "grafana"): + step( + f"{service} -> {host}", + "not reachable", + "not reachable" + if reach.get(host) in ("unresolved", "unreachable") + else reach.get(host), + ) + step( + f"{service} -> otel-collector:4318", + "connected", + reach.get("otel-collector"), + ) + + # --- OTEL_* в окружении не действуют ----------------------------------- + rows.extend(otel_env_probe(grafana)) + + # --- метрики: рост и метки --------------------------------------------- + print("waiting for metrics to settle after own traffic", flush=True) + after, at = settled(grafana, exprs) + after_by = grafana.prom_by(chat_expr, "instance", at) + step( + f"chat GET 200 count grew by {TC_CHAT_GETS}", + str(TC_CHAT_GETS), + f"{after['chat'] - base['chat']:g}", + ) + replicas = short_ids("api") + grown = [ + instance + for instance in replicas + if after_by.get(instance, 0) > base_by.get(instance, 0) + ] + step("count grew on every replica", str(len(replicas)), len(grown)) + step("jobs ready grew by 1", "1", f"{after['ready'] - base['ready']:g}") + step("jobs failed grew by 1", "1", f"{after['failed'] - base['failed']:g}") + other = grafana.prom( + "http_server_request_duration_seconds_count" + f'{{job="{API_SERVICE_NAME}",http_request_method="_OTHER"}}', + ) + step( + "_OTHER series without http_route", + "yes", + yes( + bool(other) + and all("http_route" not in o["metric"] for o in other), + ), + ) + for code, route in ( + ("401", "/api/v1/users/me"), + ("404", "/api/v1/chats/{chat_id}"), + ): + found_code = grafana.prom( + "http_server_request_duration_seconds_count" + f'{{job="{API_SERVICE_NAME}",http_response_status_code="{code}",' + f'http_route="{route}"}}', + ) + step(f"{code} series of {route}", "yes", yes(bool(found_code))) + labels = grafana.series( + '{job=~"messenger-.*"}', + started - 600, + time.time(), + ) + names_seen = {name for item in labels for name in item} + bad_names = sorted(names_seen & FORBIDDEN_LABELS) + step("forbidden label names", "[]", bad_names) + values = [str(v) for item in labels for v in item.values()] + step( + "label values that are UUIDs", + "0", + sum(bool(UUID_TEXT.search(v)) for v in values), + ) + step( + "label values with BREW, PROPFIND or the odd UUID", + "0", + sum("BREW" in v or "PROPFIND" in v or odd_uuid in v for v in values), + ) + errors = 0 + for expr in expressions: + result_status, result = grafana.proxy( + "prometheus", + "/api/v1/query", + {"query": expr}, + ) + if result_status != 200 or not isinstance(result, dict): + errors += 1 + print(f" panel query failed: {expr[:80]}") + step( + f"dashboard panel queries ({len(expressions)}) without error", + "0", + errors, + ) + empty = [ + expr + for expr in expressions + if "4.." not in expr + and "5.." not in expr + and "failed|" not in expr + and not grafana.prom(expr) + ] + step( + "panel queries with data after traffic", + "[]", + [expr[:60] for expr in empty], + ) + + # --- проба приватности --------------------------------------------------- + end = time.time() + 5 + needles = { + "U": username, + "P": password, + "T": token, + "M": text, + "K": key, + "F": filename, + "Bearer": "Bearer ", + "Basic": "Basic ", + "foreign trace-id": foreign, + } + logs = grafana.loki_all('{service_name=~"messenger-.*"}', started, end) + log_dump = json.dumps([[line, labels] for _, line, labels in logs]) + traces = grafana.search("{ }", started, end, limit=2000) + trace_dump = json.dumps( + [grafana.trace(item["traceID"])[1] for item in traces], + ) + label_dump = json.dumps(labels) + print( + f"privacy probe: {len(logs)} Loki records, {len(traces)} traces, " + f"{len(labels)} series", + flush=True, + ) + for name, needle in needles.items(): + hits = [ + where + for where, dump in ( + ("loki", log_dump), + ("tempo", trace_dump), + ("prometheus", label_dump), + ) + if needle in dump + ] + step(f"{name} in telemetry", "[]", hits) + + # --- история после рестарта Collector и хранилищ ------------------------ + saved_at = at + saved_value = grafana.prom_sum(chat_expr, saved_at) + print("docker compose restart " + " ".join(TELEMETRY_STORES), flush=True) + compose("restart", *TELEMETRY_STORES, timeout=180) + step( + "pipeline back after restart", + "yes", + yes( + bool( + poll( + lambda: ( + datasources_ok(grafana) + and all(v == "1" for v in targets_up(grafana).values()) + ), + timeout=120, + interval=3, + ), + ), + ), + ) + again = loki_request( + grafana, + request_id, + started, + event="HTTP request completed", + ) + step( + "same Loki record after restart", + "yes", + yes(bool(again) and again[0][2].get("trace_id") == trace_id), + ) + again_spans = tempo_trace(grafana, trace_id) if trace_id else [] + step( + "same trace after restart", + "yes", + yes(root_span(again_spans).get("id") == root.get("id") and bool(root)), + ) + step( + "same metric value at the saved time", + f"{saved_value:g}", + f"{grafana.prom_sum(chat_expr, saved_at):g}", + ) + return report_reconcile( + rows, + passed="own request and job are found in Loki, Tempo and " + "Prometheus through Grafana, no secrets in telemetry", + ) + + +def otel_env_probe(grafana: Grafana) -> list[tuple[str, str, str]]: + """Разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом: шлёт + в Collector из `[telemetry]` и пишет `warning` с именами переменных.""" + rows: list[tuple[str, str, str]] = [] + project = json.loads(compose("config", "--format", "json"))["name"] + instance = f"otelprobe{secrets.token_hex(4)}" + name = f"{project}-{instance}" + args = ["docker", "compose", "run", "-d", "--no-deps", "--name", name] + for var, value in OTEL_PROBE_VARS.items(): + args += ["-e", f"{var}={value}"] + args += ["-e", f"APP__INSTANCE_ID={instance}", "api"] + started = time.time() + try: + code, _ = detached(*args, timeout=120) + rows.append(("probe container with OTEL_* started", "0", str(code))) + healthy = poll( + lambda: ( + subprocess.run( + [ + "docker", + "inspect", + "-f", + "{{.State.Health.Status}}", + name, + ], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + == "healthy" + ), + timeout=60, + interval=1, + ) + rows.append(("probe container healthy", "yes", yes(bool(healthy)))) + proc = subprocess.run( + ["docker", "exec", "-i", name, "python", "-I", "-"], + input=PROBE_REQUEST_PY, + capture_output=True, + text=True, + check=False, + ) + rows.append(("probe request inside", "401", proc.stdout.strip())) + records = service_records("api", started, container=name) + warning = next( + ( + r + for r in records + if r.get("event") == "Ignored OpenTelemetry environment " + "variables" + ), + {}, + ) + rows.append(("warning level", "warning", str(warning.get("level")))) + rows.append( + ( + "warning names the variables", + str(sorted(OTEL_PROBE_VARS)), + str(warning.get("names")), + ), + ) + rows.append( + ( + "no variable values in stdout", + "yes", + yes( + not any( + value in json.dumps(records) + for value in ("elsewhere.invalid",) + ), + ), + ), + ) + found = ( + poll( + lambda: grafana.loki( + f'{{service_instance_id="{instance}"}}', + started, + time.time() + 5, + ), + ) + or [] + ) + rows.append( + ( + "probe records reach Loki from [telemetry]", + "yes", + yes(bool(found)), + ), + ) + rows.append( + ( + "probe service_name", + API_SERVICE_NAME, + str(found[0][2].get("service_name")) if found else "none", + ), + ) + finally: + with signals_ignored(): + detached("docker", "rm", "-f", name) + for row in rows: + print(f"{row[0]}: {row[2]}", flush=True) + return rows + + +# остановка процесса по SIGTERM — прежний срок (спек graceful-shutdown) +TO_STOP_LIMIT_S = 10 +# записи модуля SDK в stdout: не чаще одной в минуту (окно фильтра) +TO_SDK_WINDOW_S = 60 +# сколько держать Collector недоступным, чтобы экспорт успел отказать +TO_OUTAGE_HOLD_S = 20 + + +def make_test(port: int) -> tuple[int, str]: + """`make test` против LB: код и последняя строка вывода.""" + proc = subprocess.run( + ["make", "test", f"BASE_URL=http://localhost:{port}"], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + timeout=300, + ) + lines = (proc.stdout + proc.stderr).strip().splitlines() + return proc.returncode, lines[-1] if lines else "" + + +def timed_stop(container: str) -> tuple[float, str, bool, str]: + """`docker stop` контейнера: секунды, код выхода, есть ли запись об + остановке в stdout, её событие.""" + started = time.monotonic() + detached("docker", "stop", "--timeout", str(TO_STOP_LIMIT_S), container) + took = time.monotonic() - started + code = subprocess.run( + ["docker", "inspect", "-f", "{{.State.ExitCode}}", container], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + logs = subprocess.run( + ["docker", "logs", "--tail", "40", container], + capture_output=True, + text=True, + check=False, + ) + events = [str(r.get("event")) for r in json_records(logs.stdout)] + stopped = next( + (e for e in events if e in ("Stopped API", "Stopped worker")), + "", + ) + return took, code, bool(stopped), stopped + + +def sdk_record_counts(since: float) -> dict[str, int]: + """Записи логгеров `opentelemetry.*` в stdout с момента `since`: + «контейнер логгер» → число.""" + counts: dict[str, int] = {} + for service in ("api", "worker"): + for container in service_ids(service): + for record in service_records(service, since, container=container): + logger_name = str(record.get("logger", "")) + if logger_name.startswith("opentelemetry"): + key = f"{container[:12]} {logger_name}" + counts[key] = counts.get(key, 0) + 1 + return counts + + +def signals_back( + grafana: Grafana, + port: int, + token: str, + chat_id: str, + since: float, +) -> list[tuple[str, str, str]]: + """После возврата Collector: новый запрос в Loki, новая трасса задания, + свежие ряды API и worker в Prometheus.""" + rows: list[tuple[str, str, str]] = [] + _, hdrs, _ = call(port, "GET", f"{USERS}/me", token=token) + found = loki_request(grafana, hdrs.get("x-request-id", ""), since) + rows.append(("API record reaches Loki again", "yes", yes(bool(found)))) + trace_id = found[0][2].get("trace_id", "") if found else "" + rows.append( + ( + "API trace reaches Tempo again", + "yes", + yes(bool(trace_id) and bool(tempo_trace(grafana, str(trace_id)))), + ), + ) + status, _, ready = upload_ready( + port, + token, + chat_id, + FIXTURE_PNG.read_bytes(), + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + attachment_id = ready.get("id") if isinstance(ready, dict) else "" + worker = poll( + lambda: grafana.loki( + f'{{service_name="{WORKER_SERVICE_NAME}"}} ' + f'| attachment_id="{attachment_id}"', + since, + time.time() + 5, + ), + ) + rows.append(("worker record reaches Loki again", "yes", yes(bool(worker)))) + for name, expr in ( + ( + "API", + f'http_server_request_duration_seconds_count{{job="{API_SERVICE_NAME}"}}', + ), + ( + "worker", + f'messenger_job_duration_seconds_count{{job="{WORKER_SERVICE_NAME}"}}', + ), + ): + fresh = poll( + lambda expr=expr: ( + grafana.prom_sum(f"max(timestamp({expr}))") > since + ), + timeout=METRIC_WAIT_S, + interval=5, + ) + rows.append((f"{name} metrics scraped again", "yes", yes(bool(fresh)))) + return rows + + +def cmd_telemetry_outage(port: int) -> int: + """Спеки `observability` «Collector остановлен» / «заморожен», + `service-logging` «Отказ отправки журнала», `container-run` «Приложение без + телеметрии», `graceful-shutdown` (design change `otel-telemetry`, решение + 21). Стенд возвращается в `finally`: Collector разморожен и запущен, + сервисы телеметрии, реплики и worker работают.""" + if not stand_answers(port, "telemetry-outage"): + return 2 + grafana = Grafana() + if not grafana_ready(grafana): + print(f"telemetry-outage: no Grafana on 127.0.0.1:{grafana.port}") + return 2 + + def body() -> int: + try: + return telemetry_outage(port, grafana) + finally: + with signals_ignored(): + detached("docker", "compose", "unpause", "otel-collector") + detached("docker", "compose", "start", *TELEMETRY_SERVICES) + detached("make", "replicas", timeout=180) + running = ensure_running("worker", "relay") + print( + "restored: telemetry services started, replicas and " + f"worker running: {yes(running)}", + flush=True, + ) + + return rc_signals(body) + + +def telemetry_outage(port: int, grafana: Grafana) -> int: + rows: list[tuple[str, str, str]] = [] + people = attachment_people(port, "to") + if people is None: + return 1 + _, tokens, chat_id = people + token = tokens["alice"] + + def add(new: list[tuple[str, str, str]]) -> None: + for row in new: + rows.append(row) + print(f"{row[0]}: {row[2]}", flush=True) + + for mode in ("stop", "pause"): + prefix = f"[collector {mode}] " + since = time.time() + action = "stop" if mode == "stop" else "pause" + compose(action, "otel-collector") + print(f"{prefix}docker compose {action} otel-collector", flush=True) + code, last = make_test(port) + add([(prefix + "make test", "0 PASS", f"{code} {last.split(':')[0]}")]) + add( + [ + ( + prefix + "/health/ready", + "200", + str(call(port, "GET", "/health/ready")[0]), + ), + ], + ) + _, hdrs, _ = call(port, "GET", f"{USERS}/me", token=token) + request_id = hdrs.get("x-request-id", "") + status, _, ready = upload_ready( + port, + token, + chat_id, + FIXTURE_PNG.read_bytes(), + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + add( + [ + ( + prefix + "upload becomes ready", + "yes", + yes(isinstance(ready, dict)), + ), + ], + ) + hold = TO_OUTAGE_HOLD_S - (time.time() - since) + if hold > 0: + time.sleep(hold) + records = service_records("api", since) + add( + [ + ( + prefix + "own request record in stdout", + "yes", + yes( + any( + r.get("request_id") == request_id for r in records + ), + ), + ), + ], + ) + elapsed = time.time() - since + counts = sdk_record_counts(since) + allowed = int(elapsed // TO_SDK_WINDOW_S) + 1 + print(f"{prefix}SDK records in {elapsed:.0f} s: {counts}", flush=True) + add( + [ + ( + prefix + f"SDK records per logger at most {allowed}", + "yes", + yes(all(n <= allowed for n in counts.values())), + ), + ], + ) + replica = service_ids("api")[0] + took, exit_code, stopped, _ = timed_stop(replica) + print( + f"{prefix}docker stop api {replica[:12]}: {took:.2f} s", + flush=True, + ) + add( + [ + ( + prefix + + f"docker stop api faster than {TO_STOP_LIMIT_S} s", + "yes", + yes(took < TO_STOP_LIMIT_S), + ), + (prefix + "api exit code", "0", exit_code), + (prefix + "Stopped API in stdout", "yes", yes(stopped)), + ], + ) + worker = service_ids("worker")[0] + started = time.monotonic() + detached("docker", "compose", "stop", "worker") + took = time.monotonic() - started + exit_code = subprocess.run( + ["docker", "inspect", "-f", "{{.State.ExitCode}}", worker], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + logs = subprocess.run( + ["docker", "logs", "--tail", "20", worker], + capture_output=True, + text=True, + check=False, + ).stdout + print(f"{prefix}docker compose stop worker: {took:.2f} s", flush=True) + add( + [ + ( + prefix + f"stop worker faster than {TO_STOP_LIMIT_S} s", + "yes", + yes(took < TO_STOP_LIMIT_S), + ), + (prefix + "worker exit code", "0", exit_code), + ( + prefix + "Stopped worker in stdout", + "yes", + yes( + any( + r.get("event") == "Stopped worker" + for r in json_records(logs) + ), + ), + ), + ], + ) + detached("make", "replicas", timeout=180) + add( + [ + ( + prefix + "worker started again", + "yes", + yes(ensure_running("worker")), + ), + ], + ) + add([(prefix + "LB ready", "yes", yes(wait_lb_ready(port)))]) + back = time.time() + compose("start" if mode == "stop" else "unpause", "otel-collector") + print(f"{prefix}otel-collector back", flush=True) + add( + [ + (prefix + row[0], row[1], row[2]) + for row in signals_back(grafana, port, token, chat_id, back) + ], + ) + + # --- все сервисы телеметрии остановлены, приложение перезапущено -------- + prefix = "[telemetry down] " + config = json.loads(compose("config", "--format", "json")) + app_deps = sorted( + { + dep + for name, service in config["services"].items() + if name not in TELEMETRY_SERVICES + for dep in (service.get("depends_on") or {}) + if dep in TELEMETRY_SERVICES + }, + ) + add([(prefix + "app services depend on telemetry", "[]", str(app_deps))]) + compose("stop", *TELEMETRY_SERVICES, timeout=120) + print(f"{prefix}docker compose stop {' '.join(TELEMETRY_SERVICES)}") + since = time.time() + code, _ = detached( + "docker", + "compose", + "restart", + "api", + "worker", + timeout=180, + ) + add([(prefix + "docker compose restart api worker", "0", str(code))]) + add([(prefix + "LB ready", "yes", yes(wait_lb_ready(port)))]) + starts = [ + r + for r in service_records("api", since) + if r.get("event") == "Started API" + ] + add( + [ + ( + prefix + "replicas started", + str(len(service_ids("api"))), + str(len(starts)), + ), + ], + ) + worker_start = poll( + lambda: [ + r + for r in service_records("worker", since) + if r.get("event") == "Started worker" + ], + timeout=30, + interval=1, + ) + add([(prefix + "worker started", "yes", yes(bool(worker_start)))]) + code, last = make_test(port) + add([(prefix + "make test", "0 PASS", f"{code} {last.split(':')[0]}")]) + back = time.time() + compose("start", *TELEMETRY_SERVICES, timeout=180) + add( + [ + ( + prefix + "Grafana back", + "yes", + yes( + bool( + poll( + lambda: ( + grafana_ready(grafana) + and datasources_ok(grafana) + ), + timeout=120, + interval=3, + ), + ), + ), + ), + ], + ) + add( + [ + (prefix + row[0], row[1], row[2]) + for row in signals_back(grafana, port, token, chat_id, back) + ], + ) + return report_reconcile( + rows, + passed="API and worker work and stop in time without the Collector, " + "signals come back without restarts", + ) + + +SCRATCH_PROJECT = "mtusi-lab6-scratch" +SCRATCH_PORTS = ( + "APP_OUT_PORT", + "POSTGRES_OUT_PORT", + "VALKEY_OUT_PORT", + "S3_OUT_PORT", + "RABBITMQ_OUT_PORT", + "GRAFANA_OUT_PORT", +) +# сервисы, у которых проверяется счётчик перезапусков +SCRATCH_NO_RESTART = ("rabbitmq", *TELEMETRY_STORES, "grafana") +SCRATCH_ONE_OFF = ("migrate", "s3-bootstrap") +SCRATCH_SETTLE_S = 30 +PERMISSION_ERRORS = re.compile(r"eacces|permission denied", re.IGNORECASE) + + +def free_port() -> int: + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + return int(sock.getsockname()[1]) + + +def cmd_stand_from_scratch(project: str, runs: int) -> int: + """Спек `container-run`, «Стенд с нуля одной командой» (design change + `otel-telemetry`, решения 19 и 21): свой проект compose на пустых volumes, + `make run_docker` с первой попытки, затем проект удаляется вместе с volumes + при любом исходе. Рабочий стенд не трогается.""" + working = json.loads( + subprocess.run( + ["docker", "compose", "config", "--format", "json"], + cwd=ROOT, + capture_output=True, + text=True, + check=True, + ).stdout, + )["name"] + if project == working: + print(f"stand-from-scratch: {project} is the working stand, refused") + return 2 + env = {**os.environ, "COMPOSE_PROJECT_NAME": project} + + def scratch(*args: str, timeout: float = 300) -> tuple[int, str]: + proc = subprocess.run( + ["docker", "compose", "-p", project, *args], + cwd=ROOT, + env=env, + capture_output=True, + text=True, + check=False, + timeout=timeout, + ) + return proc.returncode, proc.stdout + proc.stderr + + def remove() -> None: + # только свой проект: имя проверено выше, -p — явно + with signals_ignored(): + code, out = scratch("down", "-v", "--remove-orphans", timeout=300) + print(f"down -v {project}: code {code}", flush=True) + if code != 0: + print(out[-500:]) + + rows: list[tuple[str, str, str]] = [] + + def working_ids() -> list[str]: + return sorted( + subprocess.run( + ["docker", "compose", "ps", "-a", "-q"], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ).stdout.split(), + ) + + def body() -> int: + before = working_ids() + print(f"working stand {working}: {len(before)} containers", flush=True) + remove() + for run in range(1, runs + 1): + try: + rows.extend(scratch_run(project, run, env, scratch)) + finally: + remove() + leftovers = subprocess.run( + [ + "docker", + "volume", + "ls", + "-q", + "--filter", + f"label=com.docker.compose.project={project}", + ], + capture_output=True, + text=True, + check=False, + ).stdout.split() + rows.append((f"run {run}: volumes left", "0", str(len(leftovers)))) + rows.append( + ( + f"working stand {working}: same container IDs", + "yes", + yes(working_ids() == before), + ), + ) + return report_reconcile( + rows, + passed=f"make run_docker on empty volumes passed {runs} times " + "at the first attempt", + ) + + return rc_signals(body) + + +def scratch_run( + project: str, + run: int, + env: dict[str, str], + scratch: Callable[..., tuple[int, str]], +) -> list[tuple[str, str, str]]: + rows: list[tuple[str, str, str]] = [] + prefix = f"run {run}: " + + def add(name: str, expected: object, got: object) -> None: + rows.append((prefix + name, str(expected), str(got))) + print(f"{prefix}{name}: {got}", flush=True) + + ports = {name: free_port() for name in SCRATCH_PORTS} + volumes = subprocess.run( + [ + "docker", + "volume", + "ls", + "-q", + "--filter", + f"label=com.docker.compose.project={project}", + ], + capture_output=True, + text=True, + check=False, + ).stdout.split() + add("project volumes before", "0", len(volumes)) + started = time.monotonic() + proc = subprocess.run( + ["make", "run_docker", *(f"{k}={v}" for k, v in ports.items())], + cwd=ROOT, + env=env, + capture_output=True, + text=True, + check=False, + timeout=900, + ) + add("make run_docker exit code", "0", proc.returncode) + print(f"{prefix}make run_docker took {time.monotonic() - started:.0f} s") + if proc.returncode != 0: + print(proc.stdout[-1500:] + proc.stderr[-1500:]) + return rows + time.sleep(SCRATCH_SETTLE_S) + _, out = scratch("ps", "-a", "--format", "json") + containers = [ + json.loads(line) for line in out.splitlines() if line.startswith("{") + ] + states: dict[str, list[str]] = {} + for item in containers: + states.setdefault(item["Service"], []).append( + f"{item['State']}:{item.get('ExitCode', '')}", + ) + config = json.loads(scratch("config", "--format", "json")[1]) + for service in sorted(config["services"]): + got = states.get(service, ["missing"]) + expected = "exited:0" if service in SCRATCH_ONE_OFF else "running:0" + add(f"{service} state", expected, ",".join(sorted(set(got)))) + for service in SCRATCH_NO_RESTART: + ids = [item["ID"] for item in containers if item["Service"] == service] + counts = [ + subprocess.run( + ["docker", "inspect", "-f", "{{.RestartCount}}", cid], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + for cid in ids + ] + add(f"{service} RestartCount", "0", ",".join(counts) or "missing") + _, logs = scratch("logs", "--no-color", timeout=120) + hits = [ + line for line in logs.splitlines() if PERMISSION_ERRORS.search(line) + ] + add("eacces / permission denied in logs", "0", len(hits)) + for line in hits[:5]: + print(f" {line[:200]}") + grafana = Grafana() + grafana.port = ports["GRAFANA_OUT_PORT"] + ready = poll( + lambda: grafana_ready(grafana) and datasources_ok(grafana), + timeout=120, + interval=3, + ) + add("grafana datasources provisioned and healthy", "yes", yes(bool(ready))) + status, dashboard = grafana.request( + "GET", + f"/api/dashboards/uid/{DASHBOARD_UID}", + ) + add( + "dashboard provisioned", + "200 True", + f"{status} " + f"{(dashboard.get('meta') or {}).get('provisioned') if isinstance(dashboard, dict) else ''}", + ) + code, last = make_test(ports["APP_OUT_PORT"]) + add("make test through its LB", "0 PASS", f"{code} {last.split(':')[0]}") + return rows + + def main() -> int: parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument("--port", type=int, default=DEFAULT_PORT) @@ -9529,6 +11520,11 @@ def main() -> int: default="mtusi-messenger:lab6", help="образ заглушки реплики (нужен только python)", ) + sub.add_parser("telemetry-check") + sub.add_parser("telemetry-outage") + scratch = sub.add_parser("stand-from-scratch") + scratch.add_argument("--project", default=SCRATCH_PROJECT) + scratch.add_argument("--runs", type=int, default=2) stop = sub.add_parser("stop-at-start") stop.add_argument("--image", default="mtusi-messenger:lab6") stop.add_argument( @@ -9650,6 +11646,12 @@ def main() -> int: ) if args.cmd == "lb-upload-timeouts": return cmd_lb_upload_timeouts(args.config, args.image) + if args.cmd == "telemetry-check": + return cmd_telemetry_check(port) + if args.cmd == "telemetry-outage": + return cmd_telemetry_outage(port) + if args.cmd == "stand-from-scratch": + return cmd_stand_from_scratch(args.project, args.runs) if args.cmd == "stop-at-start": return cmd_stop_at_start( args.image, diff --git a/.env.example b/.env.example index b179447..7ac9e90 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/.github/ci/compose.yml b/.github/ci/compose.yml index 5067d22..489f12f 100644 --- a/.github/ci/compose.yml +++ b/.github/ci/compose.yml @@ -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 diff --git a/.github/ci/stand-env.sh b/.github/ci/stand-env.sh index c8ab7cf..c9059b5 100644 --- a/.github/ci/stand-env.sh +++ b/.github/ci/stand-env.sh @@ -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 с: diff --git a/AGENTS.md b/AGENTS.md index 8a1c7a3..f4949f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 pipeline-state` | только чтение, JSON: задания по состояниям, due, ждущие срока, опубликованные и не взятые, истёкшие аренды, возраст старейшего, очередь | | `driver.py --port worker-memory` | память контейнера worker (~35 с): на девять случаев в пределах контракта два одинаковых файла разом, новая cgroup на случай; `memory.peak`, `VmHWM`, `render_peak`, OOM, сумма пиков меньше 1 ГБ; worker и relay запускаются при любом исходе; `evidence/worker/memory.md` | | `driver.py freeze-sessions [--rounds 6] [--settle 15]` | сессии PostgreSQL и журнал пула после заморозки (~2,5 мин), работает и на рабочем стенде: приложение в процессе одноразового контейнера `api`, PostgreSQL только через TCP-прокси пробы, заморожен прокси, а не сервер; режимы — между блоками и до запросов при пуле 2 и 4; `evidence/storage/freeze-sessions.md` | +| `driver.py --port telemetry-check` | телеметрия рабочего стенда через HTTP API Grafana с паролем из `.env` (~2 мин, change `otel-telemetry`): вход, порт, источники, dashboard provisioned и неизменяем, цели Prometheus; свой запрос → stdout → Loki → Tempo, traceparent, нестандартный метод, 401, 404; загрузка → трасса worker, недекодируемый JPEG → `failed`; рост счётчиков по репликам и исходам; S3 заморожен → span S3 с ошибкой (`unpause` в `finally`); сети хранилищ из api и worker, разовый контейнер с `OTEL_*`, проба приватности, рестарт Collector и хранилищ; `evidence/telemetry/check.md` | +| `driver.py --port telemetry-outage` | Collector `stop` и `pause` (~2,5 мин): `make test`, загрузка до `ready`, записи SDK в stdout, `docker stop` реплики и worker быстрее 10 с с кодом 0; все сервисы телеметрии остановлены — рестарт api и worker, `make test`; сигналы снова приходят; стенд возвращается в `finally`; `evidence/telemetry/collector-outage.md` | +| `driver.py 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_`: настоящая единица работы, тот же контракт repo на SQL, соединение на шаг и общий срок JSON-запроса в процессе (S3 и кэш — фейки), замороженный сервер — TCP-прокси; база удаляется при любом исходе, имя не по шаблону — код 2 | | `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_/` (`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/.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/.py # AbstractRepository: абстрактные методы, докстринг — контракт (None, False, условие перехода); импорты — только DTO, enum, src.utils @@ -586,25 +598,26 @@ src/ exceptions/.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(): 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/.py # DTO между repo → service → api - enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head) + enums/.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_ на каждый сервис, 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_ на каждый сервис, 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- с лимитом 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-, 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 # найденные попутно дефекты, не исправленные без просьбы ``` diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index 0be3362..a24ef8d 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -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 дольше срока контейнера diff --git a/Makefile b/Makefile index 90c2b19..ec8751d 100644 --- a/Makefile +++ b/Makefile @@ -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 \ diff --git a/QUESTIONS.md b/QUESTIONS.md index 35ed5b1..6bef943 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -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`. diff --git a/REPORT.md b/REPORT.md index b97ae42..ff5c740 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 | diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 6e399db..8b77f6d 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -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: diff --git a/bench/run.py b/bench/run.py index 0f79370..0c3e5ed 100644 --- a/bench/run.py +++ b/bench/run.py @@ -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, diff --git a/config_example.toml b/config_example.toml index 2b9768c..d70d41f 100644 --- a/config_example.toml +++ b/config_example.toml @@ -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 diff --git a/docker-compose.yml b/docker-compose.yml index 3ee0ec3..8520a58 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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: diff --git a/evidence/stand/from-scratch.md b/evidence/stand/from-scratch.md new file mode 100644 index 0000000..7fe6172 --- /dev/null +++ b/evidence/stand/from-scratch.md @@ -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 состояние одно. diff --git a/evidence/telemetry/budget.md b/evidence/telemetry/budget.md new file mode 100644 index 0000000..49010d2 --- /dev/null +++ b/evidence/telemetry/budget.md @@ -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`) всех контейнеров рабочего стенда. diff --git a/evidence/telemetry/check.md b/evidence/telemetry/check.md new file mode 100644 index 0000000..bd4d18f --- /dev/null +++ b/evidence/telemetry/check.md @@ -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` запроса). diff --git a/evidence/telemetry/collector-outage.md b/evidence/telemetry/collector-outage.md new file mode 100644 index 0000000..b9ecb15 --- /dev/null +++ b/evidence/telemetry/collector-outage.md @@ -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. diff --git a/infra/otel/collector.yaml b/infra/otel/collector.yaml new file mode 100644 index 0000000..53a9be5 --- /dev/null +++ b/infra/otel/collector.yaml @@ -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] diff --git a/infra/otel/grafana/dashboards.yaml b/infra/otel/grafana/dashboards.yaml new file mode 100644 index 0000000..320ec1b --- /dev/null +++ b/infra/otel/grafana/dashboards.yaml @@ -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 diff --git a/infra/otel/grafana/dashboards/messenger-overview.json b/infra/otel/grafana/dashboards/messenger-overview.json new file mode 100644 index 0000000..49a859b --- /dev/null +++ b/infra/otel/grafana/dashboards/messenger-overview.json @@ -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" + } + ] + } + ] +} diff --git a/infra/otel/grafana/datasources.yaml b/infra/otel/grafana/datasources.yaml new file mode 100644 index 0000000..b36e8fe --- /dev/null +++ b/infra/otel/grafana/datasources.yaml @@ -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 diff --git a/infra/otel/loki/loki.yaml b/infra/otel/loki/loki.yaml new file mode 100644 index 0000000..3a9b004 --- /dev/null +++ b/infra/otel/loki/loki.yaml @@ -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 diff --git a/infra/otel/prometheus/prometheus.yml b/infra/otel/prometheus/prometheus.yml new file mode 100644 index 0000000..cf23b73 --- /dev/null +++ b/infra/otel/prometheus/prometheus.yml @@ -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"] diff --git a/infra/otel/tempo/tempo.yaml b/infra/otel/tempo/tempo.yaml new file mode 100644 index 0000000..e4f3e36 --- /dev/null +++ b/infra/otel/tempo/tempo.yaml @@ -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 diff --git a/openspec/changes/otel-telemetry/design.md b/openspec/changes/otel-telemetry/design.md index 95440ea..2df511e 100644 --- a/openspec/changes/otel-telemetry/design.md +++ b/openspec/changes/otel-telemetry/design.md @@ -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 и временная база. diff --git a/openspec/changes/otel-telemetry/tasks.md b/openspec/changes/otel-telemetry/tasks.md index 5baa864..41de34d 100644 --- a/openspec/changes/otel-telemetry/tasks.md +++ b/openspec/changes/otel-telemetry/tasks.md @@ -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 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 telemetry-check` (21): Grafana API с паролем из `.env` (вход: без учётных данных и с +- [x] 7.1 `driver.py --port 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 telemetry-outage` (21): Collector `stop` → `make test`, загрузка до `ready`, записи SDK об +- [x] 7.2 `driver.py --port 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`. diff --git a/pyproject.toml b/pyproject.toml index 4808f9c..347df8a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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] diff --git a/service-tests/db/test_telemetry_db.py b/service-tests/db/test_telemetry_db.py new file mode 100644 index 0000000..e59baf5 --- /dev/null +++ b/service-tests/db/test_telemetry_db.py @@ -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 == () diff --git a/service-tests/unit/test_attachment_processing.py b/service-tests/unit/test_attachment_processing.py index 792b0da..d56475a 100644 --- a/service-tests/unit/test_attachment_processing.py +++ b/service-tests/unit/test_attachment_processing.py @@ -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: diff --git a/service-tests/unit/test_telemetry.py b/service-tests/unit/test_telemetry.py new file mode 100644 index 0000000..21052c5 --- /dev/null +++ b/service-tests/unit/test_telemetry.py @@ -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() diff --git a/src/api/middlewares/request_context.py b/src/api/middlewares/request_context.py index 1f251af..6f1b349 100644 --- a/src/api/middlewares/request_context.py +++ b/src/api/middlewares/request_context.py @@ -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), ) diff --git a/src/config/settings.py b/src/config/settings.py index 01af2f3..50b9da0 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -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( diff --git a/src/core/services/attachment_processing.py b/src/core/services/attachment_processing.py index 15799d2..c1146d9 100644 --- a/src/core/services/attachment_processing.py +++ b/src/core/services/attachment_processing.py @@ -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; её прерывает diff --git a/src/infra/cache/client.py b/src/infra/cache/client.py index 5d0dd00..1d25d53 100644 --- a/src/infra/cache/client.py +++ b/src/infra/cache/client.py @@ -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() diff --git a/src/infra/db/uow.py b/src/infra/db/uow.py index d30126d..2aa7f96 100644 --- a/src/infra/db/uow.py +++ b/src/infra/db/uow.py @@ -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() diff --git a/src/infra/logger.py b/src/infra/logger.py index 3354ad5..5039d00 100644 --- a/src/infra/logger.py +++ b/src/infra/logger.py @@ -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 diff --git a/src/infra/render/client.py b/src/infra/render/client.py index df8a8fb..f9266c1 100644 --- a/src/infra/render/client.py +++ b/src/infra/render/client.py @@ -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 diff --git a/src/infra/s3/client.py b/src/infra/s3/client.py index aa5d90c..f301d17 100644 --- a/src/infra/s3/client.py +++ b/src/infra/s3/client.py @@ -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, diff --git a/src/infra/telemetry/__init__.py b/src/infra/telemetry/__init__.py new file mode 100644 index 0000000..ca7bf8f --- /dev/null +++ b/src/infra/telemetry/__init__.py @@ -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", +] diff --git a/src/infra/telemetry/core.py b/src/infra/telemetry/core.py new file mode 100644 index 0000000..119a1c6 --- /dev/null +++ b/src/infra/telemetry/core.py @@ -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 diff --git a/src/infra/telemetry/db.py b/src/infra/telemetry/db.py new file mode 100644 index 0000000..a767854 --- /dev/null +++ b/src/infra/telemetry/db.py @@ -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", + }, + ) diff --git a/src/infra/telemetry/logs.py b/src/infra/telemetry/logs.py new file mode 100644 index 0000000..f789e60 --- /dev/null +++ b/src/infra/telemetry/logs.py @@ -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() diff --git a/src/infra/telemetry/setup.py b/src/infra/telemetry/setup.py new file mode 100644 index 0000000..03239a0 --- /dev/null +++ b/src/infra/telemetry/setup.py @@ -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 diff --git a/src/main.py b/src/main.py index 4b48e82..f867d47 100644 --- a/src/main.py +++ b/src/main.py @@ -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) diff --git a/src/schemas/enums/__init__.py b/src/schemas/enums/__init__.py index 4137113..b850ad0 100644 --- a/src/schemas/enums/__init__.py +++ b/src/schemas/enums/__init__.py @@ -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", diff --git a/src/schemas/enums/attachment.py b/src/schemas/enums/attachment.py index 2845392..08d7cb9 100644 --- a/src/schemas/enums/attachment.py +++ b/src/schemas/enums/attachment.py @@ -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): """Тип изображения, определённый по содержимому.""" diff --git a/src/utils/constants.py b/src/utils/constants.py index 3274eb8..351328f 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -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 символа, строчные латинские буквы, # цифры, точка и дефис, по краям — буква или цифра diff --git a/src/worker/main.py b/src/worker/main.py index 6f0df7c..bed1718 100644 --- a/src/worker/main.py +++ b/src/worker/main.py @@ -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() diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index 731844a..b87cec8 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -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 с): занижать сроки ради diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 9ace09f..96eada7 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -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, ) diff --git a/uv.lock b/uv.lock index 0842a84..f873385 100644 --- a/uv.lock +++ b/uv.lock @@ -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"