17 KiB
Отчёт — лабораторная 6
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Наблюдаемость
Change otel-telemetry (design — openspec/changes/archive/2026-11-11-otel-telemetry/design.md,
номера решений в скобках). Числа и проверки сняты на закоммиченном коде при чистом рабочем дереве:
telemetry-check и telemetry-outage — на 68f1e97 (правки verify), бюджет — на 4178b3d
(лимиты Tempo и Grafana по замеру), шапки файлов evidence/telemetry/. evidence/stand/from- scratch.md ещё снят на рабочем дереве поверх 9b35c25: пересъёмка ждёт разрешения пользователя
(QUESTIONS.md, ## otel-telemetry, вопрос 8).
Назначение компонентов
| Компонент | Версия (тег, 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 / 640, Grafana 0,5 / 512 — 2,5 CPU / 2304 МиБ. Постоянные лимиты стенда — 11,5 CPU /
7296 МиБ, с одноразовыми — 12,5 CPU / 7680 МиБ при ВМ 12 CPU / 7934 МиБ: лимиты — потолки, а не
резерв. Два замера под make test + make load + make student_test с телеметрией и без
(evidence/telemetry/budget.md): на 68f1e97 (прежние лимиты) пики memory.peak Tempo 398 и
Grafana 294 МиБ — правило «лимит не меньше 1,5 × пика» не выполнялось при 512 и 384, лимиты
подняты до 640 и 512, GOMEMLIMIT Tempo прежний (400 МиБ — его пик упирается в него, поэтому
лимит — 1,6 × GOMEMLIMIT); на 4178b3d (новые лимиты) — Collector 97, Prometheus 95, Loki 190,
Tempo 253, Grafana 248 МиБ, правило выполнено и для наибольших пиков обоих замеров. Реплика API —
до 453 МиБ с телеметрией и 482 без неё (лимит 512; пик даёт Argon2id входов make student_test,
а не SDK; запас ~6 % — ограничение, лимит реплики не менялся), worker — 502 МиБ из 1024. Грубая
цена SDK (один прогон make load): 489 против 568 запросов/с, p95 13,8 против 8,8 мс —
исследование трека 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 |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| TODO | TODO | TODO | TODO |
Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.