From ef60b472468a4531f1a2cc144cb4c03608ec546e Mon Sep 17 00:00:00 2001 From: roman Date: Sat, 14 Nov 2026 04:08:13 +0300 Subject: [PATCH] fix: address slo-alerts verify findings Count the first SDK telemetry loss on the loss panel, print pending moments on every alerts-check step, check the loss panel on a quiet stand, align two scenarios and the SLI cross-check text with what the driver verifies. Co-Authored-By: Claude Opus 5.5 --- .claude/rules/telemetry.md | 8 +- .claude/skills/run-mtusi-messenger/SKILL.md | 25 ++- .claude/skills/run-mtusi-messenger/driver.py | 187 ++++++++++++++++-- AGENTS.md | 6 +- QUESTIONS.md | 16 ++ REPORT.md | 17 +- infra/otel/prometheus/rules.test.yml | 97 ++++++++- infra/otel/prometheus/rules.yml | 23 ++- openspec/changes/slo-alerts/design.md | 37 ++++ .../slo-alerts/specs/observability/spec.md | 16 +- openspec/changes/slo-alerts/tasks.md | 42 ++++ 11 files changed, 425 insertions(+), 49 deletions(-) diff --git a/.claude/rules/telemetry.md b/.claude/rules/telemetry.md index d1596f2..1f383f8 100644 --- a/.claude/rules/telemetry.md +++ b/.claude/rules/telemetry.md @@ -126,13 +126,17 @@ paths: — `infra/otel/prometheus/rules.yml` (bind mount и `configs` CI), тесты — `rules.test.yml` (`make alerts_test`: `promtool` в одноразовом контейнере через `tar`, затем проверка `runbook_url`), в контейнер не монтируются. Новое оповещение — правило с `for`, `severity`, `summary`, - `description` с `$value`, `runbook_url` на `infra/otel/runbooks/<имя>.md`, тест срабатывания, + `description` с `$value` (у `absent()` и `up == 0` значение пустое по смыслу — вместо него + шаблон `query`: возраст последней точки, число недоступных целей; design `slo-alerts`, + «Уточнения apply», п. 21), `runbook_url` на `infra/otel/runbooks/<имя>.md`, тест срабатывания, порога, «без трафика» и снятия (в `exp_annotations` — все аннотации дословно). Блока `alerting` нет: доставки нет, Alertmanager отвергнут по функции (SA-3). Флаг `created-timestamp-zero-ingestion`, у цели `otel-collector-exporter` — protobuf первым, глобально — прежний текстовый список Prometheus 3: время начала нужно только экспортёру Collector. Потери — правило `telemetry:lost_items:total` (сумма по процессу, не `increase()`); новое - место потерь — его составляющая. `le` в запросах — как в хранилище (`"0.25"`, `"30.0"`). + место потерь — его составляющая. Ряд суммы каждого процесса начинается с нуля со старта (у SDK — + часть `… * 0` по ряду ёмкости очереди span, у Collector — его ряды `receiver_refused`): иначе + первое значение нового ряда `rate()` панели потерь отбрасывает (verify, W1). `le` в запросах — как в хранилище (`"0.25"`, `"30.0"`). - **Панели с change `slo-alerts`** (SA-10): строки «SLO and alerts», «Load balancer», «Telemetry pipeline», id с 25. Ряд, которого может не быть (оповещения, потери, 5xx API), — `… or on() vector(0)`: обход панелей драйвером требует данных. Макрос `$__range` драйвер подменяет на diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 6a4f662..4497b7c 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -498,10 +498,11 @@ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 backend-outage `outbox` + `published` +3, consumer span после остановки нет, последняя запись worker в Loki; worker стоит не меньше 130 с (ряды процесса ушли), `docker start` — все `ready`, снято ≤ 2 мин, счёт `messenger_job_time_to_ready_seconds_count` по точкам (без экстраполяции, первая точка — - ноль времени начала нового процесса) +3; 2) `docker compose stop relay` — ряды глубины уходят - ≤ 2 мин, `MessengerQueueMetricsMissing` ≤ 5 мин, `docker start` — снято ≤ 2 мин; 3) сессия psql + ноль времени начала нового процесса) +3; 2) `docker compose stop relay` — ряды глубины и + возраста очереди уходят ≤ 2 мин, `MessengerQueueMetricsMissing` ≤ 5 мин, `docker start` — снято + ≤ 2 мин; 3) сессия psql `application_name = mtusi-alerts-check` циклами держит `LOCK TABLE messages IN SHARE MODE` 2 с с - паузой 0,2 с — `MessengerSlowRequests` ≤ 3 мин, медиана доли span PostgreSQL в медленных трассах + паузой 0,2 с — `MessengerSlowRequests` ≤ 4 мин, медиана доли span PostgreSQL в медленных трассах отправки > 0,5, пул занят больше, чем до шагов, CPU реплик < 0,5 предела; сессия завершена (`pg_terminate_backend`) — снято ≤ 4 мин; 4) 3 потока входят по Basic 45 с — медиана доли span PostgreSQL в трассах входа < 0,2, свободное место в пуле ждать не пришлось (доля занятых < 1, @@ -511,11 +512,12 @@ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 backend-outage 5xx API и не меньше 503 самого LB у клиента, доля 5xx LB = доля клиента ± 5 п. п.; `docker compose start postgres` — сняты ≤ 4 мин (`MessengerQueueMetricsMissing` в pending допустим); 6) SLI за 7 суток в [0, 1], за час — по рядам правил и по исходным счётчикам: сумма - `increase(…[5m])` на время каждой точки `messenger-slo` (≤ 1 п. п.; рядом — `increase` за час - одним окном и число окон за час: пока Prometheus стоял, окон нет), перед шагами — 20 загрузок + `increase(…[5m])` на время каждой точки `messenger-slo` (≤ 1 п. п.), у доступности и задержки — + и `increase` за час одним окном (≤ 1 п. п.; у времени до `ready` — наблюдение), число окон за + час (пока Prometheus стоял, окон нет), перед шагами — 20 загрузок при работающем worker (хорошие события времени до `ready`), SLI за окно учений, запросы панелей с id от 25 с данными, панель истории состояний показывает firing всех шагов; пики памяти Prometheus и Collector. На - каждом шаге — «other alerts firing» (лишних нет). В `finally` — нагрузка остановлена, сессия + каждом шаге — момент pending рядом с каждой строкой firing и «other alerts firing» (лишних нет). В `finally` — нагрузка остановлена, сессия блокировки завершена, PostgreSQL запущен, worker и relay — `docker start` тех же контейнеров, LB готов. Код 0 / 1 / 2. - **`backend-outage`** — та же нагрузка и опрос правил; память раз в 2 с (`memory.current` реплик @@ -523,12 +525,13 @@ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 backend-outage очереди: 10 с (свой запрос находится в хранилище после возврата, счётчики `send_failed` / `enqueue_failed` экспортёра не выросли) и 120 с (`make test` PASS, 5xx у клиента 0, очередь экспорта ≤ ёмкости, память Collector ниже лимита, `TelemetryTargetDown{job=…}` ≤ 110 с, - `TelemetryDataLoss` firing, потери Collector > 0, новые сигналы после возврата, оба сняты ≤ 4 - мин); Prometheus 60 с (5xx 0, приращение счёта запросов API между точками до и после не меньше + `TelemetryDataLoss` firing, потери Collector > 0 и видны на панели потерь (запрос A панели 40, + `job="otel-collector"`), новые сигналы после возврата, оба сняты ≤ 4 мин); Prometheus 60 с (5xx 0, приращение счёта запросов API между точками до и после не меньше запросов нагрузки); Collector 120 с (`make test` PASS, `TelemetryTargetDown` firing, память каждой реплики: максимум последней трети окна не выше первой больше чем на 16 МиБ и ниже лимита, `MessengerQueueMetricsMissing` не pending; после возврата — снято, счётчики потерь SDK - реплик выросли, ёмкость очередей SDK 2048, записей Loki в окне меньше stdout). В конце — пики + реплик выросли и видны на панели потерь (`job="messenger-api"`: ряд правила процесса SDK + начинается с нуля), ёмкость очередей SDK span и журнала 2048, записей Loki в окне меньше stdout). В конце — пики памяти Collector, Prometheus и реплик по cgroup (`memory.peak`, `anon` + `kernel` + `shmem`, `file`, лимит — для бюджета). В `finally` — сервисы телеметрии запущены, worker и relay. Код 0 / 1 / 2. @@ -564,7 +567,9 @@ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 backend-outage - **`telemetry-check`** — всё через HTTP API Grafana (источники-прокси Prometheus, Loki, Tempo): вход 401 / 401 / 200, порт только на `127.0.0.1`, источники по uid и их проверка, dashboard - provisioned и отказ его сохранения, цели Prometheus `up`; затем «тихая» база счётчиков (35 с без + provisioned и отказ его сохранения, цели Prometheus `up`, метрики LB; панель потерь (id 40) на + тихом стенде — все три запроса 0, `TelemetryDataLoss` неактивно (ждёт до 330 с: окно `rate()` + панели 5 мин, время ожидания печатается); затем «тихая» база счётчиков (35 с без изменений), свой пользователь, сообщение, 10 GET чата, 401, 404, `PROPFIND` и `GET` к неизвестному пути с UUID (ряды `_OTHER` и `GET` без `http_route` выросли на 1; `BREW` — только 400 парсера, ограничение), `traceparent`, загрузка и недекодируемый JPEG (12 бит, diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index c4a81cb..195eef2 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -10364,6 +10364,9 @@ def telemetry_check(port: int, grafana: Grafana, paused: list[str]) -> int: # метрики LB (design change slo-alerts, решение 2) for name, expected, got in lb_metrics_rows(port, grafana): step(name, expected, got) + # панель потерь до своих рестартов Collector и хранилищ (verify S4) + for name, expected, got in loss_panel_quiet_rows(grafana): + step(name, expected, got) # --- база метрик до своего трафика ----------------------------------- chat_route = '"/api/v1/chats/{chat_id}"' @@ -12759,7 +12762,7 @@ AC_SESSION = "mtusi-alerts-check" AC_LOCK_HOLD_S = 2 # пауза короче 0,5 с design: в ней каждый поток записи успевает ~1 быстрый # запрос, доля медленных ~0,4, порог 10 % пересекается раньше (firing было -# 165 с из 180 при паузе 0,5 с, «Уточнения apply») +# 165 с при паузе 0,5 с, «Уточнения apply», п. 7; срок спека — 4 мин, verify S1) AC_LOCK_PAUSE_S = 0.2 AC_LOCK_CYCLES = 400 AC_LOCK_SQL = f"""\ @@ -12788,7 +12791,9 @@ AC_LAG_CLEAR_S = 120 AC_RELAY_FIRING_S = 300 AC_RELAY_SERIES_GONE_S = 120 AC_RELAY_CLEAR_S = 120 -AC_SLOW_FIRING_S = 180 +# firing задают конвейер (экспорт SDK, сбор, слот точки правила — по 15 с) и +# for 1 мин: ~165 с — запас до 3 мин мал, срок 4 мин (verify S1) +AC_SLOW_FIRING_S = 240 AC_SLOW_CLEAR_S = 240 AC_DB_FIRING_S = 180 AC_DB_CLEAR_S = 240 @@ -12800,11 +12805,13 @@ AC_LOGIN_WATCH_S = 75 # метрика доходит до Prometheus: экспорт SDK 15 с + сбор 15 с AC_SCRAPE_LAG_S = 35 AC_SLI_TOLERANCE = 0.01 +# SLI, которые сверяются и с increase одним окном часа (спек «SLO считается») +AC_SLI_ONE_WINDOW = ("availability", "latency") AC_SHARE_TOLERANCE = 0.05 AC_TRACES = 5 # фоновая нагрузка драйвера: запись преобладает — блокировка таблицы сообщений # делает медленной заметную долю «лёгких» запросов (~29 % при блокировке: порог -# 10 % окна 2 мин пересекается раньше, firing — с запасом до 3 мин) +# 10 % окна 2 мин пересекается раньше, firing — с запасом до 4 мин) LOAD_WRITERS = 6 LOAD_READERS = 1 LOAD_PERIOD_S = 0.25 @@ -13477,6 +13484,15 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: def note(text: str) -> None: print(f" observed: {text}", flush=True) + def pending_note(key: str, since: float) -> None: + """Момент pending оповещения — рядом с его строкой firing (спек + «Проверка оповещений отказами»: pending на каждом шаге).""" + at = watch.first(key, "pending", since) + note( + f"{key} pending " + + ("not observed" if at is None else f"after {at - since:.0f} s"), + ) + print( f"alerts-check {datetime.now(UTC):%Y-%m-%dT%H:%M:%SZ}: rules, " "quiet stand", @@ -13586,11 +13602,7 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: first_upload, AC_LAG_FIRING_S, ) - pending = watch.first("MessengerQueueLagHigh", "pending", first_upload) - if pending is not None: - note( - f"MessengerQueueLagHigh pending after {pending - first_upload:.0f} s", - ) + pending_note("MessengerQueueLagHigh", first_upload) rows.append( alert_row( f"[{step}] MessengerQueueLagHigh firing after the first upload", @@ -13700,10 +13712,13 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: relay_ids = service_ids("relay") detached("docker", "compose", "stop", "relay", timeout=60) stopped_at = time.time() + # сценарий «Остановленный relay уходит из рядов»: глубина и возраст gone = poll( lambda: ( not grafana.prom( - f'messenger_queue_depth{{job="{RELAY_SERVICE_NAME}"}}', + "{__name__=~" + '"messenger_queue_depth|messenger_queue_oldest_age_seconds",' + f'job="{RELAY_SERVICE_NAME}"}}', ) ), timeout=AC_RELAY_SERIES_GONE_S + 30, @@ -13711,7 +13726,8 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: ) gone_after = time.time() - stopped_at add( - f"[{step}] queue series gone within {AC_RELAY_SERIES_GONE_S} s", + f"[{step}] queue depth and age series gone within " + f"{AC_RELAY_SERIES_GONE_S} s", "yes", yes(bool(gone) and gone_after <= AC_RELAY_SERIES_GONE_S), ) @@ -13722,6 +13738,7 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: stopped_at, AC_RELAY_FIRING_S, ) + pending_note("MessengerQueueMetricsMissing", stopped_at) rows.append( alert_row( f"[{step}] MessengerQueueMetricsMissing firing", @@ -13764,6 +13781,7 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: locked_at, AC_SLOW_FIRING_S, ) + pending_note("MessengerSlowRequests", locked_at) rows.append( alert_row( f"[{step}] MessengerSlowRequests firing", @@ -13935,6 +13953,7 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: stopped_at, AC_DB_FIRING_S, ) + pending_note("MessengerNoReadyReplicas", stopped_at) rows.append( alert_row( f"[{step}] MessengerNoReadyReplicas firing", @@ -13943,6 +13962,7 @@ def alerts_check(port: int, grafana: Grafana, state: dict[str, object]) -> int: AC_DB_FIRING_S, ), ) + pending_note("MessengerHighErrorRate", stopped_at) rows.append( alert_row( f"[{step}] MessengerHighErrorRate firing", @@ -14127,8 +14147,9 @@ def sli_rows( """Сценарий «SLO считается»: SLI за 7 суток по рядам правил — от 0 до 1; за час — по рядам правил и по исходным счётчикам: сумма `increase(…[5m])` исходных счётчиков на время каждой точки правила (те же окна), расхождение - не больше 1 п. п.; для сравнения — `increase` за час одним окном и SLI за - окно учений (design, «Уточнения apply»).""" + не больше 1 п. п.; у доступности и задержки — и `increase` за час одним + окном (тоже 1 п. п.), у времени до `ready` оно — наблюдение; SLI за окно + учений (design, «Уточнения apply», пп. 12, 18).""" # последнее вычисление группы раз в 5 мин: мгновенный запрос его не видит, # когда точка старше lookback (5 мин) — время берётся из сырых точек now = time.time() @@ -14181,6 +14202,16 @@ def sli_rows( "yes", yes(abs(a - b) <= AC_SLI_TOLERANCE), ) + # у доступности и задержки — и против increase одним окном часа + # (сотни событий: потеря на границах окон — доли п. п.); у времени до + # ready событий единицы — только наблюдение (verify W3) + if name in AC_SLI_ONE_WINDOW: + add( + f"SLI {name} over the hour, rules vs raw increase over one " + "window within 1 pp", + "yes", + yes(abs(a - whole) <= AC_SLI_TOLERANCE), + ) span = f"{int(drill_end - drill_start)}s" drill = ratio( grafana.prom_sum(f"sum(increase({bad_expr}[{span}]))", drill_end), @@ -14267,6 +14298,94 @@ def panel_rows( # первая панель SLO, оповещений, LB и конвейера в messenger-overview.json SLO_FIRST_PANEL = 25 +# панель потерь «Telemetry lost per second by place»: запрос A — правило +# telemetry:lost_items:total по job, B и C — составляющие Collector и SDK +LOSS_PANEL_ID = 40 +# тихий стенд для панели потерь: окно её rate() 5 мин, плюс экспорт, сбор и +# точка правила +LOSS_QUIET_WAIT_S = 330 + + +def loss_panel_exprs(grafana: Grafana) -> list[str]: + """Запросы панели потерь из dashboard в Grafana (по порядку refId).""" + _, dashboard = grafana.request( + "GET", + f"/api/dashboards/uid/{DASHBOARD_UID}", + ) + model = ( + dashboard.get("dashboard", {}) if isinstance(dashboard, dict) else {} + ) + for panel in model.get("panels", []): + if panel.get("id") == LOSS_PANEL_ID: + return [ + panel_expr(str(target["expr"])) + for target in panel.get("targets", []) + ] + return [] + + +def loss_panel_by_job( + grafana: Grafana, + start: float, + end: float, +) -> dict[str, float]: + """Наибольшее значение запроса A панели потерь в окне — по `job` + (сценарии «Потери SDK при недоступном Collector», «Потери Collector при + недоступном хранилище»: потери видно на панели).""" + exprs = loss_panel_exprs(grafana) + if not exprs: + return {} + seconds = max(15, int(end - start)) + return { + job: round(value, 3) + for job, value in grafana.prom_by( + f"max by (job) (max_over_time(({exprs[0]})[{seconds}s:15s]))", + "job", + end, + ).items() + if job + } + + +def loss_panel_quiet_rows(grafana: Grafana) -> list[tuple[str, str, str]]: + """Сценарий «Без потерь» (verify S4): на тихом стенде каждый запрос + панели потерь даёт 0, а `TelemetryDataLoss` неактивно. Тихий — без + потерь последние 5 мин (окно `rate()` панели): ожидание до + `LOSS_QUIET_WAIT_S`, время ожидания печатается.""" + exprs = loss_panel_exprs(grafana) + started = time.time() + seen: dict[str, object] = {} + + def quiet() -> bool: + values = [round(grafana.prom_sum(expr), 6) for expr in exprs] + state = rule_states(grafana).get("TelemetryDataLoss", "inactive") + seen.update(values=values, state=state) + return bool(exprs) and not any(values) and state == "inactive" + + ok = bool(poll(quiet, timeout=LOSS_QUIET_WAIT_S, interval=15)) + print( + f" observed: loss panel quiet after {time.time() - started:.0f} s: " + f"values {seen.get('values')}, TelemetryDataLoss {seen.get('state')}", + flush=True, + ) + return [ + ("loss panel queries", "3", str(len(exprs))), + ( + "loss panel shows zero on a quiet stand", + "[0.0, 0.0, 0.0]", + str(seen.get("values")), + ), + ( + "TelemetryDataLoss on a quiet stand", + "inactive", + str(seen.get("state")), + ), + ( + f"loss panel quiet within {LOSS_QUIET_WAIT_S} s", + "yes", + yes(ok), + ), + ] class MemorySampler: @@ -14582,6 +14701,13 @@ def backend_outage( lost = grafana.prom_sum(loss_expr(exporter, signal_name)) - lost_before note(f"Collector losses of {exporter}: {lost:.0f} {signal_name}") add(prefix + "losses counted by the Collector", "yes", yes(lost > 0)) + panel = loss_panel_by_job(grafana, since, time.time()) + note(f"loss panel, max per job since the stop: {panel}") + add( + prefix + "Collector losses on the loss panel", + "yes", + yes(panel.get("otel-collector", 0.0) > 0), + ) request_id, trace_id = own_request() add( prefix + "new signals arrive after the return", @@ -14759,15 +14885,40 @@ def backend_outage( f"SDK losses before {sdk_before}, after {sdk_loss_by_instance(grafana)}", ) add(prefix + "SDK loss counters of replicas grew", "yes", yes(bool(grown))) - capacity = grafana.prom_by( - f'max by (instance) (otel_sdk_processor_log_queue_capacity{{job="{API_SERVICE_NAME}"}})', - "instance", + # потери SDK видно на панели потерь (verify W1): ряд правила процесса + # начинается с нуля, rate() видит и первую порцию + panel = poll( + lambda: ( + loss_panel_by_job(grafana, since, time.time()).get( + API_SERVICE_NAME, + 0.0, + ) + > 0 + ), + timeout=METRIC_WAIT_S, + interval=5, + ) + note( + "loss panel, max per job since the stop: " + f"{loss_panel_by_job(grafana, since, time.time())}", ) add( - prefix + "SDK queue capacity as [telemetry] max_queue_size", - "{2048.0}", - str(set(capacity.values()) or "{}"), + prefix + "SDK losses of replicas on the loss panel", + "yes", + yes(bool(panel)), ) + for signal_name in ("span", "log"): + capacity = grafana.prom_by( + f"max by (instance) (otel_sdk_processor_{signal_name}_queue_capacity" + f'{{job="{API_SERVICE_NAME}"}})', + "instance", + ) + add( + prefix + + f"SDK {signal_name} queue capacity as [telemetry] max_queue_size", + "{2048.0}", + str(set(capacity.values()) or "{}"), + ) time.sleep(AC_SCRAPE_LAG_S) loki = grafana.loki_all( f'{{service_name="{API_SERVICE_NAME}"}}', diff --git a/AGENTS.md b/AGENTS.md index 9666feb..bf62d1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -552,11 +552,11 @@ 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-check` | телеметрия рабочего стенда через HTTP API Grafana с паролем из `.env` (~2 мин, change `otel-telemetry`): вход, порт, источники, dashboard provisioned и неизменяем, цели Prometheus, метрики LB, панель потерь на тихом стенде — 0 (ожидание до 330 с); свой запрос → 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` (~3,5 мин): `make test`, загрузка до `ready`, записи SDK в stdout; возврат Collector — запись, трасса, span producer и ряды API, worker и relay при прежних `StartedAt` и `RestartCount` их контейнеров; второе окно того же вида — `make test`, `docker stop` реплики, worker и relay быстрее 10 с с кодом 0; все сервисы телеметрии остановлены — рестарт api, worker и relay, `make test`; сигналы (и span producer relay) снова приходят; стенд возвращается в `finally`; `evidence/telemetry/collector-outage.md` | | `make alerts_test` | правила Prometheus без стенда и сети (change `slo-alerts`): `tar` файлов `infra/otel/prometheus/` в одноразовый контейнер образа Prometheus из compose (`--network none`) — `promtool check config`, `check rules`, `test rules rules.test.yml`; затем у каждого оповещения `runbook_url` на существующий файл; шаг CI; `evidence/alerts/rules-test.md` | -| `driver.py --port alerts-check` | учения оповещений на рабочем стенде (~25 мин, change `slo-alerts`), через HTTP API Grafana: правила загружены, доставки нет, тихий стенд (иначе код 2); фоновая нагрузка драйвера; worker остановлен — `MessengerQueueLagHigh` и счёт времени до готовности по точкам; relay остановлен — `MessengerQueueMetricsMissing`; блокировка таблицы сообщений — `MessengerSlowRequests`, доля span PostgreSQL, пул, CPU; входы по Basic — без оповещения; PostgreSQL остановлен — `MessengerNoReadyReplicas` и `MessengerHighErrorRate`, 5xx LB против API; SLI двумя путями, новые панели и история состояний; в `finally` — нагрузка, сессия блокировки, PostgreSQL, worker, relay, LB; `evidence/alerts/check.md` | -| `driver.py --port backend-outage` | отказ хранилищ телеметрии под нагрузкой (~18 мин, change `slo-alerts`): Loki и Tempo 10 с и 120 с, Prometheus 60 с, Collector 120 с — `make test`, 5xx у клиента, очереди и память Collector, память реплик, учёт потерь, `TelemetryTargetDown` и `TelemetryDataLoss`, пики памяти по cgroup; сервисы телеметрии запускаются в `finally`; `evidence/telemetry/backend-outage.md` | +| `driver.py --port alerts-check` | учения оповещений на рабочем стенде (~25 мин, change `slo-alerts`), через HTTP API Grafana: правила загружены, доставки нет, тихий стенд (иначе код 2); фоновая нагрузка драйвера; worker остановлен — `MessengerQueueLagHigh` и счёт времени до готовности по точкам; relay остановлен — `MessengerQueueMetricsMissing`; блокировка таблицы сообщений — `MessengerSlowRequests`, доля span PostgreSQL, пул, CPU; входы по Basic — без оповещения; PostgreSQL остановлен — `MessengerNoReadyReplicas` и `MessengerHighErrorRate`, 5xx LB против API; на каждом шаге моменты pending, firing и снятия; SLI двумя путями (у доступности и задержки — и одним окном часа), новые панели и история состояний; в `finally` — нагрузка, сессия блокировки, PostgreSQL, worker, relay, LB; `evidence/alerts/check.md` | +| `driver.py --port backend-outage` | отказ хранилищ телеметрии под нагрузкой (~18 мин, change `slo-alerts`): Loki и Tempo 10 с и 120 с, Prometheus 60 с, Collector 120 с — `make test`, 5xx у клиента, очереди и память Collector, память реплик, учёт потерь и панель потерь (Collector и SDK реплик), `TelemetryTargetDown` и `TelemetryDataLoss`, пики памяти по cgroup; сервисы телеметрии запускаются в `finally`; `evidence/telemetry/backend-outage.md` | | `driver.py --port trace-chain` | сквозная трасса и сигналы уровня 4 на рабочем стенде (~5 мин, change `job-trace-propagation`), через HTTP API Grafana: предусловие — глубина очереди 0 за 120 с (иначе код 2 «stand is not quiet»); очередь и её возраст при остановленном worker и спад до 0; загрузка с повтором при замороженном S3 — одна трасса: server span API, два span producer relay, два consumer span worker (parent и link, span S3 с ошибкой, запись оригинала и вариантов); replay в той же трассе; задание без контекста (`UPDATE` колонок своей строки) — корень worker; время до `ready`, пулы, ёмкость worker, пределы контейнеров = `docker inspect` и рост CPU каждого за прогон, нет сокета Docker, панели уровня 4 с данными; `unpause s3`, worker и relay — в `finally`; `evidence/telemetry/trace-chain.md` | | `driver.py stand-from-scratch [--runs 2]` | `make run_docker` на пустых volumes своим проектом `mtusi-lab6-scratch` (рабочий — код 2) на свободных портах (~1 мин на прогон): код 0, состояния, `RestartCount` брокера и телеметрии 0, нет `eacces`, provisioning, `make test`; проект удаляется с volumes при любом исходе, ID контейнеров рабочего стенда прежние; `evidence/stand/from-scratch.md` | | `driver.py freeze-lb [--rounds 3]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME`, по умолчанию `mtusi-lab6-freeze`; `mtusi-lab6` — код 2): сама поднимает стенд с данными в tmpfs (volumes нет) на образе `mtusi-messenger:lab6` и убирает его при любом исходе; `docker pause` PostgreSQL, шесть запросов через LB — 503 за ~8 с, 504 нет, `unpause` в `finally`, сессий не больше пулов (~1,5 мин); раздел `evidence/storage/freeze-sessions.md` | diff --git a/QUESTIONS.md b/QUESTIONS.md index b9ec50e..110c2b2 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -359,10 +359,26 @@ Change `openspec/changes/slo-alerts/` (propose 2026-11-11). Номера — р Вопрос verify: устраивает ли такая трактовка двух сценариев спека («SLO считается» — те же окна; «Медленный handler» — место в пуле, а не мгновенный `pending`)? Иначе — правка спека или новый счётчик «ждут места» отдельно от открытия. + **Ответ verify (2026-11-14):** трактовка устраивает, новых счётчиков не нужно — исправлен текст двух сценариев дельты + `observability` под проверку; у доступности и задержки `alerts-check` сверяет ещё и с `increase` одним окном часа + (design, «Уточнения apply», п. 18). - Evidence раздела 11 — на commit `15ea156` без правок кода; `rules-test.md` от 2026-11-11 оставлен (повторный прогон — тот же вывод); пик Collector в долгом отказе хранилища — по `docker stats` и метрикам Collector, а не по `memory.peak`: шаг отказа Collector в той же команде начинает новую cgroup (design, «Уточнения apply», п. 16). +### Решения apply по verify + +Без пользователя (verify 2026-11-14, tasks, раздел 12); подробности — design, «Уточнения apply», пп. 17–22. + +- Ноль ряда потерь процесса SDK — по ряду ёмкости очереди span (`… or sum by (job, instance) + (otel_sdk_processor_span_queue_capacity) * 0`), как предложил verify; у Collector отдельной части не нужно: его ряды + `otelcol_receiver_refused_*` есть с нуля со старта (п. 17). +- Описание с текущим значением там, где `$value` пустое по смыслу (`absent()`, `up == 0`), — возраст последнего снимка + очереди и число недоступных целей шаблоном `query` (п. 21). +- Проверка «Без потерь» в `telemetry-check` ждёт тихого стенда до 330 с (окно `rate()` панели 5 мин), а не падает сразу: + иначе прогон сразу после `backend-outage` видел бы его потери (п. 22). +- Срок медленной БД — 4 мин в спеке и драйвере (п. 20). + ### Вопросы Не блокируют работу; ответ меняет только указанное место. diff --git a/REPORT.md b/REPORT.md index 5803732..ac678e0 100644 --- a/REPORT.md +++ b/REPORT.md @@ -305,8 +305,11 @@ runbooks — `infra/otel/runbooks/`. - Формулы окна W: доступность — `1 - sum_over_time(messenger:slo_availability_bad:increase5m[W]) / sum_over_time(messenger:slo_availability_total:increase5m[W])`; задержка и время до `ready` — `sum_over_time(messenger:slo__good:increase5m[W]) / sum_over_time(messenger:slo__total:increase5m[W])`. - Те же SLI по исходным счётчикам — `increase(…[W])` тех же селекторов (панели и `alerts-check` - считают обоими путями и сверяют, расхождение ≤ 1 п. п.). + Панели SLI (26 — за 7 суток, 28 — за интервал дашборда) считают по рядам правил. Те же SLI по + исходным счётчикам — `increase(…[W])` тех же селекторов; `alerts-check` сверяет пути за час: + ряды правил против суммы `increase(…[5m])` исходных счётчиков на время каждой точки правил (те же + окна, расхождение ≤ 1 п. п.), а у доступности и задержки — ещё против `increase(…[1h])` одним + окном (тоже ≤ 1 п. п.; у времени до `ready` одно окно — наблюдение, см. ограничения ниже). - «Лёгкие» маршруты — `http_route!~"/api/v1/users|/api/v1/auth/sessions|/api/v1/chats/.+/attachments|/api/v1/attachments/.+/content"`: вне SLI — KDF регистрации и входа (и `DELETE /api/v1/users` того же шаблона), загрузка и скачивание байтов; запросы без маршрута (404) входят. 5xx в SLI задержки не входят — это плохие @@ -388,7 +391,13 @@ true`), панель «Alert states». Правила Grafana отвергнут Сумма по процессу — правило `telemetry:lost_items:total`; оповещение — рост суммы, а не `increase()`: ряд отказов появляется с первой потерей, у собственных метрик Collector нет времени -начала. Внутренние метрики SDK (`otel.sdk.*`) включает код: процессоры и экспортёры OTLP span и +начала. Ряд суммы начинается с нуля со старта процесса — у Collector по его рядам +`otelcol_receiver_refused_*` (есть с нуля), у процессов SDK по ряду ёмкости очереди span (`… or +sum by (job, instance) (otel_sdk_processor_span_queue_capacity) * 0`), поэтому `rate()` панели +потерь видит и первую потерю процесса (без нуля первое значение нового ряда `rate()` отбрасывал: +verify, W1). Остаётся: процесс SDK, запущенный при уже недоступном Collector, или отказ Collector +дольше окна панели (5 мин) — первая точка ряда после возврата снова без нуля в окне; оповещение +`TelemetryDataLoss` это видит (рост против `offset 2m` или нуля). Внутренние метрики SDK (`otel.sdk.*`) включает код: процессоры и экспортёры OTLP span и журнала строятся после `MeterProvider` с ним и с переменной SDK только на время сборки; внешняя `OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED` удаляется, как любая `OTEL_*`; гистограммы SDK не отдаются. Результаты отказа каждого хранилища и Collector под нагрузкой драйвера (~25 запросов/с; @@ -497,7 +506,7 @@ Collector без времени начала (их закрывает прави | Уровень 4: dashboard — p50 / p95 / p99, доля ошибок, глубина и возраст очереди, пул БД, насыщение worker, контейнеры | `driver.py --port 8080 trace-chain`, `telemetry-check` | запросы панелей уровня 4 без ошибок и с данными; ряды очереди только у relay; пределы = `docker inspect`; нет сокета Docker | `evidence/telemetry/trace-chain.md`, `evidence/telemetry/check.md` | | Уровень 4: relay с SDK не меняет остановку | `driver.py --port 8080 telemetry-outage` | `docker stop` relay < 10 с, код 0, «Stopped relay» при остановленном и замороженном Collector | `evidence/telemetry/collector-outage.md` | | Уровень 4: схема контекста задания | миграция с нуля, повтор, откат, `--sql`, `make rolling_update`; план снимка очереди | `lock_timeout`, `NOT VALID`; без Seq Scan | `evidence/migrations/job-trace-context.md`, `evidence/telemetry/queue-snapshot.md` (commit `72cfa9a`) | -| Уровень 4: alert rules с runbooks в git, модульные тесты правил | `make alerts_test` | код 0: `promtool check config`, `check rules`, `test rules` (39 проверок оповещений и 6 правил записи); у каждого из 7 оповещений есть runbook | `evidence/alerts/rules-test.md` (commit `15ea156`) | +| Уровень 4: alert rules с runbooks в git, модульные тесты правил | `make alerts_test` | код 0: `promtool check config`, `check rules`, `test rules` (22 блока синтетических рядов: 43 проверки оповещений, 17 проверок выражений правил записи в 7 блоках); у каждого из 7 оповещений есть runbook | `evidence/alerts/rules-test.md` (commit `15ea156`) | | Уровень 4: SLI/SLO и окно, firing / resolved искусственным отказом, разбор двух инцидентов | `driver.py --port 8080 alerts-check` | код 0 (~20 мин): остановленный worker — firing через 158 с, снято через 44 с; relay — 220 / 45 с; медленная БД — 165 / 89 с; медленный handler — оповещения нет; недоступная БД — 60 и 105 / 29 и 135 с; лишних нет; SLI двумя путями совпали | `evidence/alerts/check.md` (commit `15ea156`) | | Уровень 4: memory limiter, batch, ограниченная буферизация, недоступный backend, учёт потерь | `driver.py --port 8080 backend-outage` | код 0 (~16 мин): `make test` PASS и 5xx 0 при остановленных Loki, Tempo, Prometheus и Collector; Collector ≤ 93 МиБ из 256, реплики без роста; потери учтены (443 записи, 1342 span, SDK 11 683 и 11 810); `TelemetryTargetDown` и `TelemetryDataLoss` — firing и снятие | `evidence/telemetry/backend-outage.md` (commit `15ea156`) | | Выбранный трек 5, если заявлен | TODO | TODO | TODO | diff --git a/infra/otel/prometheus/rules.test.yml b/infra/otel/prometheus/rules.test.yml index 30cbf32..a27bb48 100644 --- a/infra/otel/prometheus/rules.test.yml +++ b/infra/otel/prometheus/rules.test.yml @@ -279,11 +279,28 @@ tests: job: messenger-relay exp_annotations: summary: The relay queue snapshot is missing - description: 'There is no queue depth and age snapshot of the relay while the Collector exporter is up: the relay is stopped or cannot read PostgreSQL, and MessengerQueueLagHigh is blind. Runbook: infra/otel/runbooks/MessengerQueueMetricsMissing.md' + # последний снимок — точка 60 с, вычисление — 240 с + description: 'There is no queue depth and age snapshot of the relay while the Collector exporter is up (last snapshot 3m 0s ago): the relay is stopped or cannot read PostgreSQL, and MessengerQueueLagHigh is blind. Runbook: infra/otel/runbooks/MessengerQueueMetricsMissing.md' runbook_url: infra/otel/runbooks/MessengerQueueMetricsMissing.md - eval_time: 6m alertname: MessengerQueueMetricsMissing exp_alerts: [] + # снимка не было вовсе (за час): описание без возраста + - interval: 15s + input_series: + - series: 'up{job="otel-collector-exporter",instance="otel-collector:8889"}' + values: '1x20' + alert_rule_test: + - eval_time: 3m + alertname: MessengerQueueMetricsMissing + exp_alerts: + - exp_labels: + severity: warning + job: messenger-relay + exp_annotations: + summary: The relay queue snapshot is missing + description: 'There is no queue depth and age snapshot of the relay while the Collector exporter is up (last snapshot more than an hour ago): the relay is stopped or cannot read PostgreSQL, and MessengerQueueLagHigh is blind. Runbook: infra/otel/runbooks/MessengerQueueMetricsMissing.md' + runbook_url: infra/otel/runbooks/MessengerQueueMetricsMissing.md # экспортёр Collector недоступен: снимка нет, но молчит (TelemetryTargetDown) - interval: 15s input_series: @@ -333,11 +350,41 @@ tests: instance: tempo:3200 exp_annotations: summary: Metrics target tempo is down - description: 'Prometheus cannot scrape tempo (tempo:3200) for a minute; with job haproxy the load balancer metrics are missing and MessengerHighErrorRate is blind. Runbook: infra/otel/runbooks/TelemetryTargetDown.md' + # Loki к 2 мин вернулся: недоступна одна цель + description: 'Prometheus cannot scrape tempo (tempo:3200) for a minute (up 0; targets of the rule down now: 1); with job haproxy the load balancer metrics are missing and MessengerHighErrorRate is blind. Runbook: infra/otel/runbooks/TelemetryTargetDown.md' runbook_url: infra/otel/runbooks/TelemetryTargetDown.md - eval_time: 5m alertname: TelemetryTargetDown exp_alerts: [] + # Loki и Tempo недоступны вместе: по оповещению на цель, недоступны две + - interval: 15s + input_series: + - series: 'up{job="tempo",instance="tempo:3200"}' + values: '1x3 0x20' + - series: 'up{job="loki",instance="loki:3100"}' + values: '1x3 0x20' + - series: 'up{job="haproxy",instance="haproxy:8404"}' + values: '1x23' + alert_rule_test: + - eval_time: 3m + alertname: TelemetryTargetDown + exp_alerts: + - exp_labels: + severity: warning + job: loki + instance: loki:3100 + exp_annotations: + summary: Metrics target loki is down + description: 'Prometheus cannot scrape loki (loki:3100) for a minute (up 0; targets of the rule down now: 2); with job haproxy the load balancer metrics are missing and MessengerHighErrorRate is blind. Runbook: infra/otel/runbooks/TelemetryTargetDown.md' + runbook_url: infra/otel/runbooks/TelemetryTargetDown.md + - exp_labels: + severity: warning + job: tempo + instance: tempo:3200 + exp_annotations: + summary: Metrics target tempo is down + description: 'Prometheus cannot scrape tempo (tempo:3200) for a minute (up 0; targets of the rule down now: 2); with job haproxy the load balancer metrics are missing and MessengerHighErrorRate is blind. Runbook: infra/otel/runbooks/TelemetryTargetDown.md' + runbook_url: infra/otel/runbooks/TelemetryTargetDown.md # --- TelemetryDataLoss и сумма потерь ------------------------------------- # Collector: ряд отказов очереди Tempo появился на шаге 9 (135 с) сразу со @@ -410,6 +457,52 @@ tests: - eval_time: 11m alertname: TelemetryDataLoss exp_alerts: [] + # первая потеря процесса SDK видна в increase() панели потерь (verify W1): + # ряд ёмкости очереди span есть с запуска процесса — ряд суммы с нуля; ряд + # отказов реплики появился на шаге 16 (240 с) сразу со значением 36. relay + # без потерь — ноль, оповещения нет + - interval: 15s + input_series: + - series: 'otel_sdk_processor_span_queue_capacity{job="messenger-api",instance="a1",otel_component_type="batching_span_processor",otel_component_name="batching_span_processor/0"}' + values: '2048x40' + - series: 'otel_sdk_processor_span_queue_capacity{job="messenger-relay",instance="r1",otel_component_type="batching_span_processor",otel_component_name="batching_span_processor/0"}' + values: '2048x40' + - series: 'otel_sdk_processor_span_processed_total{job="messenger-api",instance="a1",otel_component_type="batching_span_processor",otel_component_name="batching_span_processor/0"}' + values: '0+100x40' + - series: 'otel_sdk_processor_span_processed_total{job="messenger-api",instance="a1",otel_component_type="batching_span_processor",otel_component_name="batching_span_processor/0",error_type="queue_full"}' + values: '_x16 36x24' + promql_expr_test: + - expr: telemetry:lost_items:total + eval_time: 3m + exp_samples: + - labels: 'telemetry:lost_items:total{job="messenger-api",instance="a1"}' + value: 0 + - labels: 'telemetry:lost_items:total{job="messenger-relay",instance="r1"}' + value: 0 + # запрос A панели 40 без суммы по job: приращение за 5 мин — вся потеря + - expr: increase(telemetry:lost_items:total[5m]) + eval_time: 6m + exp_samples: + - labels: '{job="messenger-api",instance="a1"}' + value: 36 + - labels: '{job="messenger-relay",instance="r1"}' + value: 0 + alert_rule_test: + - eval_time: 5m + alertname: TelemetryDataLoss + exp_alerts: + - exp_labels: + severity: warning + job: messenger-api + instance: a1 + exp_annotations: + summary: Telemetry of messenger-api is being lost + description: 'messenger-api (a1) lost 36 spans, log records or metric points in the last 2 minutes (full queue, failed export or refused by the memory limiter). Runbook: infra/otel/runbooks/TelemetryDataLoss.md' + runbook_url: infra/otel/runbooks/TelemetryDataLoss.md + - eval_time: 9m + alertname: TelemetryDataLoss + exp_alerts: [] + # без потерь — тихо, сумма потерь пуста - interval: 15s input_series: diff --git a/infra/otel/prometheus/rules.yml b/infra/otel/prometheus/rules.yml index 909474e..fb72dd6 100644 --- a/infra/otel/prometheus/rules.yml +++ b/infra/otel/prometheus/rules.yml @@ -43,12 +43,17 @@ groups: # worker и relay — отброшено из-за полной очереди и неудачные отправки. # Сумма, а не increase(): ряд отказов появляется с первой потерей, у # метрик Collector нет времени начала — первое значение нового ряда - # целиком рост + # целиком рост. Третья часть — ноль процесса SDK по ряду ёмкости очереди + # span (есть с запуска): ряд суммы начинается с нуля, и rate() панели + # потерь видит первую потерю (verify W1; у Collector ряды + # otelcol_receiver_refused_* есть с нуля с его старта) - record: telemetry:lost_items:total expr: >- sum by (job, instance) ({__name__=~"otelcol_(receiver_refused|exporter_send_failed|exporter_enqueue_failed)_(spans|log_records|metric_points)"}) or sum by (job, instance) ({__name__=~"otel_sdk_(processor|exporter)_(span|log)_(processed|exported)_total",error_type!=""}) + or + sum by (job, instance) (otel_sdk_processor_span_queue_capacity) * 0 # приращения событий SLI за непересекающиеся 5-минутные окна: SLI любого # окна — отношение сумм, без чтения 7 суток histogram на каждое обновление @@ -133,11 +138,16 @@ groups: for: 2m labels: severity: warning + # $value у absent() — всегда 1; текущее значение в описании — возраст + # последнего снимка за час (verify S3) annotations: summary: The relay queue snapshot is missing description: >- There is no queue depth and age snapshot of the relay while the - Collector exporter is up: the relay is stopped or cannot read + Collector exporter is up (last snapshot {{ with query `time() - + max(max_over_time(timestamp(messenger_queue_oldest_age_seconds{job="messenger-relay"})[1h:15s]))` + }}{{ . | first | value | humanizeDuration }} ago{{ else }}more + than an hour ago{{ end }}): the relay is stopped or cannot read PostgreSQL, and MessengerQueueLagHigh is blind. Runbook: infra/otel/runbooks/MessengerQueueMetricsMissing.md runbook_url: infra/otel/runbooks/MessengerQueueMetricsMissing.md @@ -153,10 +163,15 @@ groups: severity: warning annotations: summary: 'Metrics target {{ $labels.job }} is down' + # $value — up цели (0); рядом — сколько целей правила недоступно + # сейчас (verify S3) description: >- Prometheus cannot scrape {{ $labels.job }} ({{ $labels.instance }}) - for a minute; with job haproxy the load balancer metrics are missing - and MessengerHighErrorRate is blind. Runbook: + for a minute (up {{ $value }}; targets of the rule down now: {{ + with query `count(up{job=~"otel-collector|loki|tempo|haproxy"} == + 0)` }}{{ . | first | value }}{{ else }}0{{ end }}); with job + haproxy the load balancer metrics are missing and + MessengerHighErrorRate is blind. Runbook: infra/otel/runbooks/TelemetryTargetDown.md runbook_url: infra/otel/runbooks/TelemetryTargetDown.md - alert: TelemetryDataLoss diff --git a/openspec/changes/slo-alerts/design.md b/openspec/changes/slo-alerts/design.md index 8351f25..ff68eb5 100644 --- a/openspec/changes/slo-alerts/design.md +++ b/openspec/changes/slo-alerts/design.md @@ -327,6 +327,8 @@ telemetry:lost_items:total = sum by (job, instance) ({__name__=~"otelcol_(receiver_refused|exporter_send_failed|exporter_enqueue_failed)_(spans|log_records|metric_points)"}) or sum by (job, instance) ({__name__=~"otel_sdk_(processor|exporter)_(span|log)_(processed|exported)_total", error_type!=""}) + or + sum by (job, instance) (otel_sdk_processor_span_queue_capacity) * 0 # verify W1, «Уточнения apply», п. 17 ``` Оповещение: `telemetry:lost_items:total - (telemetry:lost_items:total offset 2m or telemetry:lost_items:total * 0) > 0`. @@ -583,3 +585,38 @@ COMMIT=<прежний> MIGRATE=0`; схема не меняется, нули не снят: шаг `[collector]` той же команды перезапускает контейнер (новая cgroup), поэтому в бюджете пик Collector — `docker stats` и `otelcol_process_runtime_*` окна долгого отказа (до 93 и 84 МиБ) и `memory.peak` за `alerts-check` (76 МиБ), а пробные числа п. 13 названы рядом; правило «лимит ≥ 1,5 × пика» выполнено по всем. + +Правки по verify (2026-11-14, tasks, раздел 12): + +17. **Первая потеря на панели (W1, решение 9).** Ряд суммы процесса SDK появлялся только с первой потерей сразу с её + значением, и `rate(telemetry:lost_items:total[5m])` панели 40 это первое значение отбрасывал (`backend-outage`: ряды + `messenger-api` 11 683 и 11 810 появились разом, панель — 0). К правилу добавлена третья часть `or sum by (job, + instance) (otel_sdk_processor_span_queue_capacity) * 0`: ряд ёмкости очереди span есть с запуска процесса, ряд суммы + — с нуля. У Collector ноль уже был: его ряды `otelcol_receiver_refused_*` есть с нуля со старта (проверено на стенде), + отдельной части не нужно. `TelemetryDataLoss` не меняется: рост против `offset 2m` (теперь чаще ноль, а не + отсутствие) — то же значение; тест `rules.test.yml` — ёмкость с начала, потеря на 240 с: ряд 0 до потери, + `increase(…[5m])` = 36 (первая точка окна — ноль, экстраполяции к началу нет), оповещение с 36; на прежнем правиле + тест красный (`got: nil` и `0`). Остаётся: процесс SDK, запущенный при уже недоступном Collector, и отказ Collector + дольше окна панели (5 мин) — нуля в окне нет (ограничение в `REPORT.md`). Составляющие B и C панели — исходные ряды, + они первое значение по-прежнему не видят: панель называет их частями суммы, учёт — запрос A. `backend-outage` + проверяет запрос A панели (из dashboard Grafana) в долгом отказе хранилища (`job="otel-collector"`) и отказе Collector + (`job="messenger-api"`). +18. **Сверка SLI (W3, спек «SLO считается»).** Текст сценария исправлен под проверку (ответ verify на вопрос apply: + трактовка устраивает, новых счётчиков не нужно): за час — ряды правил против суммы `increase(…[5m])` исходных + счётчиков в тех же окнах, у доступности и задержки — и против `increase` одним окном часа; `alerts-check` печатает эту + строку (`AC_SLI_ONE_WINDOW`), у времени до `ready` одно окно — наблюдение (п. 12). «Медленный handler» — «пул ни одной + реплики не занят целиком, отказов по сроку нет, `pending_requests` — наблюдение» (п. 14). +19. **Pending (W4).** `alerts-check` печатает момент pending рядом с каждой строкой firing (`pending_note`): worker, + relay, медленная БД, недоступная БД — оба оповещения; «not observed» — если опрос раз в 5 с pending не застал. +20. **Срок медленной БД (S1).** firing через 165 с при сроке 180 с — время задают конвейер (экспорт SDK, сбор, слот точки + правила по 15 с) и `for` 1 мин, а не доля; срок сценария и `AC_SLOW_FIRING_S` — 4 мин. +21. **Описание с текущим значением (S3).** У `MessengerQueueMetricsMissing` `$value` от `absent()` всегда 1, у + `TelemetryTargetDown` — 0. Вместо пустого значения описание называет осмысленное: возраст последнего снимка очереди + relay за час (шаблон `query`: `time() - max(max_over_time(timestamp(…)[1h:15s]))`, «more than an hour ago», если + снимков не было) и у цели — `up` (`$value`) плюс число недоступных сейчас целей правила. Тесты — оба варианта + описания очереди и две цели разом. +22. **Без потерь и ряды relay (S4, S5).** `telemetry-check` в начале, до своих рестартов Collector и хранилищ, проверяет: + все три запроса панели потерь — 0, `TelemetryDataLoss` неактивно; «тихий» — без потерь последние 5 мин (окно + `rate()`), поэтому ожидание до 330 с с печатью времени ожидания: прогон сразу после `backend-outage` иначе видел бы + его потери. «Остановленный relay уходит из рядов» — опрос рядов глубины и возраста; `backend-outage` — ёмкость + очередей SDK span и журнала. diff --git a/openspec/changes/slo-alerts/specs/observability/spec.md b/openspec/changes/slo-alerts/specs/observability/spec.md index b46b4cd..7a210f1 100644 --- a/openspec/changes/slo-alerts/specs/observability/spec.md +++ b/openspec/changes/slo-alerts/specs/observability/spec.md @@ -54,8 +54,10 @@ SHALL быть по меньшей мере: #### Scenario: SLO считается - **WHEN** стенд работает с трафиком не меньше 15 минут, и проверка читает SLI через источник Prometheus в Grafana -- **THEN** каждое из трёх SLI за 7 суток — число от 0 до 1 по рядам правил записи, за последний час оно отличается от того - же SLI по исходным счётчикам не больше чем на 1 процентный пункт, а dashboard показывает SLI, SLO и остаток бюджета +- **THEN** каждое из трёх SLI за 7 суток — число от 0 до 1 по рядам правил записи, за последний час SLI по рядам правил + отличается от SLI по исходным счётчикам в тех же 5-минутных окнах (сумма их `increase(…[5m])` на время каждой точки + правил) не больше чем на 1 процентный пункт, у доступности и задержки — и от `increase` исходных счётчиков одним окном + того же интервала, а dashboard показывает SLI, SLO и остаток бюджета #### Scenario: Отказ БД виден в SLI доступности @@ -146,15 +148,16 @@ SHALL печатать таблицу «шаг → ожидаемо → полу #### Scenario: Медленная БД - **WHEN** под нагрузкой запись сообщений ждёт блокировку таблицы в PostgreSQL -- **THEN** `MessengerSlowRequests` в firing не позже чем через 3 минуты, в медленных трассах отправки больше половины +- **THEN** `MessengerSlowRequests` в firing не позже чем через 4 минуты, в медленных трассах отправки больше половины времени server span занимают span PostgreSQL, занятость пула выше, чем до отказа, CPU реплик ниже половины предела, `MessengerHighErrorRate` не срабатывает, а после снятия блокировки оповещение снято не позже чем через 4 минуты #### Scenario: Медленный handler не путается с БД - **WHEN** участники параллельно входят по Basic, и вход медленнее 0,25 с -- **THEN** в трассах входа span PostgreSQL занимают меньше пятой части времени server span, ожидающих соединения пула нет, а - `MessengerSlowRequests` остаётся неактивным +- **THEN** в трассах входа span PostgreSQL занимают меньше пятой части времени server span, пул ни одной реплики не занят + целиком и отказов по сроку ожидания пула нет (`pending_requests` — наблюдение), а `MessengerSlowRequests` остаётся + неактивным #### Scenario: Недоступная БД @@ -227,7 +230,8 @@ test` проходит, вложения становятся `ready`, 5xx из- - **WHEN** Collector остановлен под нагрузкой дольше, чем нужно для заполнения очередей SDK, а затем запущен - **THEN** после возврата у реплик API выросли счётчики отброшенного из-за полной очереди или неудачных отправок SDK, - ёмкость очередей SDK — как в `[telemetry]`, а записей Loki из окна отказа меньше, чем записей stdout за то же время + ёмкость очередей SDK — как в `[telemetry]`, а записей Loki из окна отказа меньше, чем записей stdout за то же время, и + эти потери SDK видно на панели потерь #### Scenario: Потери Collector при недоступном хранилище diff --git a/openspec/changes/slo-alerts/tasks.md b/openspec/changes/slo-alerts/tasks.md index aada2fc..8f28dde 100644 --- a/openspec/changes/slo-alerts/tasks.md +++ b/openspec/changes/slo-alerts/tasks.md @@ -161,3 +161,45 @@ - [x] 11.5 Числа и наблюдения инцидентов в `REPORT.md` из 11.2–11.4, ссылки `REPORT.md` и `AGENTS.md` на файлы evidence и их commit; `graphify update .`. Проверка: файлы, названные в `REPORT.md`, существуют; у каждого инцидента — шаги со ссылкой на строки evidence. + +## 12. Замечания проверки (verify 2026-11-14) + +Код change — commit `15ea156`, evidence — `107fe7f`. Находки W1–W4, S1–S5 verify; решения без пользователя — design, +«Уточнения apply», пп. 17–22, и `QUESTIONS.md`, `## slo-alerts`, «Решения apply по verify». + +- [x] 12.1 W1, первая потеря процесса SDK на панели потерь: в `rules.yml` к `telemetry:lost_items:total` — `or sum by (job, + instance) (otel_sdk_processor_span_queue_capacity) * 0` (ряд процесса SDK с нуля с его запуска); `TelemetryDataLoss` не + меняется. Тест `rules.test.yml`: ёмкость с начала, потеря позже — `increase(telemetry:lost_items:total[5m])` равен потере, + до потери ряд 0, оповещение с тем же значением. Дельта `observability`, «Потери SDK при недоступном Collector»: «и это + видно на панели потерь»; `backend-outage` проверяет панель 40 (запрос A из dashboard) в шагах `[tempo long]` / + `[loki long]` (Collector) и `[collector]` (SDK реплик). Проверка: новый тест красный на прежнем правиле (вывод в отчёте) и + зелёный после; на стенде после рестарта Prometheus ряд правила есть у каждого процесса SDK со значением ≥ 0. +- [x] 12.2 W2: `REPORT.md`, формулы SLI — сверка путей описана как в ограничениях (панели 26 и 28 — по рядам правил, + `alerts-check` — сумма `increase(…[5m])` исходных счётчиков в тех же окнах и `increase` одним окном часа). Проверка: текст + не противоречит разделу «Ограничения SLI» и `sli_rows` драйвера. +- [x] 12.3 W3: дельта `observability` — THEN «SLO считается» (те же 5-минутные окна; у доступности и задержки — и `increase` + одним окном того же интервала) и «Медленный handler не путается с БД» (пул ни одной реплики не занят целиком, отказов по + сроку нет, `pending_requests` — наблюдение); `alerts-check` — строка сверки SLI доступности и задержки с `increase` одним + окном часа (≤ 1 п. п.); вопрос verify в `QUESTIONS.md` закрыт ответом. Проверка: `openspec validate slo-alerts --strict`, + `py_compile`. +- [x] 12.4 W4: `alerts-check` печатает момент pending рядом с каждой строкой firing (worker, relay, медленная БД, недоступная + БД — оба оповещения). Проверка: `py_compile`; в коде у каждого `alert_row` firing — `pending_note`. +- [x] 12.5 S1: медленная БД — firing не позже 4 мин (дельта «Медленная БД», `AC_SLOW_FIRING_S` = 240, комментарии + драйвера). Проверка: `grep` срока в спеке и драйвере. +- [x] 12.6 S2: `REPORT.md` — тесты правил записи названы блоками и проверками выражений, число — после 12.1 и 12.7 (по + `rules.test.yml`); `rules-test.md` — при пересъёмке (12.10). Проверка: счёт по файлу тестов. +- [x] 12.7 S3: `description` у `MessengerQueueMetricsMissing` — возраст последнего снимка очереди (шаблон `query`), у + `TelemetryTargetDown` — `up` цели (`$value`) и число недоступных целей правила; тесты `exp_annotations`. Проверка: `make + alerts_test`. +- [x] 12.8 S4: `telemetry-check` — запросы панели потерь (id 40) на тихом стенде дают 0, `TelemetryDataLoss` неактивно + (ожидание тишины до 330 с, время ожидания печатается). Проверка: `py_compile`; функция на стенде — 0. +- [x] 12.9 S5: «Остановленный relay уходит из рядов» — опрос рядов глубины и возраста очереди; `backend-outage` — ёмкость + очередей SDK span и журнала. Проверка: `py_compile`. +- [x] 12.10 Применение и регрессия: Prometheus и Grafana перезапущены с новыми файлами (правила загружены без ошибок, + dashboard provisioned); `make lint`, `make alerts_test`, `make service_test`, `py_compile` драйвера системным `python3`, + `docker compose config --quiet`, `openspec validate slo-alerts --strict`, `make test`; стенд в штатном состоянии. + Проверка: коды 0, `make lb_stats` — `UP` без ручных состояний. +- [ ] 12.11 Пересъёмка evidence на commit правок (после коммита основной сессией): `make alerts_test` → + `evidence/alerts/rules-test.md` (счёт S2), `alerts-check` → `evidence/alerts/check.md`, `telemetry-check` → + `evidence/telemetry/check.md`, `backend-outage` → `evidence/telemetry/backend-outage.md`; числа и ссылки на строки в + `REPORT.md`. Проверка: коды 0; сценарии 11.1–11.3 и новые строки (панель потерь, pending, одно окно).