fix: address otel-telemetry verify findings

Shutdown budget leaves room for SDK shutdown, stand-from-scratch accepts only
its throwaway project, OTLP exporters ignore proxy environment, telemetry-check
covers log/trace links, health series and worker instance id; spec deltas
match what the parser and SDK lifetime allow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 10:54:14 +03:00
co-authored by Claude Opus 5.5
parent a4497e3f32
commit 68f1e9794e
16 changed files with 486 additions and 34 deletions
+2 -1
View File
@@ -103,7 +103,8 @@ Design change `otel-telemetry`, решения 8, 13, 20. Консоль (`make
run_worker`) — без телеметрии: «Started API» говорит `telemetry_enabled: false`, к run_worker`) — без телеметрии: «Started API» говорит `telemetry_enabled: false`, к
`127.0.0.1:4318` обращений нет. На стенде compose её включает окружение `api` и `worker`. `127.0.0.1:4318` обращений нет. На стенде compose её включает окружение `api` и `worker`.
Остановка: API закрывает SDK после «Stopped API» и ждёт не дольше Остановка: API закрывает SDK после «Stopped API» и ждёт не дольше
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с; 8 с дренажа + 1 с < 10 с), worker — в окне `gather` `TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с; 8 с дренажа + 1 с < 10 с; дренаж 9 с с телеметрией —
ошибка настроек, `settings.md`), worker — в окне `gather`
закрытия клиентов (0,5 с; худший случай прежний, 9,5 с); `shutdown()` провайдеров — в закрытия клиентов (0,5 с; худший случай прежний, 9,5 с); `shutdown()` провайдеров — в
daemon-потоках, процесс их не ждёт. Без Collector и при замороженном Collector сроки прежние daemon-потоках, процесс их не ждёт. Без Collector и при замороженном Collector сроки прежние
(`driver.py telemetry-outage`). (`driver.py telemetry-outage`).
+6 -1
View File
@@ -253,7 +253,12 @@ run_relay` — те же мосты. Имена skeleton: `BROKER_URL_FILE` →
compose (`x-telemetry-env`: `TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`), в `.env` и compose (`x-telemetry-env`: `TELEMETRY__ENABLED`, `TELEMETRY__OTLP_ENDPOINT`), в `.env` и
`config_example.toml` включения нет: файл монтируется и в консоль. Разовая подмена — `config_example.toml` включения нет: файл монтируется и в консоль. Разовая подмена —
`TELEMETRY__*`. **`OTEL_*` — не настройки**, как любые переменные без секции: процесс с `TELEMETRY__*`. **`OTEL_*` — не настройки**, как любые переменные без секции: процесс с
включённой телеметрией удаляет их из окружения и пишет `warning` с именами. Имена skeleton: включённой телеметрией удаляет их из окружения и пишет `warning` с именами; прокси окружения
(`HTTP(S)_PROXY`) экспортёры тоже не берут (`trust_env=False`). Сочетание секций: с включённой
телеметрией `[app] graceful_shutdown_seconds` не больше `API_STOP_BUDGET_SECONDS −
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` = 8 (валидатор поля `telemetry` в `Settings`, ошибка называет
`app.graceful_shutdown_seconds`), без неё — прежние 9 (design change `otel-telemetry`,
«Уточнения apply», п. 13). Имена skeleton:
`OTEL_SERVICE_NAME` → константы `TELEMETRY_SERVICE_API` / `_WORKER`, `OTEL_SERVICE_NAME` → константы `TELEMETRY_SERVICE_API` / `_WORKER`,
`OTEL_EXPORTER_OTLP_ENDPOINT` → `otlp_endpoint`, `OTEL_EXPORTER_OTLP_PROTOCOL` — постоянно `OTEL_EXPORTER_OTLP_ENDPOINT` → `otlp_endpoint`, `OTEL_EXPORTER_OTLP_PROTOCOL` — постоянно
`http/protobuf`, `OTEL_RESOURCE_ATTRIBUTES` → `environment` (`service.*` вычисляет код). `http/protobuf`, `OTEL_RESOURCE_ATTRIBUTES` → `environment` (`service.*` вычисляет код).
+6 -1
View File
@@ -48,7 +48,12 @@ paths:
- **Закрытие со сроком** (решение 13): `shutdown()` провайдеров — в daemon-потоках - **Закрытие со сроком** (решение 13): `shutdown()` провайдеров — в daemon-потоках
(`begin_shutdown`), ожидание не дольше срока (`wait_closed`), не `asyncio.to_thread` и не (`begin_shutdown`), ожидание не дольше срока (`wait_closed`), не `asyncio.to_thread` и не
`force_flush`: при замороженном Collector `shutdown()` ждёт до 6 с. API — после «Stopped API», `force_flush`: при замороженном Collector `shutdown()` ждёт до 6 с. API — после «Stopped API»,
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с); worker — в окне `gather` закрытия (0,5 с). `TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` (1 с) внутри `API_STOP_BUDGET_SECONDS` (9 с) вместе с
дренажом — сочетание проверяет `Settings`; worker — в окне `gather` закрытия (0,5 с). Новый срок
в остановке — в этот бюджет, а не сверх него.
- **Отправка только в Collector:** экспортёры получают свою `requests.Session` с
`trust_env=False` (`_export_session`): прокси, `NO_PROXY` и `.netrc` окружения на неё не
действуют, как и `OTEL_*`.
- **Исход доставки** (решение 11) называет сервис (`JobDeliveryOutcome`), действие с сообщением - **Исход доставки** (решение 11) называет сервис (`JobDeliveryOutcome`), действие с сообщением
выводится из него; span и histogram пишет точка входа после места конкуренции, `error` — у выводится из него; span и histogram пишет точка входа после места конкуренции, `error` — у
непредвиденного исключения. непредвиденного исключения.
+13 -6
View File
@@ -480,10 +480,15 @@ python3 .claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2
- **`telemetry-check`** — всё через HTTP API Grafana (источники-прокси Prometheus, Loki, Tempo): - **`telemetry-check`** — всё через HTTP API Grafana (источники-прокси Prometheus, Loki, Tempo):
вход 401 / 401 / 200, порт только на `127.0.0.1`, источники по uid и их проверка, dashboard вход 401 / 401 / 200, порт только на `127.0.0.1`, источники по uid и их проверка, dashboard
provisioned и отказ его сохранения, цели Prometheus `up`; затем «тихая» база счётчиков (35 с без provisioned и отказ его сохранения, цели Prometheus `up`; затем «тихая» база счётчиков (35 с без
изменений), свой пользователь, сообщение, 10 GET чата, 401, 404, `BREW` и `PROPFIND`, изменений), свой пользователь, сообщение, 10 GET чата, 401, 404, `PROPFIND` и `GET` к
`traceparent`, загрузка и недекодируемый JPEG (12 бит, генератор тестов в образе API). неизвестному пути с UUID (ряды `_OTHER` и `GET` без `http_route` выросли на 1; `BREW` —
Сверяет stdout ↔ Loki ↔ Tempo по `X-Request-Id`, трассу worker по `attachment_id`, рост только 400 парсера, ограничение), `traceparent`, загрузка и недекодируемый JPEG (12 бит,
счётчиков ровно на свои запросы и задания по обеим репликам, span S3 с ошибкой при `docker генератор тестов в образе API). Сверяет stdout ↔ Loki ↔ Tempo по `X-Request-Id`, переходы лог
↔ трасса источников Grafana (derived field Loki → `tempo`; запрос `tracesToLogsV2` источника
Tempo с подстановкой span трассы возвращает её записи), трассу worker по `attachment_id` и
`service.instance.id` worker = `instance_id` его stdout, рост счётчиков ровно на свои запросы
и задания по обеим репликам, нет рядов `http_route=~"/health.*"` за срок хранения, span S3 с
ошибкой при `docker
compose pause s3` (`unpause` в `finally`), отсутствие трасс health и чужих корней, сети compose pause s3` (`unpause` в `finally`), отсутствие трасс health и чужих корней, сети
хранилищ из `api` и `worker`, разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом, хранилищ из `api` и `worker`, разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом,
пробу приватности (U, P, T, M, K, F, `Bearer `, `Basic ` по всем записям Loki, трассам Tempo и пробу приватности (U, P, T, M, K, F, `Bearer `, `Basic ` по всем записям Loki, трассам Tempo и
@@ -495,8 +500,10 @@ python3 .claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2
worker»), `make replicas`, возврат Collector — новые запись, трасса и ряды; затем все сервисы worker»), `make replicas`, возврат Collector — новые запись, трасса и ряды; затем все сервисы
телеметрии остановлены — `docker compose restart api worker`, `make test`, возврат. В `finally` телеметрии остановлены — `docker compose restart api worker`, `make test`, возврат. В `finally`
— `unpause`, `start` телеметрии, `make replicas`, worker и relay. — `unpause`, `start` телеметрии, `make replicas`, worker и relay.
- **`stand-from-scratch`** — только свой проект (`--project`, по умолчанию `mtusi-lab6-scratch`; - **`stand-from-scratch`** — только свой одноразовый проект: `--project` принимает лишь имя
рабочий — код 2): `make run_docker` с `COMPOSE_PROJECT_NAME` и свободными портами хоста, затем `^mtusi-lab6-scratch(-[a-z0-9]+)?$` (по умолчанию `mtusi-lab6-scratch`), иное — `mtusi-lab6`,
`mtusi-lab5`, `mtusi-lab6-failures` — код 2 до любых вызовов docker: команда сама делает `down
-v` своего проекта. Затем `make run_docker` с `COMPOSE_PROJECT_NAME` и свободными портами хоста, затем
состояния, `RestartCount`, `eacces` / `permission denied` в журналах, provisioning Grafana, состояния, `RestartCount`, `eacces` / `permission denied` в журналах, provisioning Grafana,
`make test` через свой LB; `down -v` своего проекта в начале, после каждого прогона и при `make test` через свой LB; `down -v` своего проекта в начале, после каждого прогона и при
Ctrl+C. Рабочий стенд лучше остановить заранее (`make stop`): два стенда — 14 ГиБ лимитов на ВМ Ctrl+C. Рабочий стенд лучше остановить заранее (`make stop`): два стенда — 14 ГиБ лимитов на ВМ
+136 -8
View File
@@ -229,7 +229,9 @@
.env — вход (401, 401, 200), порт на 127.0.0.1, источники по uid .env — вход (401, 401, 200), порт на 127.0.0.1, источники по uid
и их проверка, dashboard provisioned и неизменяем, цели и их проверка, dashboard provisioned и неизменяем, цели
Prometheus; свой запрос → stdout → Loki → Tempo (ресурс, span Prometheus; свой запрос → stdout → Loki → Tempo (ресурс, span
PostgreSQL и COMMIT), traceparent, BREW, 401, 404; загрузка → PostgreSQL и COMMIT), ссылки лог ↔ трасса источников Grafana,
traceparent, PROPFIND и GET к неизвестному пути (BREW —
ограничение), 401, 404, нет рядов health; загрузка →
ready → Loki и трасса worker; недекодируемый JPEG → failed; рост ready → Loki и трасса worker; недекодируемый JPEG → failed; рост
счётчиков по обеим репликам и по исходам; S3 заморожен → 503 и счётчиков по обеим репликам и по исходам; S3 заморожен → 503 и
span S3 с ошибкой; нет трасс health и чужих корней; сети span S3 с ошибкой; нет трасс health и чужих корней; сети
@@ -244,7 +246,9 @@
make test, возврат; в finally — unpause и start телеметрии, make make test, возврат; в finally — unpause и start телеметрии, make
replicas, worker и relay; код 1 при расхождении, 2 — нет стенда replicas, worker и relay; код 1 при расхождении, 2 — нет стенда
stand-from-scratch [--project P] [--runs 2] свой проект compose (по stand-from-scratch [--project P] [--runs 2] свой проект compose (по
умолчанию mtusi-lab6-scratch; рабочий — код 2) на свободных портах умолчанию mtusi-lab6-scratch; имя не по шаблону
^mtusi-lab6-scratch(-[a-z0-9]+)?$ — код 2 до вызовов docker:
команда удаляет volumes проекта) на свободных портах
хоста: make run_docker на пустых volumes — код 0, состояния хоста: make run_docker на пустых volumes — код 0, состояния
сервисов, RestartCount брокера и телеметрии 0, нет eacces и сервисов, RestartCount брокера и телеметрии 0, нет eacces и
permission denied, provisioning Grafana, make test через свой LB; permission denied, provisioning Grafana, make test через свой LB;
@@ -9489,6 +9493,8 @@ SIGNAL_POLL_S = 2
TC_CHAT_GETS = 10 TC_CHAT_GETS = 10
# срок вызова S3 стенда ([s3] timeout_seconds = 5): span S3 при заморозке # срок вызова S3 стенда ([s3] timeout_seconds = 5): span S3 при заморозке
TC_S3_SPAN_RANGE = (4.0, 7.5) TC_S3_SPAN_RANGE = (4.0, 7.5)
# срок хранения Prometheus стенда (7 суток): окно поиска рядов health
TC_RETENTION_S = 7 * 86400
UUID_TEXT = re.compile( 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]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
r"[0-9a-fA-F]{12}", r"[0-9a-fA-F]{12}",
@@ -10088,10 +10094,18 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
'messenger_job_type="attachment.process.v1",' 'messenger_job_type="attachment.process.v1",'
'messenger_job_outcome="{outcome}"}' 'messenger_job_outcome="{outcome}"}'
) )
# запросы к неизвестному пути: без маршрута — без http_route
unknown_expr = (
"http_server_request_duration_seconds_count"
f'{{job="{API_SERVICE_NAME}",http_route="",'
'http_request_method="{method}",http_response_status_code="404"}'
)
exprs = { exprs = {
"chat": chat_expr, "chat": chat_expr,
"ready": jobs_expr.replace("{outcome}", "ready"), "ready": jobs_expr.replace("{outcome}", "ready"),
"failed": jobs_expr.replace("{outcome}", "failed"), "failed": jobs_expr.replace("{outcome}", "failed"),
"other": unknown_expr.replace("{method}", "_OTHER"),
"unknown_get": unknown_expr.replace("{method}", "GET"),
} }
print("waiting for metrics to settle before own traffic", flush=True) print("waiting for metrics to settle before own traffic", flush=True)
base, _ = settled(grafana, exprs) base, _ = settled(grafana, exprs)
@@ -10155,14 +10169,17 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
call(port, "GET", f"{CHATS}/{uuid.uuid4()}", token=token)[0], call(port, "GET", f"{CHATS}/{uuid.uuid4()}", token=token)[0],
) )
odd_uuid = str(uuid.uuid4()) odd_uuid = str(uuid.uuid4())
# BREW парсер HTTP uvicorn (httptools) отклоняет 400 ещё до приложения: # сценарий «Необычный метод и неизвестный путь»: метод вне стандартного
# ни span, ни ряда — проверяется только отсутствие BREW и UUID в метках. # набора, который парсер HTTP пропускает (PROPFIND), и GET — к пути с UUID.
# Метод вне стандартного набора, который доходит до приложения, — # BREW парсер uvicorn (httptools) отклоняет 400 до приложения: ни span,
# PROPFIND (design change otel-telemetry, «Уточнения apply») # ни ряда — ограничение спека (KNOWN_ISSUES.md), проверяется только
status, _, _ = call(port, "BREW", f"/api/v1/teapots/{odd_uuid}") # отсутствие BREW и UUID в метках
step("BREW rejected by the HTTP parser before the app", 400, status)
status, _, _ = call(port, "PROPFIND", f"/api/v1/teapots/{odd_uuid}") status, _, _ = call(port, "PROPFIND", f"/api/v1/teapots/{odd_uuid}")
step("PROPFIND of an unknown path with a UUID", 404, status) step("PROPFIND of an unknown path with a UUID", 404, status)
status, _, _ = call(port, "GET", f"/api/v1/teapots/{odd_uuid}")
step("GET of an unknown path with a UUID", 404, status)
status, _, _ = call(port, "BREW", f"/api/v1/teapots/{odd_uuid}")
step("BREW rejected by the HTTP parser (limitation)", 400, status)
foreign = secrets.token_hex(16) foreign = secrets.token_hex(16)
status, tp_hdrs, _ = call( status, tp_hdrs, _ = call(
port, port,
@@ -10315,6 +10332,7 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
"yes", "yes",
yes(any(span["name"] == "COMMIT" for span in children)), yes(any(span["name"] == "COMMIT" for span in children)),
) )
rows.extend(log_trace_links(grafana, trace_id, resource, started))
# --- чужой traceparent ------------------------------------------------- # --- чужой traceparent -------------------------------------------------
tp_records = loki_request( tp_records = loki_request(
@@ -10387,6 +10405,12 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
WORKER_SERVICE_NAME, WORKER_SERVICE_NAME,
(job_root.get("resource") or {}).get("service.name"), (job_root.get("resource") or {}).get("service.name"),
) )
worker_instances = {str(r.get("instance_id")) for r in worker_stdout}
step(
"worker service.instance.id = instance_id of its stdout",
next(iter(worker_instances)) if len(worker_instances) == 1 else "one",
(job_root.get("resource") or {}).get("service.instance.id"),
)
names = [str(span["name"]) for span in job_spans] names = [str(span["name"]) for span in job_spans]
step( step(
"job spans: PostgreSQL", "job spans: PostgreSQL",
@@ -10548,6 +10572,24 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
step("count grew on every replica", str(len(replicas)), len(grown)) 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 ready grew by 1", "1", f"{after['ready'] - base['ready']:g}")
step("jobs failed grew by 1", "1", f"{after['failed'] - base['failed']:g}") step("jobs failed grew by 1", "1", f"{after['failed'] - base['failed']:g}")
step(
"_OTHER 404 count without http_route grew by 1",
"1",
f"{after['other'] - base['other']:g}",
)
step(
"GET 404 count without http_route grew by 1",
"1",
f"{after['unknown_get'] - base['unknown_get']:g}",
)
# за весь срок хранения: healthcheck и проверки LB идут постоянно
health_series = grafana.series(
'{__name__=~"http_server_request_duration_seconds.*",'
'http_route=~"/health.*"}',
time.time() - TC_RETENTION_S,
time.time(),
)
step("Prometheus series with health routes", "0", len(health_series))
other = grafana.prom( other = grafana.prom(
"http_server_request_duration_seconds_count" "http_server_request_duration_seconds_count"
f'{{job="{API_SERVICE_NAME}",http_request_method="_OTHER"}}', f'{{job="{API_SERVICE_NAME}",http_request_method="_OTHER"}}',
@@ -10705,6 +10747,82 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int:
) )
def log_trace_links(
grafana: Grafana,
trace_id: str,
resource: dict[str, object],
since: float,
) -> list[tuple[str, str, str]]:
"""Сценарий `observability` «От лога к трассе и обратно» через API
Grafana: у источника Loki поле `trace_id` ведёт в источник `tempo`, а
запрос `tracesToLogsV2` источника Tempo (`infra/otel/grafana/
datasources.yaml`) с подстановкой span трассы T возвращает её записи."""
rows: list[tuple[str, str, str]] = []
_, loki_ds = grafana.request("GET", "/api/datasources/uid/loki")
fields = (
(loki_ds.get("jsonData") or {}).get("derivedFields") or []
if isinstance(loki_ds, dict)
else []
)
link = next(
(f for f in fields if f.get("matcherRegex") == "trace_id"),
{},
)
rows.append(
(
"Loki field trace_id links to datasource",
"tempo label",
f"{link.get('datasourceUid')} {link.get('matcherType')}",
),
)
_, tempo_ds = grafana.request("GET", "/api/datasources/uid/tempo")
to_logs = (
(tempo_ds.get("jsonData") or {}).get("tracesToLogsV2") or {}
if isinstance(tempo_ds, dict)
else {}
)
rows.append(
(
"Tempo span links to logs in datasource",
"loki",
str(to_logs.get("datasourceUid")),
),
)
query = (
str(to_logs.get("query", ""))
.replace(
'${__span.tags["service.name"]}',
str(resource.get("service.name", "")),
)
.replace("${__trace.traceId}", trace_id)
)
rows.append(
(
"span-to-logs query fully substituted",
"yes",
yes(bool(trace_id) and bool(query) and "${" not in query),
),
)
records = []
if trace_id and query and "${" not in query:
records = (
poll(lambda: grafana.loki(query, since, time.time() + 5)) or []
)
rows.append(
(
"span-to-logs query returns records of trace T",
"yes",
yes(
len(records) >= 2
and all(r[2].get("trace_id") == trace_id for r in records),
),
),
)
for row in rows:
print(f"{row[0]}: {row[2]}", flush=True)
return rows
def otel_env_probe(grafana: Grafana) -> list[tuple[str, str, str]]: def otel_env_probe(grafana: Grafana) -> list[tuple[str, str, str]]:
"""Разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом: шлёт """Разовый контейнер API с `OTEL_SDK_DISABLED=true` и чужим адресом: шлёт
в Collector из `[telemetry]` и пишет `warning` с именами переменных.""" в Collector из `[telemetry]` и пишет `warning` с именами переменных."""
@@ -11206,6 +11324,8 @@ def telemetry_outage(port: int, grafana: Grafana) -> int:
SCRATCH_PROJECT = "mtusi-lab6-scratch" SCRATCH_PROJECT = "mtusi-lab6-scratch"
# имена проекта, которые команда принимает: она сама удаляет его volumes
SCRATCH_PROJECT_NAME = re.compile(r"^mtusi-lab6-scratch(-[a-z0-9]+)?$")
SCRATCH_PORTS = ( SCRATCH_PORTS = (
"APP_OUT_PORT", "APP_OUT_PORT",
"POSTGRES_OUT_PORT", "POSTGRES_OUT_PORT",
@@ -11232,6 +11352,14 @@ def cmd_stand_from_scratch(project: str, runs: int) -> int:
`otel-telemetry`, решения 19 и 21): свой проект compose на пустых volumes, `otel-telemetry`, решения 19 и 21): свой проект compose на пустых volumes,
`make run_docker` с первой попытки, затем проект удаляется вместе с volumes `make run_docker` с первой попытки, затем проект удаляется вместе с volumes
при любом исходе. Рабочий стенд не трогается.""" при любом исходе. Рабочий стенд не трогается."""
# down -v удаляет volumes проекта: только одноразовое имя, проверка —
# до любых вызовов docker
if not SCRATCH_PROJECT_NAME.fullmatch(project):
print(
f"stand-from-scratch: project {project!r} refused: only "
f"{SCRATCH_PROJECT_NAME.pattern} (the command removes its volumes)",
)
return 2
working = json.loads( working = json.loads(
subprocess.run( subprocess.run(
["docker", "compose", "config", "--format", "json"], ["docker", "compose", "config", "--format", "json"],
+24
View File
@@ -135,6 +135,13 @@ Change `openspec/changes/otel-telemetry/`, propose 2026-11-11. Номера —
- `level=error` Loki «empty ring» на старте и Tempo «no jobs found» в простое — шум, не отказ (п. 7); - `level=error` Loki «empty ring» на старте и Tempo «no jobs found» в простое — шум, не отказ (п. 7);
- `stand-from-scratch` останавливает рабочий стенд на время проверки (`make stop` / `docker compose start`) (п. 10); - `stand-from-scratch` останавливает рабочий стенд на время проверки (`make stop` / `docker compose start`) (п. 10);
- лимиты решения 7 подтверждены замером, не менялись (п. 11). - лимиты решения 7 подтверждены замером, не менялись (п. 11).
- Правки по verify (2026-11-11, design, «Уточнения apply», п. 13–18):
- дренаж API 9 с с включённой телеметрией — ошибка настроек с именем `app.graceful_shutdown_seconds` (8 + 1 с SDK ≤ 9
с), без телеметрии 9 с допустимы; у worker закрытие SDK — внутри прежнего окна 0,5 с (п. 13);
- экспортёры OTLP — своя `requests.Session` с `trust_env=False`: прокси окружения не действуют (п. 14);
- сценарий «Необычный метод и неизвестный путь» — на `PROPFIND` и `GET`, `BREW` — ограничение (п. 15);
- `telemetry-check`: ссылки лог ↔ трасса источников Grafana, нет рядов health, `service.instance.id` worker (п. 16);
- `stand-from-scratch --project` — только `mtusi-lab6-scratch[-…]`, иначе код 2 до docker (п. 17).
### Вопросы ### Вопросы
@@ -157,3 +164,20 @@ Change `openspec/changes/otel-telemetry/`, propose 2026-11-11. Номера —
который доходит до приложения (`PROPFIND`)? Иначе — `http="h11"` у uvicorn или правило HAProxy (отдельный change). который доходит до приложения (`PROPFIND`)? Иначе — `http="h11"` у uvicorn или правило HAProxy (отдельный change).
7. Пользователю (apply): перед замерами для отчёта переснять `telemetry-check`, `telemetry-outage`, 7. Пользователю (apply): перед замерами для отчёта переснять `telemetry-check`, `telemetry-outage`,
`stand-from-scratch` и бюджет на закоммиченном коде — evidence сняты на незакоммиченном дереве поверх `9b35c25`. `stand-from-scratch` и бюджет на закоммиченном коде — evidence сняты на незакоммиченном дереве поверх `9b35c25`.
8. Пользователю (verify W4): `driver.py stand-from-scratch` сам удаляет volumes своего проекта (`docker compose -p
mtusi-lab6-scratch… down -v` в начале, после каждого прогона и при Ctrl+C), а deny-правила `.claude/settings.local.json`
запрещают агенту `down -v`. Подтвердите, что так можно для одноразового проекта `mtusi-lab6-scratch*` (как у `make
failure_checks` со своим `<рабочий>-failures`). Имя проекта команда теперь принимает только по шаблону
`^mtusi-lab6-scratch(-[a-z0-9]+)?$`, иначе код 2 до вызовов docker. Настройки разрешений не менялись. Иначе —
убирать проект scratch руками пользователя, а команда только печатает команду уборки.
### Предложения на потом
Найдено verify, решено не исправлять в этом change.
- S2: evidence для сценария «Restart hook не трогает телеметрию» — по коду выполняется (`scripts/restart.sh` сервисы
телеметрии не называет), но вывода нет. Предложение: в `telemetry-check` или отдельной пробе — `StartedAt` сервисов
телеметрии до и после `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (задача 11.5 его уже сверяет на глаз).
- S4: relay и уборщик SDK не запускают, но загружают его модули через `SqlAlchemyUnitOfWork` (`src/infra/db/uow.py` →
`src/infra/telemetry`): 139 модулей, RSS уборщика ~100 МиБ при ~90 МиБ в `docker.md`. Предложение для change 2: ленивый
импорт SDK в `src/infra/telemetry` (до `start`) или замер `memory.peak` relay и уборщика и правка `docker.md`.
+29 -1
View File
@@ -213,7 +213,7 @@ Loki.
| `grafana` | 0,5 | 384 МиБ | 300 МиБ | 251 МиБ | | `grafana` | 0,5 | 384 МиБ | 300 МиБ | 251 МиБ |
| **итого** | **2,5** | **2048 МиБ** | | ~0,5 ГиБ | | **итого** | **2,5** | **2048 МиБ** | | ~0,5 ГиБ |
Постоянные лимиты стенда — 11,5 CPU и 7040 МиБ, с одноразовыми — 12,5 CPU и 7424 МиБ при ВМ 12 CPU и 7936 МиБ. Это Постоянные лимиты стенда — 11,5 CPU и 7040 МиБ, с одноразовыми — 12,5 CPU и 7424 МиБ при ВМ 12 CPU и 7934 МиБ. Это
потолки, а не резерв: CPU делится по времени, память стенда в простое ~3 ГиБ. Apply меряет пик каждого сервиса и реплики потолки, а не резерв: CPU делится по времени, память стенда в простое ~3 ГиБ. Apply меряет пик каждого сервиса и реплики
API под `make test` + `make load` (`docker stats`, `memory.peak`): лимит не меньше 1,5 × пика, иначе поднимается, сумма API под `make test` + `make load` (`docker stats`, `memory.peak`): лимит не меньше 1,5 × пика, иначе поднимается, сумма
пересчитывается; таблица — `REPORT.md` и `docker.md`, «Суммы». Стенд `bench/` идёт при остановленном рабочем пересчитывается; таблица — `REPORT.md` и `docker.md`, «Суммы». Стенд `bench/` идёт при остановленном рабочем
@@ -534,3 +534,31 @@ Apply 2026-11-11 (второй агент: первый прервался по
ближе всех); суммы прежние — 11,5 CPU / 7040 МиБ, с одноразовыми 12,5 / 7424 (`evidence/telemetry/budget.md`). ближе всех); суммы прежние — 11,5 CPU / 7040 МиБ, с одноразовыми 12,5 / 7424 (`evidence/telemetry/budget.md`).
12. **Быстрые тесты (8.1–8.3)** написал прерванный агент вместе с кодом; красный прогон до кода не снимался и не 12. **Быстрые тесты (8.1–8.3)** написал прерванный агент вместе с кодом; красный прогон до кода не снимался и не
воспроизводился (git агенту запрещён). Проверяют поведение, а не вызовы: in-memory экспортёры SDK и временная база. воспроизводился (git агенту запрещён). Проверяют поведение, а не вызовы: in-memory экспортёры SDK и временная база.
Правки по `/opsx:verify` (2026-11-11, задачи 12):
13. **Срок остановки API с телеметрией (W3, решение 13).** Выбрана проверка сочетания, а не `le=8` для всех: без
телеметрии дренаж 9 с по-прежнему укладывается (закрытие клиентов — миллисекунды), и прежнее поведение и спек
«Завершение за заявленный срок» не меняются. Валидатор — на поле `telemetry` класса `Settings` (секции `app` он
видит, она объявлена раньше): `enabled` и `app.graceful_shutdown_seconds + TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS >
API_STOP_BUDGET_SECONDS` (9) — ошибка с `loc` `telemetry` и текстом, который называет `app.graceful_shutdown_seconds`
и предел 8. На поле секции без секретов: ошибка секции `app` несла бы её значение. Проверку видят все процессы, что
читают `Settings` с включённой телеметрией, в том числе worker («Invalid worker settings», код 2): `config.toml`
общий, и неверное сочетание — ошибка стенда. Worker — тот же расчёт своего окна: ожидание ≤ 8 + отмена 0,5 +
потребитель 0,5 + `gather` 0,5, в котором ждётся и закрытие SDK, = 9,5 с; новой проверки не требует, тест
фиксирует арифметику (`service-tests/unit/test_settings.py`).
14. **Отправка только в Collector (S5).** Экспортёры получают `requests.Session` с `trust_env=False`: иначе `requests`
берёт `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc` и `REQUESTS_CA_BUNDLE` из окружения — второй источник адреса, как
`OTEL_*`. `requests` — зависимость экспортёра OTLP/HTTP, в `pyproject.toml` не добавлялся.
15. **«Необычный метод» (W2, п. 2).** Сценарий дельты переписан на `PROPFIND` и `GET` к пути с UUID; `BREW` — фраза об
ограничении в тексте требования «Метрики HTTP API». `telemetry-check` проверяет рост рядов `_OTHER` 404 и `GET` 404 без
`http_route` ровно на 1, `BREW` — только 400 парсера и отсутствие в метках.
16. **Проверки verify S1, S2 в `telemetry-check`.** Переход лог ↔ трасса проверяется через API Grafana настройками
источников: derived field `trace_id` Loki ведёт в `tempo` (`matcherType: label`), запрос `tracesToLogsV2` Tempo с
подстановкой `service.name` ресурса и `trace_id` трассы возвращает её записи. Ряды `http_route=~"/health.*"` ищутся за
срок хранения Prometheus; `service.instance.id` трассы задания сверяется с `instance_id` записей worker в stdout.
17. **`stand-from-scratch --project` (W4).** Принимает только `^mtusi-lab6-scratch(-[a-z0-9]+)?$`, иначе код 2 до любых
вызовов docker: команда делает `down -v` своего проекта, и чужое имя (`mtusi-lab5`, `mtusi-lab6-failures`) удалило бы
чужие volumes. Разрешено ли агенту это `down -v` при deny-правилах — вопрос пользователю (`QUESTIONS.md`).
18. **Журнал в Loki (S3).** Отправляются записи между запуском SDK и началом закрытия: записи uvicorn до lifespan, ошибки
настроек, остановка до старта и «Stopped worker» — только stdout (дельта `service-logging`).
@@ -8,6 +8,12 @@ API — требования «Завершение за заявленный с
внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать Collector дольше. Запись об остановке внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать Collector дольше. Запись об остановке
процесса SHALL быть в stdout при любом состоянии Collector. процесса SHALL быть в stdout при любом состоянии Collector.
Срок отправки при остановке SHALL входить в тот же бюджет, а не прибавляться к нему: у API с включённой телеметрией
`[app] graceful_shutdown_seconds` вместе со сроком закрытия SDK MUST NOT превышать 9 с (требование «Завершение за заявленный
срок»), иначе запуск SHALL останавливаться ошибкой проверки настроек с именем поля `app.graceful_shutdown_seconds`; без
телеметрии допустимы прежние 9 с. У worker закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай остаётся
прежним (требование «Остановка worker»).
#### Scenario: docker stop при остановленном Collector #### Scenario: docker stop при остановленном Collector
- **WHEN** Collector остановлен, реплика API только что обслуживала запросы, и выполняется `docker stop` этой реплики, а затем - **WHEN** Collector остановлен, реплика API только что обслуживала запросы, и выполняется `docker stop` этой реплики, а затем
@@ -18,3 +24,9 @@ API — требования «Завершение за заявленный с
- **WHEN** контейнер Collector заморожен (`docker pause`), и выполняются те же остановки - **WHEN** контейнер Collector заморожен (`docker pause`), и выполняются те же остановки
- **THEN** обе команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке - **THEN** обе команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке
#### Scenario: Срок остановки API не оставляет места закрытию SDK
- **WHEN** API запускается с включённой телеметрией и `APP__GRACEFUL_SHUTDOWN_SECONDS=9`
- **THEN** запуск останавливается ошибкой проверки настроек, которая называет поле `app.graceful_shutdown_seconds` и
допустимый предел, а с выключенной телеметрией то же значение принимается
@@ -156,7 +156,9 @@ buckets SHALL покрывать ожидаемые задержки API — о
Доля ошибок SHALL быть определена заранее: числитель — ответы 5xx API, знаменатель — все учтённые запросы; 4xx (неверный Доля ошибок SHALL быть определена заранее: числитель — ответы 5xx API, знаменатель — все учтённые запросы; 4xx (неверный
пароль, чужой чат) в долю ошибок не входят и показываются отдельно. Ответы, которые сгенерировал сам балансировщик, в пароль, чужой чат) в долю ошибок не входят и показываются отдельно. Ответы, которые сгенерировал сам балансировщик, в
метрики API не попадают — ограничение в `REPORT.md`. метрики API не попадают — ограничение в `REPORT.md`. Так же вне метрик, трасс и журнала API — запрос с методом, который
HTTP-парсер сервера отклоняет до приложения (`BREW`: его нет в списке методов парсера uvicorn): ответ ему даёт парсер —
ограничение, `KNOWN_ISSUES.md` («Нестандартный метод HTTP»).
#### Scenario: Запросы в метрике #### Scenario: Запросы в метрике
@@ -171,8 +173,10 @@ buckets SHALL покрывать ожидаемые задержки API — о
#### Scenario: Необычный метод и неизвестный путь #### Scenario: Необычный метод и неизвестный путь
- **WHEN** клиент шлёт запрос с методом `BREW` и запрос к несуществующему пути с UUID внутри - **WHEN** клиент шлёт к несуществующему пути с UUID внутри запрос с методом вне стандартного набора, который HTTP-парсер
- **THEN** их ряды — с методом `_OTHER` и без `http_route`, а ни метода `BREW`, ни этого UUID в метках нет сервера передаёт приложению (`PROPFIND`), и запрос `GET`
- **THEN** первый учтён в ряду с методом `_OTHER`, второй — в ряду с методом `GET`, оба ряда без `http_route`, а ни метода
`PROPFIND`, ни этого UUID в метках нет
### Requirement: Метрики заданий worker ### Requirement: Метрики заданий worker
@@ -27,8 +27,10 @@ stdout, и в записи, отправленной в хранилище ло
### Requirement: Журнал в хранилище логов ### Requirement: Журнал в хранилище логов
При включённой телеметрии каждая запись журнала API и worker, которая пишется в stdout, SHALL ещё и отправляться в хранилище При включённой телеметрии каждая запись журнала API и worker, которая пишется в stdout между запуском SDK и началом его
логов через Collector: тело — `event`, уровень — из `level`, время — `timestamp`, остальные поля записи — атрибутами, ресурс — закрытия при остановке, SHALL ещё и отправляться в хранилище логов через Collector; записи до запуска SDK (записи uvicorn до lifespan,
остановка до старта, ошибки настроек) и после начала закрытия (запись «Stopped worker») идут только в stdout. Отправленная
запись: тело — `event`, уровень — из `level`, время — `timestamp`, остальные поля записи — атрибутами, ресурс —
`service.name` и остальные атрибуты процесса (capability `observability`, «SDK в API и worker»). Записи stdout при этом MUST `service.name` и остальные атрибуты процесса (capability `observability`, «SDK в API и worker»). Записи stdout при этом MUST
NOT меняться, кроме полей трассы (требование «Связь записей с трассой»). Записи самого SDK OpenTelemetry идут только в stdout. NOT меняться, кроме полей трассы (требование «Связь записей с трассой»). Записи самого SDK OpenTelemetry идут только в stdout.
Отказ отправки MUST NOT задерживать запись и обработку и MUST NOT терять записи stdout. Отказ отправки MUST NOT задерживать запись и обработку и MUST NOT терять записи stdout.
+42 -2
View File
@@ -73,8 +73,9 @@
## 5. Worker ## 5. Worker
- [x] 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` и его ветки возвращают исход; быстрые тесты сервиса и действием с сообщением; `AttachmentProcessingService.handle` и его ветки возвращают исход; быстрые тесты сервиса
`test_worker_deliveries.py` проверяют исход каждой ветки вместо `ACK`. Проверка: `make service_test`. (`test_attachment_processing.py`) проверяют исход каждой ветки вместо `ACK`, а исход → действие, span и histogram —
`test_telemetry.py`. Проверка: `make service_test`.
- [x] 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 `instrument_engine`; в `_handle` после места конкуренции — span `CONSUMER` `process <очередь>` и histogram
`messenger.job.duration` по исходу (`error` при исключении), подтверждение внутри span; «Started worker» — поля телеметрии; `messenger.job.duration` по исходу (`error` при исключении), подтверждение внутри span; «Started worker» — поля телеметрии;
@@ -194,3 +195,42 @@
телеметрия выключена; `docker compose config --quiet` — рабочий стенд, CI, `bench/`, стенд отказов. Проверка: выводы команд; телеметрия выключена; `docker compose config --quiet` — рабочий стенд, CI, `bench/`, стенд отказов. Проверка: выводы команд;
причины любых падений — в отчёте apply до правок. причины любых падений — в отчёте apply до правок.
- [x] 11.6 `graphify update .` после закрытия задач. Проверка: в графе есть узлы `src/infra/telemetry`. - [x] 11.6 `graphify update .` после закрытия задач. Проверка: в графе есть узлы `src/infra/telemetry`.
## 12. Замечания проверки
Находки `/opsx:verify` (2026-11-11), которые решено исправить. Evidence переснимается отдельной стадией на коммите правок.
- [x] 12.1 W2. Дельта `observability`, сценарий «Необычный метод и неизвестный путь»: метод вне стандартного набора, который
пропускает HTTP-парсер (`PROPFIND`), и явное ограничение для методов, которые парсер отклоняет до приложения (`BREW`,
`KNOWN_ISSUES.md`); `telemetry-check` проверяет сценарий в новой формулировке — рост ряда `_OTHER` 404 без `http_route` и
ряда `GET` 404 без `http_route` от своих запросов, ни `PROPFIND`, ни UUID в метках. Проверка: `openspec validate
otel-telemetry --strict`; шаги `telemetry-check` — `expected` = `got`.
- [x] 12.2 W3. Проверка настроек: при включённой телеметрии `[app] graceful_shutdown_seconds` +
`TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS` не больше бюджета остановки API (9 с: SIGKILL docker через 10 с), иначе запуск
останавливается ошибкой с именем поля; у worker — тот же расчёт его окна (закрытие SDK внутри окна `gather` 0,5 с, сумма
9,5 с < 10 с). Дельта `graceful-shutdown` — требование и сценарий неверного сочетания; выбор — design, «Уточнения apply».
Проверка: быстрый тест `service-tests/unit/test_settings.py` (9 + телеметрия — ошибка с полем, 9 без телеметрии и 8 с
ней — допустимо, окно worker); `make service_test`.
- [x] 12.3 W4. `driver.py stand-from-scratch --project`: только имя `^mtusi-lab6-scratch(-[a-z0-9]+)?$`, иначе код 2 до
любых действий docker; строка в `SKILL.md`; вопрос пользователю о `down -v` своего проекта — `QUESTIONS.md`. Проверка:
`driver.py stand-from-scratch --project` с `mtusi-lab5`, `mtusi-lab6-failures`, `bp_proxies`, `mtusi-lab6` — код 2 и ни
одного вызова docker (запуск с `PATH` без `docker` и `DOCKER_HOST` на несуществующий сокет).
- [x] 12.4 S1. `telemetry-check`, сценарий «От лога к трассе и обратно»: запрос к Loki через Grafana по подстановке
`tracesToLogsV2` источника Tempo (`infra/otel/grafana/datasources.yaml`) с реальным `trace_id` возвращает записи запроса;
у источника Loki derived field `trace_id` ведёт в источник `tempo`. Проверка: шаги `telemetry-check` — `expected` = `got`.
- [x] 12.5 S2. `telemetry-check`: рядов Prometheus с `http_route=~"/health.*"` нет; `service.instance.id` ресурса трассы
задания равен `instance_id` записи worker в stdout. Проверка: шаги `telemetry-check` — `expected` = `got`.
- [x] 12.6 S3. Дельта `service-logging`, «Журнал в хранилище логов»: отправляются записи между запуском и закрытием SDK;
записи до запуска и после закрытия — только stdout. Проверка: `openspec validate otel-telemetry --strict`.
- [x] 12.7 S5. Экспортёры OTLP получают свою `requests.Session` с `trust_env=False`: `HTTP(S)_PROXY` и `NO_PROXY` окружения
на отправку не влияют, данные идут только в Collector. Проверка: быстрый тест в `service-tests/unit/test_telemetry.py`
`test_exporters_ignore_proxy_environment`: с `HTTP(S)_PROXY` в окружении отправка трёх экспортёров уходит на адрес
Collector без прокси, `requests.Session.send` подменён — сети нет); `make service_test`.
- [x] 12.8 S6. Память ВМ в design (решение 7) — 7934 МиБ, как в `docker.md` и `REPORT.md`; ссылка задачи 5.1 — на
фактические файлы тестов. Проверка: `grep -n 7936` по change — пусто.
- [x] 12.9 Не исправлять, записать: `QUESTIONS.md`, `## otel-telemetry`, «Предложения на потом» — evidence «Restart hook
не трогает телеметрию» (S2) и загрузка SDK relay и уборщиком через `SqlAlchemyUnitOfWork` (S4). Проверка: подраздел есть.
- [x] 12.10 Регрессия: `openspec validate otel-telemetry --strict`, `make lint`, `make service_test`, `make
service_test_db`, пересборка и `docker compose up -d` api и worker, `make test`, `make student_test` через LB (красный
только `test_exclusion_evidence_exists`), `driver.py --port 8080 telemetry-check` — код 0 (вывод в scratchpad; evidence —
следующая стадия на коммите).
+70 -2
View File
@@ -1,11 +1,44 @@
"""Значения `[uploads]` (спек `service-configuration`, «Неверный параметр """Значения `[uploads]` (спек `service-configuration`, «Неверный параметр
загрузок»). Сама секция, а не `Settings`: тот читает `.env` и `config.toml`. загрузок») и сочетание срока остановки API с телеметрией (спек
`graceful-shutdown`, «Остановка при недоступном Collector»). Секция или
`Settings` только из аргументов: настоящий читает `.env` и `config.toml`.
""" """
from typing import Any
import pytest import pytest
from pydantic import ValidationError from pydantic import ValidationError
from pydantic_settings import (
BaseSettings,
PydanticBaseSettingsSource,
SettingsConfigDict,
)
from src.config.settings import Uploads from src.config.settings import Settings, Uploads, Worker
from src.utils.constants import (
API_STOP_BUDGET_SECONDS,
CONTAINER_STOP_TIMEOUT_SECONDS,
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS,
)
from src.worker import main as worker_main
class _ArgumentsOnly(Settings):
"""`Settings` без окружения, `.env` и `config.toml`."""
model_config = SettingsConfigDict(
**{**Settings.model_config, "env_file": None, "toml_file": None},
)
@classmethod
def settings_customise_sources(
cls,
settings_cls: type[BaseSettings], # noqa: ARG003
init_settings: PydanticBaseSettingsSource,
*args: PydanticBaseSettingsSource, # noqa: ARG003
**kwargs: Any, # noqa: ARG003
) -> tuple[PydanticBaseSettingsSource, ...]:
return (init_settings,)
@pytest.mark.parametrize( @pytest.mark.parametrize(
@@ -26,3 +59,38 @@ def test_wrong_value_names_field(field: str, value: object) -> None:
def test_zero_turns_backlog_limit_off() -> None: def test_zero_turns_backlog_limit_off() -> None:
assert Uploads(max_unfinished_jobs=0).max_unfinished_jobs == 0 assert Uploads(max_unfinished_jobs=0).max_unfinished_jobs == 0
assert Uploads().max_unfinished_jobs == 250 assert Uploads().max_unfinished_jobs == 250
def test_api_stop_with_telemetry_over_budget_names_field() -> None:
"""9 с дренажа + 1 с закрытия SDK — SIGKILL docker (verify W3)."""
with pytest.raises(ValidationError) as caught:
_ArgumentsOnly(
app={"graceful_shutdown_seconds": 9},
telemetry={"enabled": True},
)
errors = caught.value.errors(include_input=False)
assert [error["loc"] for error in errors] == [("telemetry",)]
assert "app.graceful_shutdown_seconds" in errors[0]["msg"]
@pytest.mark.parametrize(
("graceful", "enabled"),
[(9, False), (8, True), (1, True)],
)
def test_api_stop_within_budget(graceful: int, enabled: bool) -> None:
loaded = _ArgumentsOnly(
app={"graceful_shutdown_seconds": graceful},
telemetry={"enabled": enabled},
)
assert loaded.app.graceful_shutdown_seconds == graceful
def test_budgets_fit_container_stop() -> None:
"""API: дренаж до 8 с + закрытие SDK; worker: ожидание до 8 с, отмена,
потребитель и одно окно `gather` с закрытием SDK — по 0,5 с."""
assert API_STOP_BUDGET_SECONDS < CONTAINER_STOP_TIMEOUT_SECONDS
assert 8 + TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS <= API_STOP_BUDGET_SECONDS
with pytest.raises(ValidationError):
Worker(graceful_shutdown_seconds=8.01)
worker_worst = 8 + 3 * worker_main._CLOSE_TIMEOUT_SECONDS
assert worker_worst < CONTAINER_STOP_TIMEOUT_SECONDS
+70 -3
View File
@@ -14,14 +14,24 @@ from typing import Any
import httpx import httpx
import pytest import pytest
import requests
from botocore.exceptions import ClientError from botocore.exceptions import ClientError
from fastapi import APIRouter, FastAPI from fastapi import APIRouter, FastAPI
from opentelemetry import trace from opentelemetry import trace
from opentelemetry._logs import SeverityNumber from opentelemetry._logs import SeverityNumber
from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import (
InMemoryLogRecordExporter,
SimpleLogRecordProcessor,
)
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import InMemoryMetricReader from opentelemetry.sdk.metrics.export import InMemoryMetricReader
from opentelemetry.sdk.trace import ReadableSpan from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult from opentelemetry.sdk.trace.export import (
SimpleSpanProcessor,
SpanExporter,
SpanExportResult,
)
from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter, InMemorySpanExporter,
) )
@@ -30,6 +40,7 @@ from redis.exceptions import RedisError
from src.api.middlewares import RequestContextMiddleware from src.api.middlewares import RequestContextMiddleware
from src.config import settings from src.config import settings
from src.config.settings import Telemetry as TelemetrySettings
from src.infra import logger as app_logger from src.infra import logger as app_logger
from src.infra import telemetry from src.infra import telemetry
from src.infra.cache.client import Cache from src.infra.cache.client import Cache
@@ -49,6 +60,8 @@ pytestmark = pytest.mark.anyio
SERVICE = "messenger-api" SERVICE = "messenger-api"
SECRET_TEXT = "secret-text-in-exception" SECRET_TEXT = "secret-text-in-exception"
COLLECTOR = "http://otel-collector:4318"
PROXY = "http://proxy.invalid:3128"
@dataclass @dataclass
@@ -583,6 +596,60 @@ async def test_shutdown_is_bounded() -> None:
telemetry.remove_log_hooks() telemetry.remove_log_hooks()
def test_exporters_ignore_proxy_environment(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Данные идут только в Collector из `[telemetry]`: прокси окружения
(`HTTP(S)_PROXY`) экспортёры не берут (verify S5). Отправка подменена на
уровне `requests.Session.send` — сети нет, видно, с какими прокси она бы
ушла."""
for name in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"):
monkeypatch.setenv(name, PROXY)
monkeypatch.setenv(name.lower(), PROXY)
for name in ("NO_PROXY", "no_proxy"):
monkeypatch.delenv(name, raising=False)
sent: list[tuple[str, dict[str, str]]] = []
def send(
self: requests.Session, # noqa: ARG001
request: requests.PreparedRequest,
**kwargs: Any,
) -> requests.Response:
sent.append((str(request.url), dict(kwargs.get("proxies") or {})))
response = requests.Response()
response.status_code = 200
response._content = b""
response.request = request
return response
monkeypatch.setattr(requests.Session, "send", send)
exporters = core._otlp_exporters(
TelemetrySettings(otlp_endpoint=COLLECTOR),
)
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporters.spans))
logger_provider = LoggerProvider()
logger_provider.add_log_record_processor(
SimpleLogRecordProcessor(exporters.logs),
)
meter_provider = MeterProvider(metric_readers=[exporters.metrics])
try:
tracer_provider.get_tracer("t").start_span("probe").end()
logger_provider.get_logger("t").emit(body="probe")
meter_provider.get_meter("t").create_counter("probe").add(1)
exporters.metrics.force_flush()
finally:
tracer_provider.shutdown()
logger_provider.shutdown()
meter_provider.shutdown()
assert {url for url, _ in sent} == {
f"{COLLECTOR}/v1/traces",
f"{COLLECTOR}/v1/logs",
f"{COLLECTOR}/v1/metrics",
}
assert all(proxies == {} for _, proxies in sent), sent
# --- исход доставки worker ------------------------------------------------ # --- исход доставки worker ------------------------------------------------
+43 -3
View File
@@ -21,7 +21,12 @@ from pydantic_settings import (
from sqlalchemy.engine import URL from sqlalchemy.engine import URL
from src.schemas.enums import RunModeEnum from src.schemas.enums import RunModeEnum
from src.utils.constants import INSTANCE_ID_PATTERN, S3_BUCKET_NAME_PATTERN from src.utils.constants import (
API_STOP_BUDGET_SECONDS,
INSTANCE_ID_PATTERN,
S3_BUCKET_NAME_PATTERN,
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS,
)
BASE_DIR = Path(__file__).resolve().parent.parent.parent BASE_DIR = Path(__file__).resolve().parent.parent.parent
ENV_PATH = BASE_DIR.joinpath(".env") ENV_PATH = BASE_DIR.joinpath(".env")
@@ -40,8 +45,13 @@ class App(BaseModel):
port: int = Field(default=8080, ge=1, le=65535) port: int = Field(default=8080, ge=1, le=65535)
log_level: LogLevel = "INFO" log_level: LogLevel = "INFO"
# секунды, которые uvicorn ждёт текущие запросы после SIGTERM; # секунды, которые uvicorn ждёт текущие запросы после SIGTERM;
# docker шлёт SIGKILL через 10 с, поэтому не больше 9 # docker шлёт SIGKILL через 10 с, поэтому не больше 9, а с телеметрией —
graceful_shutdown_seconds: int = Field(default=8, ge=1, le=9) # не больше 8: после lifespan ещё закрытие SDK (проверка в Settings)
graceful_shutdown_seconds: int = Field(
default=8,
ge=1,
le=API_STOP_BUDGET_SECONDS,
)
# секунды, которые uvicorn держит простаивающее keep-alive соединение. # секунды, которые uvicorn держит простаивающее keep-alive соединение.
# Больше, чем HAProxy держит простаивающий сеанс клиента, а с ним и # Больше, чем HAProxy держит простаивающий сеанс клиента, а с ним и
# соединение с репликой (timeout http-keep-alive 10 с и http-reuse # соединение с репликой (timeout http-keep-alive 10 с и http-reuse
@@ -543,6 +553,36 @@ class Settings(BaseSettings):
relay: Relay = Relay() relay: Relay = Relay()
telemetry: Telemetry = Telemetry() telemetry: Telemetry = Telemetry()
@field_validator("telemetry")
@classmethod
def api_stop_fits_container(
cls,
value: Telemetry,
info: ValidationInfo,
) -> Telemetry:
"""С телеметрией API после дренажа ещё ждёт закрытия SDK: сумма не
больше бюджета остановки, иначе SIGKILL docker (код 137). Проверка на
поле секции без секретов: секции `app` ошибка с её значением не
нужна (design change `otel-telemetry`, «Уточнения apply», п. 13)."""
app = info.data.get("app")
if (
value.enabled
and app is not None
and app.graceful_shutdown_seconds
+ TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS
> API_STOP_BUDGET_SECONDS
):
limit = (
API_STOP_BUDGET_SECONDS - TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS
)
raise ValueError(
"enabled telemetry requires app.graceful_shutdown_seconds "
f"<= {limit:g}: SDK shutdown takes up to "
f"{TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS:g} s of the "
f"{API_STOP_BUDGET_SECONDS:g} s stop budget",
)
return value
@classmethod @classmethod
def settings_customise_sources( def settings_customise_sources(
cls, cls,
+16 -1
View File
@@ -17,6 +17,9 @@ from contextlib import contextmanager, suppress
from dataclasses import dataclass, field from dataclasses import dataclass, field
from typing import Any from typing import Any
# транспорт экспортёров OTLP/HTTP (зависимость opentelemetry-exporter-otlp-
# proto-http): своя сессия без окружения
import requests
from opentelemetry import trace from opentelemetry import trace
from opentelemetry.context import Context from opentelemetry.context import Context
from opentelemetry.exporter.otlp.proto.http import Compression from opentelemetry.exporter.otlp.proto.http import Compression
@@ -253,9 +256,18 @@ def start(
return True return True
def _export_session() -> requests.Session:
"""Сессия отправки без окружения: `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc`
и `REQUESTS_CA_BUNDLE` на неё не действуют — данные идут только по адресу
`[telemetry]` (verify S5, как с `OTEL_*`, решение 8)."""
session = requests.Session()
session.trust_env = False
return session
def _otlp_exporters(config: TelemetrySettings) -> Exporters: def _otlp_exporters(config: TelemetrySettings) -> Exporters:
"""OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без """OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без
заголовков и сжатия.""" заголовков и сжатия, своя сессия без прокси окружения."""
timeout = config.export_timeout_seconds timeout = config.export_timeout_seconds
endpoint = config.otlp_endpoint endpoint = config.otlp_endpoint
return Exporters( return Exporters(
@@ -264,6 +276,7 @@ def _otlp_exporters(config: TelemetrySettings) -> Exporters:
headers={}, headers={},
timeout=timeout, timeout=timeout,
compression=Compression.NoCompression, compression=Compression.NoCompression,
session=_export_session(),
), ),
metrics=PeriodicExportingMetricReader( metrics=PeriodicExportingMetricReader(
OTLPMetricExporter( OTLPMetricExporter(
@@ -272,6 +285,7 @@ def _otlp_exporters(config: TelemetrySettings) -> Exporters:
timeout=timeout, timeout=timeout,
compression=Compression.NoCompression, compression=Compression.NoCompression,
preferred_temporality=_CUMULATIVE, preferred_temporality=_CUMULATIVE,
session=_export_session(),
), ),
export_interval_millis=config.metric_export_interval_seconds export_interval_millis=config.metric_export_interval_seconds
* 1000, * 1000,
@@ -282,6 +296,7 @@ def _otlp_exporters(config: TelemetrySettings) -> Exporters:
headers={}, headers={},
timeout=timeout, timeout=timeout,
compression=Compression.NoCompression, compression=Compression.NoCompression,
session=_export_session(),
), ),
) )
+6
View File
@@ -157,6 +157,12 @@ TELEMETRY_LOGS_PATH = "/v1/logs"
# секунды, которые процесс ждёт закрытия SDK при остановке; что не ушло — # секунды, которые процесс ждёт закрытия SDK при остановке; что не ушло —
# теряется (решение 13): API — 8 с дренажа + закрытие клиентов + 1 с < 10 с # теряется (решение 13): API — 8 с дренажа + закрытие клиентов + 1 с < 10 с
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS = 1 TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS = 1
# секунды от SIGTERM до SIGKILL docker (stop_grace_period сервисов приложения)
CONTAINER_STOP_TIMEOUT_SECONDS = 10
# секунды на дренаж uvicorn и закрытие SDK API: остаток до SIGKILL — закрытие
# клиентов в lifespan и выход процесса. Без телеметрии дренаж до 9 с, с ней —
# дренаж + TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS (проверка настроек, verify W3)
API_STOP_BUDGET_SECONDS = 9
# секунды: не больше одной записи логгера `opentelemetry.*` в stdout за окно # секунды: не больше одной записи логгера `opentelemetry.*` в stdout за окно
TELEMETRY_SDK_LOG_WINDOW_SECONDS = 60 TELEMETRY_SDK_LOG_WINDOW_SECONDS = 60
# префикс логгеров самого SDK: их записи не экспортируются # префикс логгеров самого SDK: их записи не экспортируются