diff --git a/.env.example b/.env.example index aa74772..c08340f 100644 --- a/.env.example +++ b/.env.example @@ -267,6 +267,25 @@ ORCH_REAPER_MAX_RUNNING_S=3600 ORCH_REAPER_FINALIZE_GRACE_S=300 ORCH_LEASE_RECLAIM_ENABLED=true +# ORCH-063: disk-watchdog — background heartbeat that measures HOST-FS fill via the +# mounted bind-paths (/repos, /app/data) with shutil.disk_usage (NOT the container +# overlay /) and Telegram-alerts the operator at >= threshold. On 07.06.2026 the +# mva154 host disk silently hit 100% and stalled the WHOLE self-hosting pipeline; +# this is the missing proactive signal. Daemon thread modelled on reconciler/reaper +# (start/stop in main.lifespan, /queue snapshot, never-raise). Anti-spam state is +# in-memory (no DB migration); the watchdog only READS fill and SENDS Telegram — it +# never touches the disk/container or restarts prod (self-hosting safety). +# DISK_MONITOR_ENABLED -> kill-switch; false -> the daemon does not start (1:1 as before). +# DISK_MONITOR_INTERVAL_S -> heartbeat measurement period, seconds (order of minutes). +# DISK_MONITOR_THRESHOLD_PCT -> fill % that triggers the alert (Owner-fixed 85; valid 1..100). +# DISK_MONITOR_REALERT_S -> cooldown between repeat alerts while above threshold (~6h). +# DISK_MONITOR_PATHS -> CSV of monitored HOST bind-paths; empty -> /repos,/app/data. +ORCH_DISK_MONITOR_ENABLED=true +ORCH_DISK_MONITOR_INTERVAL_S=300 +ORCH_DISK_MONITOR_THRESHOLD_PCT=85 +ORCH_DISK_MONITOR_REALERT_S=21600 +ORCH_DISK_MONITOR_PATHS=/repos,/app/data + # ORCH-022: security-gate (secret-scanning + dependency audit) on the # deploy-staging -> deploy edge, run FIRST among the edge sub-gates. Deterministic # (no LLM): gitleaks (offline secret-scan, pinned Go binary in the image) + pip-audit diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d0a815..b01e1a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,12 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **Disk-watchdog: мониторинг заполнения диска mva154 + Telegram-алерт при ≥85%** (ORCH-063, `feat`): новый фоновый daemon-поток `src/disk_watchdog.py` (каркас `reconciler`/`job_reaper`) — недостающий **проактивный** сигнал о заполнении хост-диска (07.06.2026 диск mva154 тихо дорос до 100% и положил весь self-hosting-конвейер всех проектов). **Аддитивно, never-raise:** `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — **не тронуты**, новой миграции нет (состояние анти-спама — in-memory). + - **Замер хост-ФС (FR-2/AC-8):** каждые `disk_monitor_interval_s` (дефолт 300с) меряет заполнение **смонтированных хост-bind-путей** (`/repos`, `/app/data`) через stdlib `shutil.disk_usage` — НЕ overlay `/` контейнера, НЕ субпроцесс `df`; дедуп путей по физическому устройству (`st_dev`) → один алерт на раздел. Недоступный путь → пропуск с warning, остальные пути меряются (per-path never-raise). + - **Решение об алерте (FR-3/FR-4/AC-2..AC-4):** pure-функция `decide_action(used_pct, threshold, prev_state, now, realert_s)` (юнит-тестируема без потока/таймера, время инъецируется): алерт на пересечении порога (дефолт **85%**, граница `>=` включительно), cooldown-повтор `disk_monitor_realert_s` (~6ч, анти-спам — не на каждом тике), однократный recovery при возврате ниже порога. Алерт — `send_telegram` (notifying, не silent), best-effort. + - **Конфигурируемость + kill-switch (FR-5/AC-5):** флаги `disk_monitor_enabled`/`_interval_s`/`_threshold_pct`/`_realert_s`/`_paths` (`src/config.py`, env `ORCH_DISK_MONITOR_*`) с defensive-валидацией (порог 1..100, интервалы > 0 → невалидное к дефолту + warning). `disk_monitor_enabled=false` → демон не стартует (старт/стоп в `main.lifespan`, гард), `GET /queue` → `{"enabled": false}` — поведение 1:1 как сейчас. + - **Наблюдаемость (FR-6/AC-7):** аддитивный read-only блок `disk_monitor` в `GET /queue` (`enabled`/`threshold_pct`/`interval_s`/`realert_s`/`last_run_ts`/`paths`[`used_pct`/`free_gb`/`free_pct`/`alerting`/`last_alert_at`]); существующие ключи `/queue` не изменены; `status()` never-raise. + - **Self-hosting безопасность (NFR-6):** watchdog только читает заполнение и шлёт уведомление — не трогает диск/контейнер, не рестартит прод; безопасен для enduro-trails в общем инстансе. Откат тривиален (`ORCH_DISK_MONITOR_ENABLED=false`, миграций нет). Тесты: `tests/test_disk_watchdog.py` (TC-01..TC-12, 18 кейсов); полный регресс `tests/` зелёный (1296). Документация: `docs/architecture/README.md` (компонент + блок `/queue`), `docs/operations/INFRA.md` (что мониторится/порог/как отключить/реакция на алерт), `.env.example`. ADR: `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md`, сквозной `docs/architecture/adr/adr-0024-disk-watchdog.md`. - **Промпт-аудит 6 агентов: расхардкод даты/модели, сверка гейтов, escalation, чистка** (ORCH-092 / эпилог эпика ORCH-52, `docs`): точечная правка 6 системных промптов `.openclaw/agents/*.md` + анти-регресс-тестов, устраняющая класс дефектов промптов (хардкод даты/модели в примерах, размазанная эскалация, нереализуемая/конфликтующая инструкция rebase, мёртвая инструкция reviewer, недообогащённый tester). **Docs/prompts-only:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, состав machine-verdict ключей и схема БД — **не тронуты**; `frontmatter_validation_strict` остаётся `False`. Машинные verdict-ключи (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:` + значения APPROVED/REQUEST_CHANGES/PASS/FAIL/SUCCESS/FAILED) и канон 52d/52c/52e (5 секций, 6 полей) — байт-в-байт. - **Расхардкод даты/модели (FR-1/FR-2, AC-1/AC-2):** во всех 6 промптах копируемые примеры frontmatter несут плейсхолдеры `created_at: ` / `model_used: ` + явную врезку «не копируй буквально: подставь `date +%F` и фактическую модель из конфига». Литерал `claude-opus-4-8` остаётся лишь как справка в таблице полей (вне копируемого блока). - **Сверка имён гейтов (FR-3, AC-3):** все `check_*` в 6 промптах сверены с реестром `QG_CHECKS` — несовпадений нет (`check_tests_passed` подтверждён валидным, не «исправлен вслепую»); закреплено интеграционным тестом. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 16da09e..497b78d 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -13,6 +13,7 @@ - **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe. **ORCH-026:** `claim_next_job` гейтит задачи с незавершёнными зависимостями (`job_deps`, `NOT EXISTS`) без занятия слота; декларации/циклы — leaf `src/task_deps.py`. - **Job-reaper** (`src/job_reaper.py`, ORCH-065 — [adr-0011](adr/adr-0011-job-reaper-lease-reclaim.md)) — фоновый daemon-поток (каркас `reconciler`), стартует/останавливается в `main.lifespan` (после `reconciler.start()` / перед `worker.stop()`). Детектирует «мёртвый» `running`-job **без рестарта** процесса (Tier-1 мёртвый `jobs.pid` после `reaper_dead_ticks` тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running`; Tier-3 backstop `reaper_max_running_s`) и приводит строку к корректному статусу через те же контракты (`_try_advance_stage`/`_finalize_job`, gate-driven; exit≠0/неизвестно → `attempts Сквозной (cross-cutting) ADR: вводит **новый фоновый компонент** оркестратора в ряду +> `reconciler` (adr-0007) и `job_reaper` (adr-0011). Детальное решение задачи — +> `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md`. + +## Статус +Proposed (ORCH-063) + +## Контекст +07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь self-hosting-конвейер** (один +прод-инстанс `orchestrator` обслуживает все прод-проекты из общей БД/очереди). Проактивного сигнала +о заполнении диска у системы не было. Оркестратор уже имеет два проверенных фоновых daemon-потока с +единым каркасом (`threading.Thread(daemon=True)` + `threading.Event`, `start/stop/status`, +never-raise, снимок в `GET /queue`): `reconciler` (ORCH-053) и `job_reaper` (ORCH-065). Новый +эксплуатационный watchdog логично встроить тем же паттерном. + +## Решение +Вводится третий фоновый компонент **disk-watchdog** (`src/disk_watchdog.py`): +- **Калька каркаса** `reconciler`/`reaper`: daemon-поток, чистый stop через `_stop.wait(interval)`, + контракт `start()`/`stop(timeout)`/`status()`, старт/стоп в `main.lifespan` (старт последним — + после `reaper.start()`; стоп первым в reverse-порядке), наблюдаемость — аддитивный блок + `disk_monitor` в `GET /queue`. +- **Замер** заполнения **хост-ФС** через смонтированные bind-пути (`/repos`, `/app/data`) stdlib + `shutil.disk_usage` (не overlay `/` контейнера, не субпроцесс `df`); дедуп путей по `st_dev`. +- **Решение об алерте** — pure-функция от `(used_pct, threshold, prev_state, now, realert_s)`: + алерт на пересечении порога (дефолт 85%), ограниченный cooldown-повтор, recovery при возврате + ниже порога. Состояние анти-спама — in-memory (без миграции БД). +- **Алерт** — `send_telegram` (notifying), best-effort. Kill-switch `disk_monitor_enabled`. +- **Только сигнал, не лечение:** watchdog читает и уведомляет, не трогает диск/контейнер, не + рестартит прод (self-hosting безопасность). Авто-очистка диска — отдельная задача. + +**Инварианты:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, схема БД — **не меняются** +(watchdog — эксплуатационный демон, не Quality Gate, как `reconciler`/`reaper`). never-raise на +уровнях per-path / per-tick / per-send. При выключенном kill-switch — поведение 1:1 как сейчас +(нулевая регрессия для enduro-trails). + +## Последствия +- **+** Ранний сигнал предотвращает групповой простой всех проектов; дёшево, без внешних + зависимостей (принцип «всё в Docker на одном сервере, минимум зависимостей»). +- **+** Знакомый паттерн фонового демона → низкий риск, простое сопровождение. +- **−** In-memory состояние / best-effort Telegram — допустимы для раннего сигнала (не SLA). +- **Откат:** `ORCH_DISK_MONITOR_ENABLED=false`; миграций БД нет. + +## Ссылки +- Задачный ADR: `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md` +- Родственные компоненты: [adr-0007-reconciler.md](adr-0007-reconciler.md), + [adr-0011-job-reaper-lease-reclaim.md](adr-0011-job-reaper-lease-reclaim.md) +- Топология host-разделов: `docs/operations/INFRA.md` + diff --git a/docs/operations/INFRA.md b/docs/operations/INFRA.md index 3eb70aa..cf56ade 100644 --- a/docs/operations/INFRA.md +++ b/docs/operations/INFRA.md @@ -58,6 +58,27 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл - `~/.orchestrator-ssh` → `/home/slin/.ssh` (ro, деплой по ssh; target в HOME агента, согласован с `HOME=/home/slin` из launcher — ORCH-040, ранее `/root/.ssh`) +### Disk-watchdog: мониторинг заполнения диска mva154 (ORCH-063) +07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь конвейер всех проектов** +(один прод-инстанс `orchestrator` на общей БД/очереди). Чтобы такой инцидент сигнализировался +**заранее**, работает фоновый daemon-поток `src/disk_watchdog.py` (каркас `reconciler`/`job_reaper`): +- **Что мониторится:** заполнение **хост-разделов** по смонтированным bind-путям (`/repos` → + host `/home/slin/repos`, `/app/data` → host `./data`) через stdlib `shutil.disk_usage` — НЕ + overlay `/` контейнера (иначе замер ложно-низкий). Пути с одним физическим устройством (`st_dev`) + дедуплицируются → один алерт, не два. +- **Порог и период:** при заполнении **≥ 85%** (`ORCH_DISK_MONITOR_THRESHOLD_PCT`) шлётся + Telegram-алерт оператору; замер — раз в 300с (`ORCH_DISK_MONITOR_INTERVAL_S`). Пока диск выше + порога, повтор — не чаще раза в ~6ч (`ORCH_DISK_MONITOR_REALERT_S`, анти-спам). При возврате + ниже порога — однократное recovery-сообщение. +- **Как отключить:** `ORCH_DISK_MONITOR_ENABLED=false` (демон не стартует; `GET /queue` → + `disk_monitor.enabled=false`; поведение 1:1 как сейчас). Наблюдаемость — блок `disk_monitor` в + `GET /queue` (последний замер: `used_pct`/`free_gb`/`alerting`/`last_alert_at` по каждому пути). +- **Что делать при алерте:** watchdog **только сигнализирует** — он не трогает диск/контейнер и не + рестартит прод (self-hosting безопасность). Освобождение места — **ручная** операция оператора: + типовые «пожиратели» — старые worktree-каталоги `/home/slin/repos/_wt/*` завершённых задач, + логи, dangling Docker-образы/слои (`docker image prune`, `docker builder prune`). Авто-очистка — + вне объёма ORCH-063 (отдельная задача). + ## Переменные окружения (карта; значения — в `.env`) | Переменная | Назначение | @@ -91,6 +112,11 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл | `ORCH_RECONCILE_GRACE_DEFAULT_S` | порог «застряла» по `tasks.updated_at`, сек; дефолт `600` | | `ORCH_RECONCILE_GRACE_OVERRIDES_JSON` | per-stage пороги, напр. `{"development":300}`; невалидный JSON → дефолт | | `ORCH_RECONCILE_NOTIFY_UNBLOCK` | слать Telegram при разблокировке застрявшей задачи; дефолт `true` | +| `ORCH_DISK_MONITOR_ENABLED` | kill-switch disk-watchdog (ORCH-063); дефолт `true`. `false` → демон не стартует, поведение 1:1 как сейчас | +| `ORCH_DISK_MONITOR_INTERVAL_S` | период heartbeat-замера заполнения диска, сек; дефолт `300` | +| `ORCH_DISK_MONITOR_THRESHOLD_PCT` | порог заполнения для алерта, %; дефолт `85` (валидация 1..100, иначе → дефолт) | +| `ORCH_DISK_MONITOR_REALERT_S` | cooldown повторного алерта, пока выше порога, сек; дефолт `21600` (~6 ч) | +| `ORCH_DISK_MONITOR_PATHS` | CSV отслеживаемых **хост**-bind-путей; пусто → `/repos,/app/data` | | `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука | **Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`. diff --git a/docs/work-items/ORCH-063/00-business-request.md b/docs/work-items/ORCH-063/00-business-request.md new file mode 100644 index 0000000..59456c4 --- /dev/null +++ b/docs/work-items/ORCH-063/00-business-request.md @@ -0,0 +1,7 @@ +# Business Request: INFRA: мониторинг диска mva154 + алерт при >85% + +Work Item ID: ORCH-063 + +## Description + +TBD diff --git a/docs/work-items/ORCH-063/01-brd.md b/docs/work-items/ORCH-063/01-brd.md new file mode 100644 index 0000000..56ad6a8 --- /dev/null +++ b/docs/work-items/ORCH-063/01-brd.md @@ -0,0 +1,147 @@ +--- +work_item: ORCH-063 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 01 — BRD (бизнес-требования): ORCH-063 — INFRA: мониторинг диска mva154 + алерт при >85% + +Work Item: **ORCH-063** · Repo: **orchestrator** (self-hosting) · Стадия: analysis +Заказчик: Слава (Владелец/оператор) +Тип: INFRA · Приоритет: **P1** + +--- + +## 1. Бизнес-контекст и проблема + +### 1.1. Инцидент (установленный факт) +**07.06.2026** диск на хосте **mva154** (`slin@82.22.50.71`) незаметно дорос до **100%** и положил +**весь конвейер**: CI стал красным, очередь Gitea застряла. Сбой произошёл **тихо** — не было +ни одного предупреждающего сигнала до полного исчерпания диска. Разбор был ручным и пост-фактум. + +### 1.2. Корневая боль +У оркестратора **нет проактивного сигнала о заполнении диска**. Диск хоста заполняется накопительно +и предсказуемо (git-worktree в `/repos/_wt/...`, образы Docker, БД `./data/orchestrator.db`, логи), +но оператор узнаёт о проблеме только когда уже **поздно** — конвейер всех проектов (self-hosting: +`orchestrator` + `enduro-trails` из одного инстанса) уже встал. + +### 1.3. Self-hosting контекст (групповой риск) +Прод-инстанс `orchestrator` (8500) — ОДИН на ВСЕ прод-проекты, с общей БД и общей очередью +(`docs/operations/INFRA.md`). Исчерпание диска роняет конвейер **всех** проектов сразу. Ранний +сигнал (heartbeat-watchdog) — дешёвая страховка от дорогого группового простоя. + +### 1.4. Что нужно (формулировка Владельца) +**Heartbeat-watchdog:** периодически измерять заполнение диска (`df`); при превышении порога +**85%** — слать алерт Славе (Telegram). Сигнал должен прийти **заранее**, пока есть запас места +на ручную/будущую авто-очистку. + +--- + +## 2. Объём (scope) + +### 2.1. В объёме +- **Фоновый watchdog-демон** (по образцу `reconciler`/`job_reaper`, ORCH-053/065): периодически + семплит заполнение хост-ФС, на которой живут рабочие данные оркестратора (репозитории, БД, + Docker), и при пересечении порога шлёт Telegram-алерт оператору. +- **Конфигурируемый порог** (дефолт **85%**), период опроса, kill-switch. +- **Анти-спам:** алерт по факту пересечения порога + ограниченное по частоте повторение, пока + заполнение выше порога (а не на каждом тике); сообщение о возврате «ниже порога» (recovery). +- **Наблюдаемость** последнего замера/состояния алерта в `GET /queue` (read-only). +- **never-raise:** любой сбой watchdog не влияет на конвейер. + +### 2.2. Вне объёма (явно, не делать) +- **Авто-очистка / garbage collection диска** (прунинг старых worktree, образов, логов, vacuum БД) — + отдельная задача; ORCH-063 только **сигнализирует**, не **лечит**. +- Интеграция с внешними системами мониторинга (Prometheus/Grafana/Zabbix), метрики/экспортёры. +- Алерт-каналы кроме существующего Telegram (`send_telegram`). +- Мониторинг ресурсов кроме диска (CPU/RAM/inode — возможное расширение, не сейчас; inode — + кандидат на follow-up, см. §8 R-4). +- Мониторинг нескольких хостов / удалённый сбор (только локальный хост текущего инстанса). +- Изменение `STAGE_TRANSITIONS`, реестра `QG_CHECKS`, стадий конвейера, схемы БД-контрактов. + +--- + +## 3. Заинтересованные стороны +- **Владелец/оператор (Слава):** получает алерт, выполняет ручную очистку/реакцию; принимает + результат. +- **Self-hosting прод (`orchestrator`):** обслуживает enduro-trails из того же инстанса — watchdog + не должен мешать/ронять конвейер (изоляция через never-raise). +- **Все прод-проекты:** косвенные бенефициары — ранний сигнал предотвращает групповой простой. + +--- + +## 4. Бизнес-требования (BR) + +| ID | Требование | Связь | +|----|------------|-------| +| BR-1 | Оркестратор **периодически** (heartbeat) измеряет заполнение хост-файловой системы, на которой растут его рабочие данные (репозитории `/repos`, БД `/app/data`, Docker). | FR-1, AC-1 | +| BR-2 | При достижении/превышении **порога заполнения** (дефолт **85%**) оператор получает **Telegram-алерт** с действенными деталями: точка монтирования/путь, занято %, свободно (ГБ/%). | FR-2, FR-3, AC-2 | +| BR-3 | **Анти-спам:** алерт шлётся при **пересечении** порога (переход «ниже→на/выше»), а далее повторяется не чаще, чем раз в настраиваемый период (`re-alert`), пока заполнение остаётся выше порога — конвейер/чат не заваливается одинаковыми сообщениями на каждом тике. | FR-4, AC-3 | +| BR-4 | При возврате заполнения **ниже порога** состояние алерта сбрасывается и отправляется однократное сообщение восстановления «диск ниже порога» (recovery), чтобы оператор знал, что инцидент снят. | FR-4, AC-4 | +| BR-5 | Порог, период опроса, период повторного алерта и набор отслеживаемых путей **конфигурируемы**; есть **kill-switch** для полного отключения watchdog (нулевая регрессия). | FR-5, AC-5 | +| BR-6 | **never-raise:** любая ошибка измерения/отправки алерта/самого демона **не роняет** и не блокирует конвейер (фоновый поток, изолированный как `reconciler`/`reaper`). | NFR-1, AC-6 | +| BR-7 | Текущее состояние watchdog (последний замер по путям, состояние алерта, время последнего алерта, порог/период) наблюдаемо в `GET /queue` (read-only). | FR-6, AC-7 | +| BR-8 | Watchdog стартует/останавливается вместе с приложением (в `main.lifespan`) и не требует ручного запуска. | FR-1, AC-8 | + +--- + +## 5. Нефункциональные требования (NFR) + +| ID | Требование | +|----|------------| +| NFR-1 | **never-raise / изоляция:** watchdog — отдельный daemon-поток (паттерн `reconciler`/`job_reaper`); исключение в тике логируется и не прерывает ни поток, ни конвейер. | +| NFR-2 | **Дешевизна:** замер диска — лёгкая операция (предпочтительно stdlib `shutil.disk_usage`, без тяжёлого порождения процессов на каждом тике); период опроса по умолчанию — порядка минут (не секунд), чтобы не создавать нагрузки. | +| NFR-3 | **Корректность источника замера (self-hosting):** измеряется заполнение **хост-ФС**, а не overlay-ФС контейнера. Контейнер видит хост-разделы через bind-mount'ы (`/repos`, `/app/data`); замер обязан отражать раздел(ы), которые реально заполняются на хосте (см. §6). | +| NFR-4 | **Нулевая регрессия:** при выключенном kill-switch поведение приложения идентично текущему; enduro-trails и конвейер не затрагиваются. | +| NFR-5 | **Инварианты неизменны:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, существующие таблицы-контракты БД — не меняются. Допустимо не вводить новую миграцию (состояние watchdog — best-effort, может жить в памяти). | +| NFR-6 | **Self-hosting безопасность:** watchdog только **читает** заполнение и **шлёт** уведомление — не выполняет действий над диском/контейнером, не рестартит прод. | + +--- + +## 6. Допущения и ограничения + +- **Видимость хост-диска из контейнера.** Оркестратор бежит в контейнере с `network_mode: host` и + bind-mount'ами `/home/slin/repos → /repos`, `./data → /app/data`, `/var/run/docker.sock` + (`docs/operations/INFRA.md`). Замер `shutil.disk_usage()`/`df` по **смонтированному пути** + (`/repos`, `/app/data`) отражает заполнение **хост-раздела**, который этот путь подмонтировал — + именно той ФС, что переполнилась 07.06. Замер по `/` (overlay контейнера) **нерепрезентативен** и + не должен использоваться как источник истины. +- **Один заполняющийся раздел.** На mva154, вероятно, рабочие данные (`/home/slin/repos`, + `./data`, Docker) лежат на одном host-разделе; набор отслеживаемых путей по умолчанию должен + покрывать его и при совпадении физического устройства не дублировать алерт (дедуп по устройству — + желательное, не блокирующее требование; решение — за архитектором). +- **Best-effort алертинг.** Доставка Telegram не гарантирована (та же `send_telegram`, never-raise); + watchdog — ранний сигнал, не SLA-гарантия. Состояние анти-спама может быть in-memory (после + рестарта допустим повторный алерт, если всё ещё выше порога — это безопасно). +- **Порог 85%** — зафиксирован Владельцем как дефолт; конфигурируем (BR-5) на случай тюнинга. +- **Только сигнал, не лечение.** Авто-освобождение места — вне объёма (§2.2). + +--- + +## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md) +- AC-1 watchdog периодически измеряет заполнение хост-ФС и стартует с приложением. +- AC-2 при ≥85% оператор получает Telegram-алерт с действенными деталями. +- AC-3 анти-спам: один алерт на пересечение + ограниченное повторение, не на каждом тике. +- AC-4 возврат ниже порога → сброс состояния + recovery-сообщение. +- AC-5 порог/период/пути/kill-switch конфигурируемы; выключение → нулевая регрессия. +- AC-6 любой сбой watchdog не роняет конвейер (never-raise). +- AC-7 состояние watchdog видно в `GET /queue`. + +--- + +## 8. Риски (детали — 10-tech-risks.md, заполняет архитектор) +- **R-1** — замер по неверной ФС (overlay `/` контейнера вместо хост-раздела) → ложно-низкое + заполнение → watchdog «молчит» при реально полном хосте (повтор инцидента 07.06). Митигировать: + замер по bind-mount-путям хост-разделов (NFR-3). +- **R-2** — спам-алерты на каждом тике при длительном превышении порога → шум, оператор глохнет к + сигналу. Митигировать: анти-спам/cooldown (BR-3). +- **R-3** — порог 85% слишком близок к 100% при быстром росте (один большой build/worktree) → + оператор не успевает среагировать. Зафиксирован как дефолт Владельцем; конфигурируемость (BR-5) + оставляет рычаг. Возможный follow-up — второй «критический» порог (напр. 95%) с более громким + алертом (кандидат, не в объёме). +- **R-4** — исчерпание **inode** (а не байтов) тоже валит ФС, но не ловится замером по %-байтам. + Кандидат на расширение (вне объёма ORCH-063). +- **R-5** — `df`/субпроцесс на каждом тике — лишняя нагрузка; предпочесть stdlib (NFR-2). diff --git a/docs/work-items/ORCH-063/02-trz.md b/docs/work-items/ORCH-063/02-trz.md new file mode 100644 index 0000000..8913f5a --- /dev/null +++ b/docs/work-items/ORCH-063/02-trz.md @@ -0,0 +1,186 @@ +--- +work_item: ORCH-063 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 02 — ТЗ (TRZ): ORCH-063 — INFRA: мониторинг диска mva154 + алерт при >85% + +Work Item: **ORCH-063** · Repo: **orchestrator** · Стадия: analysis + +> ТЗ описывает **что** и **где** должно измениться (модули/контракты/артефакты), выведенное из BRD и +> фактического кода. **Как** (точная структура демона, способ замера, хранение состояния анти-спама, +> точки врезки) — решает архитектор в `06-adr/`. ТЗ фиксирует требования и границы. + +--- + +## 1. Сводка изменения + +Ввести **disk-watchdog** — фоновый daemon-поток (по образцу `reconciler`/`job_reaper`), который +периодически (heartbeat) измеряет заполнение **хост-файловой системы** через смонтированные в +контейнер bind-пути и при пересечении настраиваемого порога (дефолт **85%**) шлёт **Telegram-алерт** +оператору. Анти-спам (алерт на пересечение + ограниченное повторение + recovery при возврате ниже +порога), наблюдаемость в `GET /queue`, kill-switch, never-raise. **Машина стадий, реестр QG и схема +БД-контрактов не меняются; новой миграции не требуется.** + +--- + +## 2. Задействованные модули / пути + +| Путь | Действие | +|------|----------| +| `src/disk_watchdog.py` *(новый leaf-модуль; имя — на усмотрение архитектора)* | **создать** — чистая логика замера + решение об алерте (pure, тестируемо) + daemon-обёртка (`threading.Thread(daemon=True)` + `threading.Event`, `start`/`stop`/`status`), never-raise. Образец: `src/reconciler.py`, `src/job_reaper.py`. | +| `src/config.py` | **изменить** — добавить флаги фичи (см. §8). | +| `src/main.py` | **изменить** — `start()`/`stop()` watchdog в `lifespan` (после `reaper.start()` / в reverse-порядке на shutdown); добавить read-only блок `disk_monitor` в `GET /queue`. | +| `src/notifications.py` | **изменить (опц.)** — переиспользовать `send_telegram(text)` (notifying) напрямую из watchdog **или** добавить тонкий helper `notify_disk_alert(...)`/`notify_disk_recovery(...)` (never-raise). Выбор — архитектор. | +| `.env.example` | **изменить** — задокументировать новые `ORCH_DISK_*` переменные (дескрипторы, без значений-секретов). | + +> Чистую логику (замер по путям, дедуп по устройству, решение «алертить / повторить / recovery» как +> функция от текущего %, порога и предыдущего состояния) держать в **leaf-модуле**, never-raise, по +> образцу `src/task_deps.py` / `src/post_deploy.py` — для юнит-тестируемости без фонового потока. + +--- + +## 3. Функциональные требования + +### FR-1 — Heartbeat-демон (BR-1, BR-8) +- Фоновый daemon-поток измеряет заполнение диска каждые `disk_monitor_interval_s` секунд. +- Стартует/останавливается в `main.lifespan` (паттерн `reconciler.start()`/`reaper.start()` и reverse + на shutdown). Период — `threading.Event().wait(interval)` (чистый stop, как `reconciler._run`). +- Контракт демона: `start()`, `stop(timeout)`, `status() -> dict` (для `/queue`). + +### FR-2 — Замер заполнения хост-ФС (BR-1, NFR-3) +- Для каждого пути из `disk_monitor_paths` измерить заполнение (`used/total`, %), свободно (байты/%). +- **Источник — смонтированные хост-пути**, а не overlay `/` контейнера (NFR-3): дефолтный набор + путей должен покрывать раздел(ы), на которых растут рабочие данные оркестратора — `/repos` + (host `/home/slin/repos`) и `/app/data` (host `./data`). Способ замера — предпочтительно stdlib + `shutil.disk_usage(path)` (без субпроцесса `df` на каждом тике, NFR-2); финальный выбор — архитектор. +- При совпадении физического устройства у нескольких путей — желательно не дублировать алерт (дедуп + по устройству `st_dev`/mount); требование «желательно», не блокирующее. +- Недоступный/несуществующий путь → пропуск этого пути с лог-warning, без падения тика. + +### FR-3 — Алерт при превышении порога (BR-2) +- Если заполнение пути **≥ `disk_monitor_threshold_pct`** (дефолт `85`) — сформировать и отправить + Telegram-алерт через `send_telegram` (notifying, **не** silent — это alert, как `notify_error`). +- **Содержимое алерта (действенное):** идентификатор хоста/пути (точка монтирования), занято %, + свободно (ГБ и/или %), порог. Текст — на русском, по стилю существующих `notify_*`-алертов. + +### FR-4 — Анти-спам, повтор и recovery (BR-3, BR-4) +- Решение об отправке — функция от `(current_pct, threshold, previous_state, now)`: + - **переход «ниже→на/выше порога»** → отправить алерт (первое пересечение); + - **остаётся выше порога** → повторно слать **не чаще**, чем раз в `disk_monitor_realert_s` + (cooldown), а не на каждом тике; + - **переход «выше→ниже порога»** → сбросить состояние алерта и отправить однократное + **recovery-сообщение** «диск ниже порога» (notifying). +- Состояние анти-спама может быть **in-memory** (best-effort; после рестарта допустим повторный + алерт, если всё ещё выше порога — безопасно, NFR-5). Время — через инъецируемый `now`-провайдер, + чтобы решение было тестируемо без реального таймера. + +### FR-5 — Конфигурируемость и kill-switch (BR-5, NFR-4) +- Поведение управляется флагами `config.py` (см. §8). При `disk_monitor_enabled=False` watchdog + **не запускается** (демон не стартует в `lifespan`) — нулевая регрессия. + +### FR-6 — Наблюдаемость (BR-7) +- `GET /queue` получает аддитивный read-only блок `disk_monitor` (по образцу блоков `reconcile`/ + `reaper`/`serial_gate`): `enabled`, `threshold_pct`, `interval_s`, `paths` с последним замером + (`used_pct`, `free_bytes`/`free_gb`), `alerting` (bool на путь/глобально), `last_alert_at`. + never-raise: при ошибке — минимальный словарь с флагами. + +--- + +## 4. Изменения API + +- **Новых обязательных endpoint'ов нет.** Снимок состояния отдаётся через существующий `GET /queue` + (аддитивный блок `disk_monitor`, §3/FR-6); существующие ключи ответа не меняются. +- Опционально (на усмотрение архитектора, **не обязательно**): отдельный `GET /disk` для on-demand + замера. Если вводится — задокументировать в README. Рекомендация: ограничиться блоком в `/queue`. + +--- + +## 5. Изменения схемы БД + +**Нет.** Состояние watchdog — best-effort, держится в памяти демона (NFR-5). Новых таблиц/колонок/ +миграций не вводится. `STAGE_TRANSITIONS`/`QG_CHECKS`/`tasks`/`jobs`/`agent_runs` — без изменений. + +> Если архитектор решит сделать состояние last-alert durable (переживающим рестарт) — допустима +> только **аддитивная, идемпотентная** миграция (`CREATE TABLE IF NOT EXISTS`), но это **не** +> требование ТЗ (по умолчанию — in-memory). + +--- + +## 6. Требования к новым/изменённым QG checks + +**Нет.** Watchdog — фоновый эксплуатационный демон, **не** Quality Gate стадии. Реестр `QG_CHECKS` и +`check_*` не трогаются (аналогично `reconciler`/`job_reaper`, которые тоже не являются QG). + +--- + +## 7. Совместимость / регресс + +- **Аддитивно:** новый leaf-модуль + точечные врезки в `main.lifespan` и `GET /queue` + флаги config. + Существующий код не переписывается. +- **Kill-switch** `disk_monitor_enabled` (дефолт `True`): `False` → демон не стартует, `/queue`-блок + отдаёт `{"enabled": false}` — поведение приложения 1:1 как сейчас (NFR-4). +- **never-raise:** изоляция фонового потока (паттерн `reconciler`/`reaper`); сбой замера/отправки/ + тика не влияет на конвейер (BR-6/NFR-1). Демон бежит в общем self-hosting-инстансе — обязан быть + безопасным для enduro-trails. +- **Обратимость:** удаление эффекта = выключение флага; миграций БД нет, откат тривиален. +- **Self-hosting:** watchdog только читает заполнение и шлёт уведомление — не трогает диск/контейнер, + не рестартит прод (NFR-6). + +--- + +## 8. Конфигурация (`src/config.py`) + +По образцу `reconcile_*` / `merge_gate_*`: + +| Поле (env) | Тип / дефолт | Назначение | +|------------|--------------|------------| +| `disk_monitor_enabled` (`ORCH_DISK_MONITOR_ENABLED`) | `bool = True` | kill-switch; `False` → демон не стартует (нулевая регрессия). | +| `disk_monitor_interval_s` (`ORCH_DISK_MONITOR_INTERVAL_S`) | `int = 300` | период heartbeat-замера, сек (порядок минут, NFR-2). | +| `disk_monitor_threshold_pct` (`ORCH_DISK_MONITOR_THRESHOLD_PCT`) | `int = 85` | порог заполнения для алерта (дефолт фиксирован Владельцем). | +| `disk_monitor_realert_s` (`ORCH_DISK_MONITOR_REALERT_S`) | `int = 21600` | минимальный интервал между повторными алертами, пока выше порога (анти-спам; ~6 ч). | +| `disk_monitor_paths` (`ORCH_DISK_MONITOR_PATHS`) | `str = "/repos,/app/data"` (CSV) | отслеживаемые пути (смонтированные хост-разделы, NFR-3); пусто → дефолтный набор. | + +Финальный набор/имена флагов и дефолты уточняет архитектор; диапазон/валидация значений (порог в +1..100, интервалы > 0) — defensive, невалидное → дефолт + лог-warning (паттерн `reconcile_grace_*`). + +--- + +## 9. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR) + +Документация — golden source (CLAUDE.md §2). По итогам разработки обновить: +- `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md` — решение (способ замера хост-ФС, + набор путей/дедуп, хранение состояния анти-спама, точки врезки, дефолты порога/периода). +- `docs/architecture/README.md` — новый компонент «Disk-watchdog (ORCH-063)» в списке компонентов + + описание блока `disk_monitor` в `GET /queue`. +- `docs/operations/INFRA.md` — раздел/строки про disk-watchdog: что мониторится, порог, как + отключить (`ORCH_DISK_MONITOR_ENABLED`), что делать при алерте (ручная очистка — ссылка/руководство). +- `.env.example` — новые `ORCH_DISK_*` дескрипторы. +- `CHANGELOG.md` — запись `feat:`. +- При новом endpoint `/disk` (если архитектор введёт) — обновить таблицу API в README. + +--- + +## 10. Инварианты (не нарушать) +- `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, схема существующих таблиц БД — **без изменений**. +- never-raise на тик демона; сбой watchdog не блокирует и не роняет конвейер (NFR-1). +- Замер — по **хост-разделам** (bind-mount-пути), не по overlay `/` контейнера (NFR-3). +- Не рестартить/не ронять прод-контейнер; watchdog только читает и уведомляет (NFR-6, self-hosting). +- При выключенном флаге — поведение 1:1 как сейчас; enduro-trails не затрагивается. + +--- + +## 11. Открытые вопросы для архитектора (не блокируют анализ) +- OQ-1: Способ замера — stdlib `shutil.disk_usage(path)` vs субпроцесс `df` (рекомендация — stdlib, + NFR-2). +- OQ-2: Дедуп путей по физическому устройству (`os.stat().st_dev`), чтобы единый host-раздел не + алертил дважды. +- OQ-3: Состояние анти-спама — in-memory (рекомендация) vs durable (доп. таблица); влияет на + поведение после рестарта. +- OQ-4: Нужен ли второй «критический» порог (напр. 95%) с усиленным/более частым алертом — кандидат, + по умолчанию **нет** (один порог 85%). +- OQ-5: Helper в `notifications.py` (`notify_disk_alert`) vs прямой вызов `send_telegram` из watchdog. diff --git a/docs/work-items/ORCH-063/03-acceptance-criteria.md b/docs/work-items/ORCH-063/03-acceptance-criteria.md new file mode 100644 index 0000000..924dcff --- /dev/null +++ b/docs/work-items/ORCH-063/03-acceptance-criteria.md @@ -0,0 +1,132 @@ +--- +work_item: ORCH-063 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-063 — INFRA: мониторинг диска mva154 + алерт при >85% + +Work Item: **ORCH-063** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что +считается провалом). Reviewer/tester проверяет их буквально по файлам репозитория и тестам. + +--- + +## AC-1 — Heartbeat-демон запускается с приложением + +**Условие:** фоновый disk-watchdog периодически измеряет заполнение диска и стартует вместе с +приложением без ручного запуска. +- **PASS:** есть daemon-поток (паттерн `reconciler`/`job_reaper`: `threading.Thread(daemon=True)` + + `threading.Event`), стартующий в `main.lifespan` (после `reaper.start()`) и останавливающийся на + shutdown; период замера = `disk_monitor_interval_s`; есть метод `status()`. +- **FAIL:** watchdog не стартует автоматически; блокирующий `time.sleep` без чистого stop; замер + выполняется в обработчике вебхука/в горячем пути конвейера, а не в отдельном демоне. + +--- + +## AC-2 — Алерт при заполнении ≥ порога + +**Условие:** при заполнении отслеживаемого пути ≥ `disk_monitor_threshold_pct` (дефолт 85%) оператор +получает Telegram-алерт с действенными деталями. +- **PASS:** при `used_pct ≥ threshold` вызывается `send_telegram` (notifying, не silent) с + сообщением, содержащим путь/точку монтирования, занято %, свободно (ГБ или %) и порог. +- **FAIL:** алерт не отправляется при превышении; отправляется silent (`disable_notification=True`) + и не пингует; сообщение без действенных деталей (нет %/пути/свободно). + +--- + +## AC-3 — Анти-спам: не на каждом тике + +**Условие:** при длительном превышении порога алерт не дублируется на каждом тике. +- **PASS:** алерт отправляется при пересечении порога (переход «ниже→на/выше»); пока заполнение + остаётся выше порога, повторный алерт шлётся не чаще `disk_monitor_realert_s`. Решение об отправке + выражено чистой функцией от `(current_pct, threshold, previous_state, now)` и покрыто юнит-тестом. +- **FAIL:** алерт шлётся на каждом тике при стабильном превышении; нет cooldown/состояния; логика + отправки не тестируема (зашита в поток с реальным таймером). + +--- + +## AC-4 — Recovery при возврате ниже порога + +**Условие:** при возврате заполнения ниже порога состояние сбрасывается и приходит однократное +сообщение восстановления. +- **PASS:** переход «выше→ниже порога» сбрасывает состояние алерта и отправляет ровно одно + recovery-сообщение «диск ниже порога»; последующее новое превышение снова алертит (цикл повторяем). +- **FAIL:** после спада ниже порога состояние не сбрасывается (новое превышение молчит из-за + «залипшего» cooldown); recovery шлётся повторно на каждом тике ниже порога. + +--- + +## AC-5 — Конфигурируемость и kill-switch + +**Условие:** порог, период, период повтора, пути и включение конфигурируемы; выключение даёт нулевую +регрессию. +- **PASS:** в `config.py` есть `disk_monitor_enabled` / `disk_monitor_interval_s` / + `disk_monitor_threshold_pct` / `disk_monitor_realert_s` / `disk_monitor_paths` (с env-маппингом); + при `disk_monitor_enabled=False` демон не стартует, `/queue`-блок отдаёт `{"enabled": false}`, + поведение приложения идентично текущему. Новые env задокументированы в `.env.example`. +- **FAIL:** значения захардкожены; нет kill-switch; при выключении меняется поведение конвейера; + env не задокументированы. + +--- + +## AC-6 — never-raise (изоляция от конвейера) + +**Условие:** любой сбой watchdog не роняет и не блокирует конвейер. +- **PASS:** замер по несуществующему/недоступному пути, ошибка `send_telegram`, исключение в тике — + логируются и **не** пробрасываются; демон продолжает работу; конвейер и enduro-trails не + затронуты. Покрыто тестом (замер по битому пути / исключение в отправке → тик не падает). +- **FAIL:** исключение в тике останавливает поток или всплывает в приложение; недоступный путь + роняет замер всех путей. + +--- + +## AC-7 — Наблюдаемость в `GET /queue` + +**Условие:** состояние watchdog видно в `GET /queue`. +- **PASS:** ответ `GET /queue` содержит аддитивный блок `disk_monitor` с `enabled`, `threshold_pct`, + `interval_s`, `paths` (последний замер: `used_pct`, свободно), `alerting`, `last_alert_at`; + существующие ключи ответа не изменены; блок never-raise (при ошибке — минимальный словарь). +- **FAIL:** блока нет; изменены/сломаны существующие ключи `/queue`; блок может выбросить исключение. + +--- + +## AC-8 — Корректный источник замера (хост-ФС) + +**Условие:** замер отражает заполнение хост-раздела, а не overlay-ФС контейнера. +- **PASS:** дефолтный набор путей — смонтированные хост-пути (`/repos`, `/app/data`); замер по ним + репрезентативен для заполняющегося хост-раздела. Источником истины **не** является `shutil.disk_usage("/")` + (overlay контейнера). +- **FAIL:** мониторится только `/` контейнера → ложно-низкое заполнение при реально полном хосте + (риск повтора инцидента 07.06). + +--- + +## AC-9 — Документация обновлена (golden source) + +**Условие:** документация обновлена в том же PR (CLAUDE.md §2; reviewer-ось). +- **PASS:** обновлены `docs/architecture/README.md` (компонент + блок `/queue`), + `docs/operations/INFRA.md` (что мониторится, порог, как отключить, реакция на алерт), + `.env.example` (новые `ORCH_DISK_*`), `CHANGELOG.md` (`feat:`); создан + `docs/work-items/ORCH-063/06-adr/ADR-001-*.md`. +- **FAIL:** функционал добавлен, но обзорные/операционные доки или ADR не обновлены. + +--- + +## Сводная матрица AC ↔ FR/BR + +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / BR-8 / FR-1 | +| AC-2 | BR-2 / FR-2 / FR-3 | +| AC-3 | BR-3 / FR-4 | +| AC-4 | BR-4 / FR-4 | +| AC-5 | BR-5 / FR-5 / NFR-4 | +| AC-6 | BR-6 / NFR-1 | +| AC-7 | BR-7 / FR-6 | +| AC-8 | NFR-3 / FR-2 | +| AC-9 | CLAUDE.md §2 (документация = golden source) | diff --git a/docs/work-items/ORCH-063/04-test-plan.yaml b/docs/work-items/ORCH-063/04-test-plan.yaml new file mode 100644 index 0000000..ca6e042 --- /dev/null +++ b/docs/work-items/ORCH-063/04-test-plan.yaml @@ -0,0 +1,92 @@ +work_item: ORCH-063 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +title: "Disk-watchdog mva154: heartbeat-замер + Telegram-алерт при >85%" +framework: pytest +scope: > + Покрывается: чистая логика решения об алерте (порог/анти-спам/recovery), замер заполнения + по путям с дедупом/never-raise, формат алерт-сообщения, daemon start/stop/status, + блок disk_monitor в GET /queue, нулевая регрессия при выключенном kill-switch. + Вне покрытия: реальная отправка в Telegram (мокается), реальное заполнение диска mva154, + внешние системы мониторинга, авто-очистка диска (вне объёма ORCH-063). +notes: > + Время и Telegram-транспорт инъецируются/мокаются: now-провайдер для cooldown, + monkeypatch send_telegram для перехвата вызовов. shutil.disk_usage мокается для задания + used_pct без реального диска. Полный регресс tests/ должен оставаться зелёным. + Имена модулей/функций финализирует архитектор (ADR-001) — module в TC ориентировочны. + +tests: + - id: TC-01 + type: unit + description: "Решение алертить: used_pct >= threshold и состояние было 'ниже' -> should_alert=True (пересечение порога)." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-02 + type: unit + description: "Анти-спам: used_pct >= threshold, состояние уже 'выше', с последнего алерта прошло < realert_s -> should_alert=False (не на каждом тике)." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-03 + type: unit + description: "Повтор по cooldown: 'выше' порога, прошло >= realert_s с последнего алерта -> should_alert=True (повторный алерт)." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-04 + type: unit + description: "Recovery: переход used_pct < threshold из состояния 'выше' -> сброс состояния + ровно одно recovery-сообщение; ниже порога устойчиво -> recovery не повторяется." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-05 + type: unit + description: "Граница порога: used_pct ровно == threshold трактуется как превышение (>= порога алертит); used_pct == threshold-1 -> молчит." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-06 + type: unit + description: "Замер по путям: для каждого пути считается used_pct/free через (мок) shutil.disk_usage; совпадающие по устройству пути дедуплицируются (одно срабатывание)." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-07 + type: unit + description: "never-raise: недоступный/несуществующий путь и исключение в send_telegram логируются и не пробрасываются; тик завершается, демон жив." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-08 + type: unit + description: "Формат алерта: сообщение содержит путь/точку монтирования, used_pct, свободно (ГБ или %) и порог; отправляется notifying (disable_notification не True)." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-09 + type: unit + description: "Kill-switch: при disk_monitor_enabled=False демон не стартует в lifespan (или start() — no-op); замеры/алерты не выполняются." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-10 + type: unit + description: "status(): возвращает dict с enabled/threshold_pct/interval_s/paths(последний замер)/alerting/last_alert_at; never-raise при отсутствии замеров." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-11 + type: integration + description: "GET /queue содержит аддитивный блок disk_monitor с ожидаемыми ключами; существующие ключи ответа (counts/reconcile/reaper/serial_gate/...) не изменены." + module: tests/test_disk_watchdog.py + expected: PASS + + - id: TC-12 + type: integration + description: "Тик демона при замоканном высоком заполнении (>=85%) вызывает send_telegram один раз; при выключенном флаге GET /queue отдаёт disk_monitor.enabled=false и алертов нет (нулевая регрессия)." + module: tests/test_disk_watchdog.py + expected: PASS diff --git a/docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md b/docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md new file mode 100644 index 0000000..2531eec --- /dev/null +++ b/docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md @@ -0,0 +1,196 @@ +--- +work_item: ORCH-063 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# ADR-001: Disk-watchdog — heartbeat-демон мониторинга заполнения хост-ФС + Telegram-алерт при ≥85% + +Work Item: **ORCH-063** — INFRA: мониторинг диска mva154 + алерт при >85% +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0024-disk-watchdog.md`** (новый фоновый +компонент-демон в ряду `reconciler`/`job_reaper` — кросс-каттинговое решение). + +## Статус +Proposed + +## Контекст +07.06.2026 диск хоста **mva154** (`slin@82.22.50.71`) тихо дорос до 100% и положил **весь +конвейер всех проектов** (CI красный, очередь Gitea застряла). Корневая боль: у оркестратора +**нет проактивного сигнала** о заполнении диска — оператор узнаёт о проблеме постфактум, когда +self-hosting-инстанс `orchestrator` (8500, один на все прод-проекты, общая БД/очередь) уже встал +(BRD §1). + +Факты, сверенные с кодом: +- В оркестраторе уже есть **каркас фонового daemon-потока**, повторённый дважды: + `src/reconciler.py::Reconciler` (ORCH-053) и `src/job_reaper.py` (ORCH-065) — оба + `threading.Thread(daemon=True)` + `threading.Event`, чистый stop через `self._stop.wait(interval)`, + контракт `start()`/`stop(timeout)`/`status()`, **never-raise** на тик, наблюдаемость через + `GET /queue`. Старт/стоп — в `src/main.py::lifespan` (старт после `reaper.start()`, стоп в + reverse-порядке), снимок — в `@app.get("/queue")` (`"reaper": reaper.status()` и др.). +- Контейнер бежит `network_mode: host` с bind-mount'ами host-разделов: `/home/slin/repos → /repos`, + `./data → /app/data` (`docs/operations/INFRA.md` §«Тома»). Именно эта ФС переполнилась 07.06. + Замер по overlay `/` контейнера нерепрезентативен (BRD §6, NFR-3). +- Алерты шлются через `src/notifications.py::send_telegram` (notifying по умолчанию; silent — + только при явном `disable_notification`). +- Образец «чистая leaf-логика + тонкая обёртка» уже принят: `src/task_deps.py`, `src/serial_gate.py`, + `src/staging_verdict.py` — pure-функции (never-raise) + точечные врезки. + +«Как есть» не годится: единственный сигнал о диске — падение всего конвейера. Нужен дешёвый ранний +heartbeat-watchdog. ТЗ (02-trz) фиксирует требования; данный ADR фиксирует **как** (§OQ-1..OQ-5). + +## Решение + +### Сводка +Вводим **disk-watchdog** — новый фоновый daemon-поток `src/disk_watchdog.py`, точная калька +архитектуры `reconciler`/`job_reaper`. Демон каждые `disk_monitor_interval_s` (дефолт 300с) меряет +заполнение **смонтированных хост-путей** через stdlib `shutil.disk_usage(path)`, дедуплицирует пути +по физическому устройству (`os.stat(path).st_dev`), и через **чистую функцию решения** от +`(used_pct, threshold, prev_state, now)` решает: послать алерт (пересечение порога вверх), повторить +(cooldown `disk_monitor_realert_s`), послать recovery (возврат вниз) или молчать. Состояние +анти-спама — **in-memory** (без миграции БД). Наблюдаемость — аддитивный блок `disk_monitor` в +`GET /queue`. Kill-switch `disk_monitor_enabled`. **never-raise** на каждом уровне. +`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — **не трогаются**. + +### D1 — Способ замера: stdlib `shutil.disk_usage` (OQ-1, FR-2/NFR-2) +Замер каждого пути — `shutil.disk_usage(path)` (`total`/`used`/`free` в байтах), `used_pct = +round(used / total * 100, 1)`. Чистый системный вызов `statvfs`, без порождения субпроцесса `df` на +каждом тике (NFR-2: heartbeat порядка минут, дёшево). `df` отвергнут (см. Альтернативы). +- **Почему репрезентативно для хост-ФС (NFR-3, AC-8):** `shutil.disk_usage(path)` возвращает + статистику ФС, которой принадлежит `path`. На bind-mount'е `/repos`/`/app/data` это **хост-раздел** + (тот, что переполнился 07.06), а не overlay контейнера. Дефолтный набор путей — + `/repos,/app/data`; `shutil.disk_usage("/")` **не** используется как источник истины. +- Недоступный/несуществующий путь (`FileNotFoundError`/`PermissionError`/`OSError`) → пропуск + **этого** пути с `logger.warning`, остальные пути меряются дальше (FR-2, AC-6: один битый путь не + роняет весь тик). + +### D2 — Дедуп путей по физическому устройству (OQ-2, FR-2) +Перед замером пути резолвим `os.stat(path).st_dev` и схлопываем пути с одинаковым `st_dev` в один +логический раздел (ключ дедупа — `st_dev`; для отображения берём первый успешно резолвнутый путь). +На mva154 `/repos` и `/app/data` с высокой вероятностью лежат на одном host-разделе (BRD §6) → один +алерт, а не два дубля. Дедуп — **желательное** требование (BRD §6), реализуемое, never-raise: ошибка +`os.stat` → путь обрабатывается как отдельный (fail-open, без потери замера). + +### D3 — Чистая функция решения + модель состояния (OQ-3, FR-4, AC-3/AC-4) +Решение об отправке вынесено в **pure-функцию** (юнит-тестируема без потока и реального таймера, +AC-3): + +``` +decide_action(used_pct, threshold, prev: PathAlertState, now, realert_s) -> Action +# Action ∈ {NONE, ALERT, REALERT, RECOVERY} +``` + +- `prev.alerting == False` и `used_pct >= threshold` → **ALERT** (пересечение «ниже→на/выше»); +- `prev.alerting == True` и `used_pct >= threshold` и `now - prev.last_alert_at >= realert_s` → + **REALERT** (cooldown истёк); иначе при `alerting && >=threshold` → **NONE** (анти-спам: не на + каждом тике, BR-3/AC-3); +- `prev.alerting == True` и `used_pct < threshold` → **RECOVERY** (переход «выше→ниже», ровно одно + сообщение, сброс `alerting`, BR-4/AC-4); +- `prev.alerting == False` и `used_pct < threshold` → **NONE** (норма). + +**Модель состояния (in-memory, per device/path):** `PathAlertState{alerting: bool, last_alert_at: +float|None}`, словарь `{dedup_key -> PathAlertState}` в демоне. Durable-хранение **отвергнуто** +(OQ-3): TRZ §5/NFR-5 допускает in-memory, состояние best-effort. После рестарта `alerting` +сбрасывается → при всё ещё полном диске придёт повторный алерт — это **безопасно** (ранний сигнал, +не SLA). **Время инъецируется** `now`-провайдером (дефолт — обёртка над часами; в тестах — фейк), +чтобы cooldown/recovery тестировались детерминированно (AC-3). + +### D4 — Отправка алерта: формат в leaf + `send_telegram` напрямую (OQ-5, FR-3) +Форматирование текста — pure-функция в `disk_watchdog.py` (`format_alert_message` / +`format_recovery_message`, тестируема). Отправка — **прямой** `send_telegram(text)` +(**notifying**, не silent — это алерт, как `notify_error`); отдельный helper в `notifications.py` +**не** вводим (минимизация поверхности; OQ-5 оставляет выбор за архитектором). Вызов `send_telegram` +обёрнут `try/except` → ошибка доставки логируется и не роняет тик (BR-6/AC-6; доставка best-effort, +BRD §6). +- **Содержимое (действенное, FR-3/AC-2):** точка монтирования/путь, занято %, свободно (ГБ и %), + порог; текст на русском в стиле существующих `notify_*`. Пример: + `🔴 Диск mva154: /repos заполнен на 87.3% (порог 85%). Свободно 6.2 ГБ (12.7%). Освободите + место — риск остановки конвейера всех проектов.` + Recovery: `🟢 Диск mva154: /repos вернулся ниже порога — 78.1% (свободно 11.0 ГБ).` + +### D5 — Один порог 85% (OQ-4, BR-2) +Один настраиваемый порог `disk_monitor_threshold_pct` (дефолт 85, зафиксирован Владельцем). +Второй «критический» порог (напр. 95%) с усиленным алертом — **вне объёма** (OQ-4, BRD §8 R-3), +кандидат на follow-up. Конфигурируемость порога (BR-5) оставляет рычаг тюнинга. + +### D6 — Lifecycle и точки врезки (FR-1/FR-5/FR-6, AC-1/AC-5/AC-7) +- **`src/disk_watchdog.py`** (новый leaf) — pure-логика (`measure_paths`, `decide_action`, + `format_*`) + класс `DiskWatchdog(threading.Thread(daemon=True) + threading.Event)` с + `start()`/`stop(timeout=5.0)`/`status()`; цикл `while not self._stop.is_set(): try: tick(); + except: log; self._stop.wait(interval)`. Модуль-синглтон `disk_watchdog = DiskWatchdog()`. +- **`src/config.py`** — флаги §«Конфигурация» (D7); defensive-валидация значений (порог 1..100, + интервалы > 0) → невалидное к дефолту + warning (паттерн `reconcile_grace_*`). +- **`src/main.py::lifespan`** — `disk_watchdog.start()` **последним** (после `reaper.start()`, + гард `if settings.disk_monitor_enabled`), `disk_watchdog.stop()` **первым** в `finally` + (reverse-порядок). Демон независим (не трогает очередь/БД) → порядок не критичен, но + следуем конвенции. +- **`@app.get("/queue")`** — аддитивный ключ `"disk_monitor": disk_watchdog.status()`; существующие + ключи не меняются; `status()` never-raise (при ошибке — `{"enabled": ...}` минимум, FR-6/AC-7). + Снимок: `enabled`, `threshold_pct`, `interval_s`, `realert_s`, `paths` (по каждому + устройству/пути: `path`, `used_pct`, `free_gb`, `alerting`, `last_alert_at`). +- **`.env.example`** — дескрипторы `ORCH_DISK_*` (AC-5). + +### D7 — Конфигурация (`src/config.py`, FR-5/AC-5) +| Поле (env) | Тип / дефолт | Назначение | +|------------|--------------|------------| +| `disk_monitor_enabled` (`ORCH_DISK_MONITOR_ENABLED`) | `bool = True` | kill-switch; `False` → демон не стартует (нулевая регрессия, NFR-4). | +| `disk_monitor_interval_s` (`ORCH_DISK_MONITOR_INTERVAL_S`) | `int = 300` | период heartbeat (порядок минут, NFR-2). | +| `disk_monitor_threshold_pct` (`ORCH_DISK_MONITOR_THRESHOLD_PCT`) | `int = 85` | порог алерта (дефолт Владельца). | +| `disk_monitor_realert_s` (`ORCH_DISK_MONITOR_REALERT_S`) | `int = 21600` | cooldown повторного алерта выше порога (~6 ч, анти-спам). | +| `disk_monitor_paths` (`ORCH_DISK_MONITOR_PATHS`) | `str = "/repos,/app/data"` (CSV) | отслеживаемые host-пути (NFR-3); пусто → дефолтный набор. | + +### D8 — Инварианты (NFR-5/NFR-6, AC-6) +- `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, схема существующих таблиц БД — **без изменений** + (watchdog — эксплуатационный демон, не QG; как `reconciler`/`reaper`). Новой миграции нет (D3). +- **never-raise** на трёх уровнях: per-path (D1), per-tick (внешний `try/except` в `_run`), + per-send (D4). Сбой watchdog не блокирует и не роняет конвейер (BR-6/NFR-1). +- **Self-hosting безопасность (NFR-6):** watchdog только **читает** заполнение и **шлёт** Telegram — + не трогает диск/контейнер, не рестартит прод. Безопасен для enduro-trails в общем инстансе. + +## Альтернативы +- **Субпроцесс `df -P` на каждом тике** — отвергнут: лишнее порождение процесса при heartbeat + порядка минут (NFR-2), парсинг вывода, зависимость от формата `df`. `shutil.disk_usage` — stdlib, + без субпроцесса, кроссплатформенно. +- **Замер по `/` (overlay контейнера)** — отвергнут: нерепрезентативен для хост-раздела (NFR-3/AC-8), + прямой путь к повтору инцидента 07.06 (ложно-низкое заполнение). +- **Durable-состояние анти-спама (доп. таблица)** — отвергнуто: TRZ §5/NFR-5 допускает in-memory; + повторный алерт после рестарта при полном диске безопасен; миграция = лишняя поверхность и + усложнение отката. +- **Внешний мониторинг (Prometheus/Grafana/node_exporter)** — вне объёма (BRD §2.2): тяжёлая + инфра-зависимость против принципа «минимум зависимостей, всё в Docker на одном сервере». Дешёвый + встроенный heartbeat закрывает боль. +- **Новый endpoint `GET /disk`** — не вводим (TRZ §4 рекомендация): снимок отдаётся блоком в + `/queue`, меньше API-поверхности. + +## Последствия +- **+** Ранний сигнал о заполнении диска до остановки конвейера всех проектов; дешёвая страховка от + дорогого группового self-hosting-простоя. +- **+** Полная архитектурная калька проверенных `reconciler`/`reaper` → низкий риск, знакомый паттерн + для ревью/сопровождения. +- **+** Чистая pure-логика (`decide_action`, `format_*`, `measure_paths`) юнит-тестируема без потока + и таймера (AC-3/AC-6). +- **−** In-memory состояние → повторный алерт после рестарта при всё ещё полном диске. Митигейшн: + это безопасно (ранний сигнал, не SLA; NFR-5) и редко (рестарт прода — событие). +- **−** Best-effort доставка Telegram (та же `send_telegram`): алерт может не дойти при сбое сети. + Митигейшн: watchdog — ранний сигнал, не гарантия; cooldown-повтор повышает шанс доставки. +- **−** Дедуп по `st_dev` не покрывает редкий случай разных устройств для `/repos` и `/app/data` + (тогда — два независимых алерта, что корректно). Без ущерба. +- **Откат:** `ORCH_DISK_MONITOR_ENABLED=false` (демон не стартует, блок `/queue` → `{"enabled": + false}`, поведение 1:1 как сейчас). Полное удаление — снять врезки в `main.py`/`config.py` + + удалить leaf; миграций БД нет → откат тривиален (TRZ §7). + +## Ссылки +- BRD: `docs/work-items/ORCH-063/01-brd.md` +- TRZ: `docs/work-items/ORCH-063/02-trz.md` +- Acceptance: `docs/work-items/ORCH-063/03-acceptance-criteria.md` +- Инфра: `docs/work-items/ORCH-063/07-infra-requirements.md` +- Риски: `docs/work-items/ORCH-063/10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0024-disk-watchdog.md` +- Сверено по коду: `src/reconciler.py` (каркас демона), `src/job_reaper.py` (lifecycle/status), + `src/main.py` (lifespan §94-118, `/queue` §142-173), `src/notifications.py::send_telegram`, + `docs/operations/INFRA.md` (bind-mount'ы `/repos`, `/app/data`). + + diff --git a/docs/work-items/ORCH-063/07-infra-requirements.md b/docs/work-items/ORCH-063/07-infra-requirements.md new file mode 100644 index 0000000..c89f221 --- /dev/null +++ b/docs/work-items/ORCH-063/07-infra-requirements.md @@ -0,0 +1,63 @@ +--- +work_item: ORCH-063 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 07 — Инфра-требования: ORCH-063 — мониторинг диска mva154 + алерт при ≥85% + +Work Item: **ORCH-063** · Repo: **orchestrator** (self-hosting) · Стадия: architecture + +## I-1. Топология / окружения +Топология **не меняется**. Watchdog работает внутри существующего контейнера `orchestrator` +(8500, `network_mode: host`) и опирается на уже существующие bind-mount'ы host-разделов: +- `/home/slin/repos → /repos` (рабочие репозитории, git-worktree `/repos/_wt/...`); +- `./data → /app/data` (SQLite БД). + +Именно эта host-ФС переполнилась 07.06. Замер ведётся по смонтированным путям `/repos`, `/app/data` +(`shutil.disk_usage`), что отражает **хост-раздел**, а не overlay `/` контейнера (NFR-3/AC-8). Новых +контейнеров/портов/томов/сетей не требуется. Тот же демон автоматически работает и в staging-инстансе +(8501) — на собственной Ф С/путях, без отдельной настройки. + +## I-2. Переменные окружения / секреты +Новые env (дескрипторы — в `.env.example`; **без секретов**): + +| Env | Дефолт | Назначение | +|-----|--------|------------| +| `ORCH_DISK_MONITOR_ENABLED` | `true` | kill-switch (false → демон не стартует, нулевая регрессия). | +| `ORCH_DISK_MONITOR_INTERVAL_S` | `300` | период heartbeat-замера, сек. | +| `ORCH_DISK_MONITOR_THRESHOLD_PCT` | `85` | порог заполнения для алерта. | +| `ORCH_DISK_MONITOR_REALERT_S` | `21600` | cooldown повторного алерта выше порога (~6 ч). | +| `ORCH_DISK_MONITOR_PATHS` | `/repos,/app/data` | CSV отслеживаемых host-путей. | + +Telegram-доставка использует **существующие** секреты `send_telegram` (`ORCH_TELEGRAM_*` / +`.env`) — новых секретов не вводится. Дефолты пригодны для прода без обязательной правки `.env` +(env опциональны — все имеют значения по умолчанию в `config.py`). + +## I-3. Деплой / рестарт +- Изменение **не требует** специальной инфра-процедуры сверх штатного self-hosting-деплоя + (staging 8501 → прод 8500 через `Confirm Deploy`, ORCH-059/036). +- **Self-hosting инвариант соблюдён:** watchdog только читает заполнение и шлёт уведомление — не + рестартит/не роняет прод-контейнер, не выполняет действий над диском (NFR-6). Безопасен для + enduro-trails в общем инстансе. +- Демон стартует/останавливается автоматически в `main.lifespan` (ручной запуск не нужен, AC-1/AC-8). + +### Реакция оператора на алерт (runbook-минимум) +При получении Telegram-алерта «Диск mva154 ≥ порога»: +1. Зайти на хост (`slin@82.22.50.71`), проверить `df -h /home/slin/repos`. +2. Освободить место (кандидаты — порядок ручной очистки): прунинг старых git-worktree + `/home/slin/repos/_wt/*` завершённых задач; `docker image prune` / `docker builder prune`; + ротация/удаление старых логов. **Авто-очистка — вне объёма ORCH-063** (отдельная задача). +3. Дождаться recovery-сообщения «диск ниже порога» (приходит однократно при возврате под порог). + +> Развёрнутый раздел про disk-watchdog (что мониторится, порог, как отключить +> `ORCH_DISK_MONITOR_ENABLED`, реакция на алерт) добавляется в `docs/operations/INFRA.md` на стадии +> development (TRZ §9, AC-9). + +## I-4. CI/CD +Без изменений `.gitea/workflows/`. Новый код покрывается существующим `pytest tests/` (юнит-тесты +pure-логики `decide_action`/`measure_paths`/`format_*` + изоляция never-raise — TRZ/AC-3/AC-6). + diff --git a/docs/work-items/ORCH-063/10-tech-risks.md b/docs/work-items/ORCH-063/10-tech-risks.md new file mode 100644 index 0000000..9b87335 --- /dev/null +++ b/docs/work-items/ORCH-063/10-tech-risks.md @@ -0,0 +1,39 @@ +--- +work_item: ORCH-063 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-063 — мониторинг диска mva154 + алерт при ≥85% + +Work Item: **ORCH-063** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Риски реализации и их митигейшн. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Замер по неверной ФС** (overlay `/` контейнера вместо host-раздела) → ложно-низкое заполнение → watchdog молчит при реально полном хосте (повтор 07.06). | Сред. | Выс. | ADR D1: замер `shutil.disk_usage` по bind-mount-путям `/repos`/`/app/data` (host-разделы); `/` запрещён как источник (NFR-3/AC-8). Тест AC-8. | +| TR-2 | **Спам-алерты на каждом тике** при длительном превышении → шум, оператор глохнет. | Сред. | Сред. | ADR D3: pure `decide_action` — алерт на пересечении + cooldown `disk_monitor_realert_s` (~6 ч); юнит-тест AC-3. | +| TR-3 | **Залипший cooldown** — после спада ниже порога состояние не сброшено → новое превышение молчит. | Низ. | Сред. | ADR D3: переход «выше→ниже» сбрасывает `alerting` + однократный recovery; цикл повторяем. Тест AC-4. | +| TR-4 | **Исключение в тике/отправке роняет поток или конвейер.** | Низ. | Выс. | ADR D8: never-raise на 3 уровнях (per-path, per-tick, per-send), как `reconciler`/`reaper`. Тест AC-6 (битый путь / падение `send_telegram`). | +| TR-5 | **Порог 85% близок к 100% при быстром росте** (один большой build/worktree) → оператор не успевает. | Низ. | Сред. | Дефолт зафиксирован Владельцем; конфигурируем (BR-5). Второй «критический» порог (95%) — кандидат follow-up (OQ-4, вне объёма). | +| TR-6 | **Исчерпание inode** (не байтов) валит ФС, но не ловится замером по %-байтам. | Низ. | Сред. | Вне объёма ORCH-063 (BRD §8 R-4); кандидат на расширение замера (`os.statvfs` f_files/f_favail). Задокументировать как known-limitation. | +| TR-7 | **Потеря анти-спам-состояния при рестарте** (in-memory) → повторный алерт при всё ещё полном диске. | Сред. | Низ. | Осознанный компромисс (ADR D3, NFR-5): повторный ранний сигнал безопасен; durable-хранение отвергнуто (лишняя миграция). | +| TR-8 | **Best-effort Telegram** — алерт не доставлен при сбое сети. | Низ. | Сред. | Та же `send_telegram` (never-raise); cooldown-повтор повышает шанс доставки. Watchdog — ранний сигнал, не SLA (BRD §6). | +| TR-9 | **Дедуп по `st_dev` ошибочно схлопнет разные разделы** или `os.stat` упадёт. | Низ. | Низ. | ADR D2: ключ дедупа — фактический `st_dev`; ошибка `os.stat` → fail-open (путь как отдельный, замер не теряется). | + +## Сводный вывод +Доминирующий класс — **риски ложного молчания/шума** (TR-1, TR-2, TR-3), полностью закрытые +конструктивно: корректный источник замера (host-ФС) + pure-функция анти-спама с юнит-покрытием. +Изоляция от конвейера обеспечена never-raise-каркасом проверенных `reconciler`/`reaper`. Эскалация +`arch:major-change` **не требуется**: изменение аддитивное, под kill-switch, без правки +`STAGE_TRANSITIONS`/`QG_CHECKS`/схемы БД, тривиально откатывается. Возврат в анализ **не требуется** — +ТЗ реализуемо без нарушения принципов. Остаточный риск для прод-конвейера (self-hosting) — **низкий**: +watchdog только читает и уведомляет, не трогает прод. TR-6 (inode) — осознанная known-limitation вне +объёма. + diff --git a/docs/work-items/ORCH-063/12-review.md b/docs/work-items/ORCH-063/12-review.md new file mode 100644 index 0000000..e98f382 --- /dev/null +++ b/docs/work-items/ORCH-063/12-review.md @@ -0,0 +1,99 @@ +--- +verdict: APPROVED +work_item: ORCH-063 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-09 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-063 +version: 1 +--- + +# Review ORCH-063 — INFRA: disk-watchdog мониторинг диска mva154 + алерт при ≥85% + +> Машинный вердикт читается ТОЛЬКО из `verdict:` во frontmatter. `APPROVED` → дальше по конвейеру. + +## Summary + +PR реализует disk-watchdog — фоновый daemon-поток `src/disk_watchdog.py` по канону +`reconciler`/`job_reaper`, точно по ТЗ `02-trz.md` и ADR-001/`adr-0024`. Все 9 критериев приёмки +(`03-acceptance-criteria.md` AC-1..AC-9) выполнены и покрыты содержательными тестами +(`tests/test_disk_watchdog.py`, TC-01..TC-12, 18 кейсов). Полный регресс зелёный: **1296 passed**. +Инварианты соблюдены: `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — **не тронуты** (проверено +`git diff` — `src/stages.py`/`src/stage_engine.py`/`src/qg/` без изменений), миграций нет. Документация +обновлена как golden source в том же work-item. **Блокеров (P0/P1) нет → APPROVED.** + +## Оси проверки + +### 1. Соответствие ТЗ / Acceptance Criteria +- **AC-1 (heartbeat-демон):** `DiskWatchdog(threading.Thread(daemon=True) + threading.Event)`, + `_stop.wait(interval)` (чистый stop, без блокирующего `time.sleep`), контракт + `start()`/`stop(timeout)`/`status()`. Старт в `main.lifespan` **после** `reaper.start()`, стоп + **первым** в `finally` (reverse) — `src/main.py`. ✓ +- **AC-2 (алерт ≥ порога):** `format_alert_message` несёт host/путь/`used_pct`/свободно (ГБ+%)/порог; + отправка `send_telegram(..., disable_notification=False)` — notifying. Подтверждено TC-08. ✓ +- **AC-3 (анти-спам):** чистая `decide_action(used_pct, threshold, prev, now, realert_s)`, cooldown + `disk_monitor_realert_s`, время инъецируется `now_provider`. TC-02/TC-03 + e2e. ✓ +- **AC-4 (recovery):** переход «выше→ниже» → ровно одно recovery-сообщение + сброс `alerting`; ниже + порога молчит. TC-04 + e2e (`test_tick_antispam_then_realert_then_recovery`). ✓ +- **AC-5 (config + kill-switch):** 5 флагов `disk_monitor_*` (env `ORCH_DISK_MONITOR_*`, `env_prefix=ORCH_`) + + defensive-валидаторы (порог 1..100, интервалы > 0 → дефолт + warning). `enabled=False` → `start()` + no-op (TC-09), `.env.example` обновлён. ✓ +- **AC-6 (never-raise):** три уровня — per-path (`_measure_one`), per-tick (`_run` outer try/except), + per-send (`_send`). TC-07 (битый путь / падение `send_telegram`). ✓ +- **AC-7 (наблюдаемость):** аддитивный блок `disk_monitor` в `GET /queue`; `status()` never-raise + (минимум `{"enabled": …}` при ошибке). TC-11 проверяет сохранность всех существующих ключей. ✓ +- **AC-8 (источник = хост-ФС):** дефолт `/repos,/app/data` через `shutil.disk_usage`, не overlay `/`, + не субпроцесс `df`; дедуп по `st_dev`. TC-06. ✓ +- **AC-9 (документация):** см. секцию «Документация». ✓ + +### 2. Соответствие ADR / инвариантам +- Реализация 1:1 с ADR-001 D1–D8: stdlib-замер (D1), дедуп `st_dev` fail-open (D2), pure + `decide_action` + in-memory state (D3), прямой `send_telegram` без helper (D4), один порог 85% (D5), + lifecycle/врезки (D6), config (D7), инварианты (D8). Сквозной `adr-0024` зарегистрирован в ряду + `reconciler`/`job_reaper`. +- **Трассировка:** врезки в `main.lifespan` и `@app.get("/queue")` — строго **аддитивные** (новый + импорт + один вызов `disk_watchdog.start()/stop()` + ключ `"disk_monitor"`); зафиксированные + инварианты соседних маркеров не сломаны. `STAGE_TRANSITIONS`/`QG_CHECKS` не затронуты — подтверждено. + +### 3. Качество кода +- Docstrings на всех публичных функциях/классе; чистая leaf-логика отделена от потока (тестируемо). +- Defensive-граничные случаи покрыты: `total == 0` → `0.0`, пустой CSV → дефолт, `os.stat` fail → fail-open. +- Тесты содержательные (не тривиальные): юнит-решения, измерение/дедуп, e2e цикл alert→silent→realert→ + recovery, интеграция `/queue`. Полный suite зелёный (1296). + +### 4. Документация (golden source) +- `docs/architecture/README.md` — компонент «Disk-watchdog» + описание блока `/queue`. ✓ +- `docs/operations/INFRA.md` — что мониторится / порог / как отключить / реакция на алерт. ✓ +- `.env.example` — 5 дескрипторов `ORCH_DISK_MONITOR_*`. ✓ +- `CHANGELOG.md` — запись `feat:`. ✓ +- `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md` + сквозной `adr-0024`. ✓ +- `src/` изменён → документация обновлена в том же work-item. Ось пройдена. + +## Findings + +### P0 — Blocker +- (нет) + +### P1 — Must fix +- (нет) + +### P2 — Should fix +- (нет) + +### P3 — Nice-to-have +- [ ] Косметика: хвостовые артефакты тул-обёртки `` / ``, протёкшие в текст + golden-source доков, авторизованных на стадии architecture (НЕ в developer-коммите): + `06-adr/ADR-001-disk-watchdog.md` (строки 195–196), `docs/architecture/adr/adr-0024-disk-watchdog.md` + (стр. 59), `07-infra-requirements.md` (стр. 63), `10-tech-risks.md` (стр. 39). На парсинг + frontmatter/QG не влияют (находятся в конце файла), функциональность не затрагивают — поэтому P3. + Рекомендуется зачистить при следующем касании этих доков (правка чужой стадии — по согласованию, + CLAUDE.md §3). Не блокирует вердикт. + +## Документация +Обновлена полностью в том же work-item: `architecture/README.md` (компонент + блок `/queue`), +`operations/INFRA.md` (мониторинг/порог/отключение/реакция), `.env.example` (новые `ORCH_DISK_*`), +`CHANGELOG.md` (`feat:`), задачный ADR-001 + сквозной `adr-0024`. Обзорная витрина (README «Известные +ограничения») этим PR не затрагивается. Ось документации пройдена — оснований для `REQUEST_CHANGES` нет. diff --git a/docs/work-items/ORCH-063/13-test-report.md b/docs/work-items/ORCH-063/13-test-report.md new file mode 100644 index 0000000..265f041 --- /dev/null +++ b/docs/work-items/ORCH-063/13-test-report.md @@ -0,0 +1,94 @@ +--- +result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE +work_item: ORCH-063 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-09 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-063 +--- + +# Test Report — ORCH-063 — INFRA: disk-watchdog мониторинг диска mva154 + алерт при ≥85% + +> Машинный вердикт читается ТОЛЬКО из `result:` во frontmatter. `PASS` → задача переходит на `deploy-staging`. + +## Окружение +- Python: 3.12.13 +- pytest: 8.3.3 (pytest-asyncio 0.23.8, anyio 4.13.0) +- Worktree: `/repos/_wt/orchestrator/feature_ORCH-063-infra-mva154-85/` (ветка `feature/ORCH-063-infra-mva154-85`) +- Дата: 2026-06-09 + +## Smoke API (read-only) +| Endpoint | Результат | +|----------|-----------| +| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` | +| `GET /status` | PASS — отвечает; ORCH-063 (task 74) виден в `active_tasks` на `stage=testing` | +| `GET /queue` | PASS — блок `serial_gate` присутствует (ORCH-088) рядом с `auto_labels` (ORCH-089); существующие ключи `counts/reconcile/reaper/post_deploy/merge_verify/task_deps` на месте | + +`serial_gate.per_repo.orchestrator.active_task = ORCH-063 (testing)` — регресса смока нет. + +## Результаты по тест-плану (`04-test-plan.yaml`) + +Все TC прогнаны в `tests/test_disk_watchdog.py` (18 кейсов покрывают TC-01..TC-12). Сопоставление с +критериями приёмки `03-acceptance-criteria.md`: + +| TC ID | Тип | Описание | Тест(ы) | AC | Результат | +|-------|-----|----------|---------|----|-----------| +| TC-01 | unit | Алерт при пересечении порога (ниже→на/выше) → should_alert=True | `test_tc01_alert_on_crossing_up` | AC-2/AC-3 | PASS | +| TC-02 | unit | Анти-спам: выше порога, прошло < realert_s → should_alert=False | `test_tc02_antispam_within_cooldown` | AC-3 | PASS | +| TC-03 | unit | Повтор по cooldown: прошло ≥ realert_s → should_alert=True | `test_tc03_realert_after_cooldown` | AC-3 | PASS | +| TC-04 | unit | Recovery: выше→ниже → сброс + ровно одно recovery; ниже устойчиво → не повторяется | `test_tc04_recovery_and_no_repeat`, `test_tick_antispam_then_realert_then_recovery` | AC-4 | PASS | +| TC-05 | unit | Граница порога: `== threshold` алертит; `== threshold-1` молчит | `test_tc05_threshold_boundary_inclusive` | AC-2 | PASS | +| TC-06 | unit | Замер по путям через (мок) `shutil.disk_usage`; дедуп по устройству | `test_tc06_measure_and_dedup_by_device` | AC-8 | PASS | +| TC-07 | unit | never-raise: битый путь и исключение в `send_telegram` не пробрасываются | `test_tc07_broken_path_does_not_kill_tick`, `test_tc07_send_failure_does_not_raise` | AC-6 | PASS | +| TC-08 | unit | Формат алерта: путь/used_pct/свободно/порог; notifying (не silent) | `test_tc08_alert_message_actionable_and_notifying`, `test_tc08_format_helpers` | AC-2 | PASS | +| TC-09 | unit | Kill-switch: `enabled=False` → демон не стартует / `/queue` enabled=false | `test_tc09_killswitch_does_not_start`, `test_tc09_killswitch_status_block` | AC-5 | PASS | +| TC-10 | unit | `status()`: dict с enabled/threshold_pct/interval_s/paths/alerting/last_alert_at; never-raise | `test_tc10_status_shape`, `test_tc10_status_reflects_last_measurement` | AC-7 | PASS | +| TC-11 | integration | `GET /queue` содержит блок `disk_monitor`; существующие ключи не изменены | `test_tc11_queue_has_disk_monitor_block` | AC-7 | PASS | +| TC-12 | integration | Тик при ≥85% → `send_telegram` один раз; при выключенном флаге `disk_monitor.enabled=false`, алертов нет | `test_tc12_queue_disabled_block`, `test_tick_antispam_then_realert_then_recovery` | AC-5/AC-2 | PASS | + +Доп. кейсы (вне номерных TC, усиливают покрытие): `test_parse_paths_default_and_csv` (парс CSV/дефолт путей) — PASS. + +Покрытие: все 12 TC из тест-плана выполнены, каждый сопоставлен с AC; AC-1 (heartbeat-демон, +lifecycle) и AC-9 (документация) — структурно подтверждены review (`12-review.md`, вердикт `APPROVED`) +и не требуют отдельного рантайм-теста. + +## Вывод pytest + +Целевой файл: +``` +tests/test_disk_watchdog.py ... 18 items +test_tc01_alert_on_crossing_up PASSED +test_tc02_antispam_within_cooldown PASSED +test_tc03_realert_after_cooldown PASSED +test_tc04_recovery_and_no_repeat PASSED +test_tc05_threshold_boundary_inclusive PASSED +test_tc06_measure_and_dedup_by_device PASSED +test_tc07_broken_path_does_not_kill_tick PASSED +test_tc07_send_failure_does_not_raise PASSED +test_tc08_alert_message_actionable_and_notifying PASSED +test_tc08_format_helpers PASSED +test_tc09_killswitch_does_not_start PASSED +test_tc09_killswitch_status_block PASSED +test_tc10_status_shape PASSED +test_tc10_status_reflects_last_measurement PASSED +test_tick_antispam_then_realert_then_recovery PASSED +test_parse_paths_default_and_csv PASSED +test_tc11_queue_has_disk_monitor_block PASSED +test_tc12_queue_disabled_block PASSED +======================== 18 passed, 1 warning in 0.40s ========================= +``` + +Полный регресс: +``` +======================= 1296 passed, 1 warning in 31.97s ======================= +``` +(Единственный warning — `PydanticDeprecatedSince20` в `src/config.py:7`, предсуществующий, не связан +с ORCH-063, не влияет на функциональность.) + +## Итог +**PASS** — все 12 TC выполнены и зелёные, полный регресс `1296 passed`, smoke API (read-only) +исправен, блоки `serial_gate`/`auto_labels` в `/queue` на месте. Регрессов и обоснованных +FAIL не выявлено. Задача готова к переходу на `deploy-staging`. diff --git a/docs/work-items/ORCH-063/14-deploy-log.md b/docs/work-items/ORCH-063/14-deploy-log.md new file mode 100644 index 0000000..2dd312e --- /dev/null +++ b/docs/work-items/ORCH-063/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-063 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM. diff --git a/src/config.py b/src/config.py index 39c610d..1a9377f 100644 --- a/src/config.py +++ b/src/config.py @@ -1,3 +1,5 @@ +import logging + from pydantic import field_validator from pydantic_settings import BaseSettings @@ -381,6 +383,68 @@ class Settings(BaseSettings): reaper_finalize_grace_s: int = 300 lease_reclaim_enabled: bool = True + # ORCH-063: disk-watchdog — background heartbeat that measures host-FS fill via + # the mounted bind-paths and Telegram-alerts the operator at >= threshold. On + # 07.06.2026 the mva154 host disk silently hit 100% and stalled the WHOLE + # self-hosting pipeline; the watchdog is the missing proactive signal. Modelled + # on reconciler/job_reaper (daemon thread, start/stop in main.lifespan, /queue + # snapshot, never-raise). Anti-spam state is in-memory (no DB migration). + # disk_monitor_enabled -> kill-switch; False -> the daemon does not start + # (zero regression), env ORCH_DISK_MONITOR_ENABLED. + # disk_monitor_interval_s -> heartbeat measurement period, seconds (order of + # minutes; cheap shutil.disk_usage, no df subprocess). + # disk_monitor_threshold_pct -> fill % that triggers the alert (Owner-fixed 85). + # disk_monitor_realert_s -> min interval between repeat alerts while still + # above threshold (anti-spam cooldown, ~6h). + # disk_monitor_paths -> CSV of monitored HOST bind-paths (NOT overlay /); + # empty -> the default set (/repos, /app/data). + # Defensive validation (ADR-001 D7): threshold out of 1..100 or a non-positive + # interval -> default + warning (the process never crashes on a bad env value). + disk_monitor_enabled: bool = True + disk_monitor_interval_s: int = 300 + disk_monitor_threshold_pct: int = 85 + disk_monitor_realert_s: int = 21600 + disk_monitor_paths: str = "/repos,/app/data" + + @field_validator( + "disk_monitor_interval_s", "disk_monitor_realert_s", mode="before" + ) + @classmethod + def _disk_positive_int(cls, v, info): + # Non-positive / non-numeric interval -> the field default (never crash). + _defaults = {"disk_monitor_interval_s": 300, "disk_monitor_realert_s": 21600} + fallback = _defaults.get(info.field_name, 1) + try: + if v is None or (isinstance(v, str) and v.strip() == ""): + return fallback + iv = int(v) + if iv <= 0: + logging.getLogger("orchestrator.config").warning( + "%s must be > 0, got %s; falling back to %s", + info.field_name, v, fallback, + ) + return fallback + return iv + except (TypeError, ValueError): + return fallback + + @field_validator("disk_monitor_threshold_pct", mode="before") + @classmethod + def _disk_threshold_pct(cls, v): + # Threshold must be a percentage in 1..100; otherwise -> default 85. + try: + if v is None or (isinstance(v, str) and v.strip() == ""): + return 85 + iv = int(v) + if 1 <= iv <= 100: + return iv + logging.getLogger("orchestrator.config").warning( + "disk_monitor_threshold_pct must be 1..100, got %s; using 85", v + ) + return 85 + except (TypeError, ValueError): + return 85 + # ORCH-071: merge-verify under-gate on the `deploy -> done` edge. For the # self-hosting repo the `deploy` stage runs the DETERMINISTIC self-deploy path # (Phase A/B/C), where the LLM `deployer` agent — historically the ONLY actor diff --git a/src/disk_watchdog.py b/src/disk_watchdog.py new file mode 100644 index 0000000..1ac991b --- /dev/null +++ b/src/disk_watchdog.py @@ -0,0 +1,358 @@ +"""ORCH-063: disk-watchdog — host-FS fill heartbeat + Telegram alert at >=85%. + +On 07.06.2026 the mva154 host disk silently grew to 100% and took down the WHOLE +self-hosting pipeline of every project (one prod ``orchestrator`` instance serves +all prod projects from a shared DB/queue). The system had no proactive signal — +the operator only learned of the problem once the instance was already stuck. + +This module is a background daemon thread modelled 1:1 on ``reconciler`` +(ORCH-053) and ``job_reaper`` (ORCH-065): a ``threading.Thread(daemon=True)`` + +``threading.Event`` for a clean stop, the ``start()`` / ``stop(timeout)`` / +``status()`` contract, a ``/queue`` snapshot, per-tick never-raise and a +kill-switch (``ORCH_DISK_MONITOR_ENABLED``). Each tick measures the fill of the +mounted **host** bind-paths (``/repos``, ``/app/data``) via stdlib +``shutil.disk_usage`` — NOT the container overlay ``/``, NOT a ``df`` subprocess — +deduplicates paths by physical device (``st_dev``), and through a pure decision +function from ``(used_pct, threshold, prev_state, now, realert_s)`` decides to +alert (threshold crossed up), re-alert (cooldown elapsed), send recovery (back +below threshold) or stay silent. + +Invariants (TRZ §10 / ADR-001): + * ``STAGE_TRANSITIONS`` / ``QG_CHECKS`` / ``check_*`` / the DB schema are + UNCHANGED — the watchdog is an operational daemon, not a Quality Gate (like + ``reconciler`` / ``job_reaper``). No new migration (anti-spam state is + in-memory, best-effort, may reset on restart — safe: an early signal, not an + SLA). + * never-raise on three levels: per-path (a broken path is skipped, the rest are + measured), per-tick (outer ``try/except`` in ``_run``), per-send + (``send_telegram`` wrapped). + * Self-hosting safety: the watchdog only READS fill and SENDS Telegram — it + never touches the disk/container, never restarts prod. Safe for enduro-trails + in the shared instance. + * Kill-switch ``disk_monitor_enabled=False`` -> the daemon does not start + (``main.lifespan`` guard) and ``/queue`` returns ``{"enabled": false}`` — + behaviour 1:1 as before. + +See docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md and the cross-cutting +docs/architecture/adr/adr-0024-disk-watchdog.md. +""" + +import logging +import os +import shutil +import socket +import threading +import time +from dataclasses import dataclass +from datetime import datetime, timezone + +from .config import settings +from .notifications import send_telegram + +logger = logging.getLogger("orchestrator.disk_watchdog") + +_BYTES_PER_GB = 1024 ** 3 + +# Decision actions returned by ``decide_action`` (D3). +ACTION_NONE = "none" +ACTION_ALERT = "alert" +ACTION_REALERT = "realert" +ACTION_RECOVERY = "recovery" + + +@dataclass +class PathAlertState: + """In-memory anti-spam state for one logical device/path (D3). + + Best-effort: lives only in the daemon (no DB row, no migration). After a + process restart ``alerting`` resets to ``False`` -> a still-full disk re-alerts + once, which is safe (an early signal, not an SLA; TRZ §5/NFR-5). + """ + + alerting: bool = False + last_alert_at: float | None = None + + +def _resolve_host() -> str: + """Best-effort host label for alert text (never raises). + + The prod container runs ``network_mode: host`` so ``gethostname()`` resolves + to the real host (``mva154``). Any failure -> the neutral ``"host"``. + """ + try: + name = socket.gethostname() + return name or "host" + except Exception: # noqa: BLE001 - never break the tick + return "host" + + +def parse_paths(raw: str) -> list[str]: + """Parse the ``disk_monitor_paths`` CSV into a clean path list. + + Empty / blank -> the default host bind-paths (``/repos``, ``/app/data``, + TRZ §8). Never raises. + """ + default = ["/repos", "/app/data"] + try: + if not raw or not raw.strip(): + return default + paths = [p.strip() for p in raw.split(",") if p.strip()] + return paths or default + except Exception: # noqa: BLE001 - never break the tick + return default + + +def decide_action( + used_pct: float, + threshold: float, + prev: PathAlertState, + now: float, + realert_s: float, +) -> str: + """Pure alert decision (D3) — testable without a thread or a real timer. + + Returns one of ``ACTION_{NONE,ALERT,REALERT,RECOVERY}`` as a function of the + current fill, the threshold, the previous per-path state and the injected + clock: + + * not alerting & ``used_pct >= threshold`` -> ALERT (crossed up) + * alerting & still ``>= threshold`` & cooldown -> REALERT (re-alert) + * alerting & still ``>= threshold`` & in cooldown-> NONE (anti-spam) + * alerting & ``used_pct < threshold`` -> RECOVERY (crossed down) + * not alerting & ``used_pct < threshold`` -> NONE (normal) + + Threshold is inclusive: ``used_pct == threshold`` counts as exceeding + (``>=``, TC-05). + """ + above = used_pct >= threshold + if not prev.alerting: + return ACTION_ALERT if above else ACTION_NONE + # prev.alerting is True + if not above: + return ACTION_RECOVERY + last = prev.last_alert_at + if last is None or (now - last) >= realert_s: + return ACTION_REALERT + return ACTION_NONE + + +def _measure_one(path: str) -> dict | None: + """Measure one path via ``shutil.disk_usage`` (D1). Never raises. + + Returns a measurement dict, or ``None`` if the path is missing / unreadable + (``FileNotFoundError`` / ``PermissionError`` / ``OSError``) -> the caller skips + THIS path and keeps measuring the others (FR-2, AC-6: one broken path never + fails the whole tick). + """ + try: + usage = shutil.disk_usage(path) + total = int(usage.total) + used = int(usage.used) + free = int(usage.free) + used_pct = round(used / total * 100, 1) if total > 0 else 0.0 + free_pct = round(free / total * 100, 1) if total > 0 else 0.0 + return { + "path": path, + "total_bytes": total, + "used_bytes": used, + "free_bytes": free, + "used_pct": used_pct, + "free_pct": free_pct, + "free_gb": round(free / _BYTES_PER_GB, 1), + } + except Exception as e: # noqa: BLE001 - skip this path, keep the tick alive + logger.warning("disk-watchdog: cannot measure path %s, skipping: %s", path, e) + return None + + +def _dedup_key(path: str) -> object: + """Physical-device dedup key (D2): ``st_dev`` if resolvable, else the path. + + Paths sharing a device (``/repos`` and ``/app/data`` on the same host + partition) collapse to one logical partition -> one alert, not two. Failure to + ``os.stat`` -> fail-open (the path is its own key, measured independently). + """ + try: + return os.stat(path).st_dev + except Exception: # noqa: BLE001 - fail-open, treat as a distinct device + return path + + +def measure_paths(paths: list[str]) -> list[dict]: + """Measure every path, deduplicated by physical device (D1/D2). Never raises. + + For each distinct ``st_dev`` the FIRST successfully-measured path is kept and + carries a stable ``dedup_key`` (so anti-spam state is per-device). A path that + fails to measure is skipped (AC-6). + """ + out: list[dict] = [] + seen: set[object] = set() + for path in paths: + key = _dedup_key(path) + if key in seen: + continue + m = _measure_one(path) + if m is None: + continue + seen.add(key) + m["dedup_key"] = key + out.append(m) + return out + + +def format_alert_message(m: dict, threshold: float, host: str) -> str: + """Actionable Telegram alert text (FR-3/AC-2): host, path, used %, free, threshold.""" + return ( + f"\U0001f534 Диск {host}: {m['path']} заполнен на {m['used_pct']}% " + f"(порог {threshold}%). Свободно {m['free_gb']} ГБ ({m['free_pct']}%). " + f"Освободите место — риск остановки конвейера всех проектов." + ) + + +def format_recovery_message(m: dict, host: str) -> str: + """Single recovery message when fill returns below threshold (FR-4/AC-4).""" + return ( + f"\U0001f7e2 Диск {host}: {m['path']} вернулся ниже порога — " + f"{m['used_pct']}% (свободно {m['free_gb']} ГБ)." + ) + + +class DiskWatchdog: + """Background daemon measuring host-FS fill and alerting on >= threshold. + + Modelled on ``Reconciler`` / ``JobReaper``: a ``threading.Thread(daemon=True)`` + + a ``threading.Event`` for a clean stop. The only in-memory state is the + best-effort anti-spam map (``_states``), the last-measurement snapshot + (``_last``) and ``last_run_ts`` — all reset on restart, which is safe (D3). + + ``now_provider`` is injectable so the cooldown / recovery logic is testable + deterministically without a real timer (AC-3). + """ + + def __init__(self, interval_s: float | None = None, now_provider=None): + self.interval_s = ( + interval_s if interval_s is not None else settings.disk_monitor_interval_s + ) + self._now = now_provider or time.time + self._stop = threading.Event() + self._thread: threading.Thread | None = None + self._host = _resolve_host() + # Best-effort in-memory state, per dedup_key (device/path). + self._states: dict[object, PathAlertState] = {} + self._last: dict[object, dict] = {} + self.last_run_ts: float | None = None + + # -- config helpers ---------------------------------------------------- + @property + def _threshold(self) -> int: + return settings.disk_monitor_threshold_pct + + @property + def _realert_s(self) -> int: + return settings.disk_monitor_realert_s + + def _paths(self) -> list[str]: + return parse_paths(settings.disk_monitor_paths) + + # -- tick -------------------------------------------------------------- + def tick(self) -> None: + """One measurement pass over all monitored paths (never-raise per send). + + Measures every (deduplicated) path, runs the pure ``decide_action`` per + device and dispatches the resulting alert / re-alert / recovery via + ``send_telegram`` (notifying). Telegram failures are logged and swallowed + (best-effort delivery, AC-6). + """ + threshold = self._threshold + realert_s = self._realert_s + now = self._now() + for m in measure_paths(self._paths()): + key = m["dedup_key"] + prev = self._states.get(key) or PathAlertState() + action = decide_action(m["used_pct"], threshold, prev, now, realert_s) + if action in (ACTION_ALERT, ACTION_REALERT): + self._send(format_alert_message(m, threshold, self._host), notifying=True) + self._states[key] = PathAlertState(alerting=True, last_alert_at=now) + elif action == ACTION_RECOVERY: + self._send(format_recovery_message(m, self._host), notifying=True) + self._states[key] = PathAlertState(alerting=False, last_alert_at=None) + # ACTION_NONE: leave prev state untouched (anti-spam / normal). + # Record the snapshot for /queue observability. + cur = self._states.get(key) or prev + self._last[key] = { + "path": m["path"], + "used_pct": m["used_pct"], + "free_gb": m["free_gb"], + "free_pct": m["free_pct"], + "alerting": cur.alerting, + "last_alert_at": cur.last_alert_at, + } + + def _send(self, text: str, notifying: bool) -> None: + """Send a Telegram alert (notifying, not silent). Never raises (AC-6).""" + try: + send_telegram(text, disable_notification=not notifying) + except Exception as e: # noqa: BLE001 - delivery is best-effort + logger.warning("disk-watchdog: telegram send failed: %s", e) + + # -- loop / lifecycle -------------------------------------------------- + def _tick(self) -> None: + try: + self.tick() + finally: + self.last_run_ts = datetime.now(timezone.utc).timestamp() + + def _run(self) -> None: + logger.info( + "DiskWatchdog started (interval=%ss, threshold=%s%%, realert=%ss, " + "paths=%s, enabled=%s)", + self.interval_s, self._threshold, self._realert_s, + self._paths(), settings.disk_monitor_enabled, + ) + while not self._stop.is_set(): + try: + self._tick() + except Exception as e: # noqa: BLE001 - outer never-raise + logger.error("DiskWatchdog loop error: %s", e) + self._stop.wait(self.interval_s) + logger.info("DiskWatchdog stopped") + + def start(self) -> None: + """Start the daemon thread (idempotent: a live thread is a no-op). + + Honours the kill-switch: ``disk_monitor_enabled=False`` -> no-op (the + daemon never starts; ``main.lifespan`` also guards, AC-5/TC-09). + """ + if not settings.disk_monitor_enabled: + return + if self._thread and self._thread.is_alive(): + return + self._stop.clear() + self._thread = threading.Thread( + target=self._run, name="disk-watchdog", daemon=True + ) + self._thread.start() + + def stop(self, timeout: float = 5.0) -> None: + self._stop.set() + if self._thread: + self._thread.join(timeout=timeout) + + def status(self) -> dict: + """Disk-monitor snapshot for /queue observability (FR-6/AC-7). Never raises.""" + try: + return { + "enabled": settings.disk_monitor_enabled, + "threshold_pct": self._threshold, + "interval_s": self.interval_s, + "realert_s": self._realert_s, + "last_run_ts": self.last_run_ts, + "paths": list(self._last.values()), + } + except Exception as e: # noqa: BLE001 - observability must never raise + logger.warning("disk-watchdog: status() failed: %s", e) + return {"enabled": settings.disk_monitor_enabled} + + +# Module-level singleton used by the FastAPI lifespan. +disk_watchdog = DiskWatchdog() diff --git a/src/main.py b/src/main.py index ccb3734..38811c8 100644 --- a/src/main.py +++ b/src/main.py @@ -105,9 +105,19 @@ async def lifespan(app: FastAPI): from .job_reaper import reaper reaper.start() + # ORCH-063: start the disk-watchdog LAST (after the reaper). It is independent + # of the queue/DB — it only reads host-FS fill and Telegram-alerts at >= + # threshold — so the order is not critical, but we follow the daemon + # convention. Honours the kill-switch ORCH_DISK_MONITOR_ENABLED (start() is a + # no-op when disabled, so behaviour is 1:1 as before). + from .disk_watchdog import disk_watchdog + disk_watchdog.start() + try: yield finally: + # ORCH-063: stop the disk-watchdog first (reverse of startup). + disk_watchdog.stop() # Graceful shutdown order mirrors startup in reverse: stop the reaper # first, then the reconciler (it must not enqueue new work while the # worker is winding down), then the worker. Running agents keep going; @@ -151,6 +161,7 @@ async def queue(): from . import task_deps from . import serial_gate from . import labels + from .disk_watchdog import disk_watchdog return { "counts": job_status_counts(), "max_concurrency": worker.max_concurrency, @@ -169,6 +180,10 @@ async def queue(): # ORCH-089 (D7): auto-mode-by-label observability (read-only) — kill-switch, # label names, scope. Additive block. "auto_labels": labels.snapshot(), + # ORCH-063 (FR-6 / AC-7): disk-watchdog observability (read-only) — + # enabled, threshold, interval, last measurement per host-path. Additive + # block; never-raise (status() returns {"enabled": ...} minimum on error). + "disk_monitor": disk_watchdog.status(), "recent": recent_jobs(10), } diff --git a/tests/test_disk_watchdog.py b/tests/test_disk_watchdog.py new file mode 100644 index 0000000..328802b --- /dev/null +++ b/tests/test_disk_watchdog.py @@ -0,0 +1,329 @@ +"""ORCH-063: disk-watchdog tests (TC-01..TC-12). + +The watchdog never touches a real disk or Telegram: ``shutil.disk_usage`` is +monkeypatched to set ``used_pct`` deterministically, ``send_telegram`` is captured +via monkeypatch, and the cooldown/recovery clock is injected through +``now_provider`` so time-dependent decisions are tested without a real timer. +""" +import os +import tempfile + +import pytest + +# Override env before importing app modules (same convention as test_reaper.py). +os.environ.setdefault("ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_orch_disk.db")) +os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token") +os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token") + +import src.disk_watchdog as dw # noqa: E402 +from src.disk_watchdog import ( # noqa: E402 + ACTION_ALERT, + ACTION_NONE, + ACTION_REALERT, + ACTION_RECOVERY, + DiskWatchdog, + PathAlertState, + decide_action, + format_alert_message, + format_recovery_message, + measure_paths, + parse_paths, +) + + +# --------------------------------------------------------------------------- # +# Helpers +# --------------------------------------------------------------------------- # +def _usage(used_pct: float, total_gb: float = 100.0): + """Build a fake ``shutil.disk_usage`` result with the given fill %.""" + total = int(total_gb * (1024 ** 3)) + used = int(total * used_pct / 100) + free = total - used + + class _U: + pass + + u = _U() + u.total, u.used, u.free = total, used, free + return u + + +@pytest.fixture +def captured_sends(monkeypatch): + """Capture every ``send_telegram`` call made by the watchdog.""" + calls = [] + + def _fake_send(text, disable_notification=False): + calls.append({"text": text, "disable_notification": disable_notification}) + return 1 + + monkeypatch.setattr(dw, "send_telegram", _fake_send) + return calls + + +# --------------------------------------------------------------------------- # +# TC-01..TC-05: pure decision function +# --------------------------------------------------------------------------- # +def test_tc01_alert_on_crossing_up(): + """TC-01: was below, now >= threshold -> ALERT (threshold crossed).""" + prev = PathAlertState(alerting=False, last_alert_at=None) + assert decide_action(90.0, 85, prev, now=1000.0, realert_s=21600) == ACTION_ALERT + + +def test_tc02_antispam_within_cooldown(): + """TC-02: already alerting, above, < realert_s since last -> NONE (anti-spam).""" + prev = PathAlertState(alerting=True, last_alert_at=1000.0) + # 1000 s later, cooldown is 21600 -> still suppressed. + assert decide_action(90.0, 85, prev, now=2000.0, realert_s=21600) == ACTION_NONE + + +def test_tc03_realert_after_cooldown(): + """TC-03: already alerting, above, >= realert_s elapsed -> REALERT.""" + prev = PathAlertState(alerting=True, last_alert_at=1000.0) + assert decide_action(90.0, 85, prev, now=1000.0 + 21600, realert_s=21600) == ACTION_REALERT + + +def test_tc04_recovery_and_no_repeat(): + """TC-04: above->below resets state with one RECOVERY; staying below is silent.""" + prev_above = PathAlertState(alerting=True, last_alert_at=1000.0) + assert decide_action(70.0, 85, prev_above, now=5000.0, realert_s=21600) == ACTION_RECOVERY + # After recovery the state is non-alerting; staying below -> NONE (no repeat). + prev_below = PathAlertState(alerting=False, last_alert_at=None) + assert decide_action(70.0, 85, prev_below, now=6000.0, realert_s=21600) == ACTION_NONE + + +def test_tc05_threshold_boundary_inclusive(): + """TC-05: used_pct == threshold counts as exceeding; threshold-1 is silent.""" + below = PathAlertState(alerting=False, last_alert_at=None) + assert decide_action(85.0, 85, below, now=1.0, realert_s=10) == ACTION_ALERT + assert decide_action(84.0, 85, below, now=1.0, realert_s=10) == ACTION_NONE + + +# --------------------------------------------------------------------------- # +# TC-06: measurement + device dedup +# --------------------------------------------------------------------------- # +def test_tc06_measure_and_dedup_by_device(monkeypatch): + """TC-06: per-path used_pct/free computed; same-device paths dedup to one.""" + monkeypatch.setattr(dw.shutil, "disk_usage", lambda p: _usage(50.0)) + # Both paths share st_dev=42 -> single logical partition. + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": 42})()) + + out = measure_paths(["/repos", "/app/data"]) + assert len(out) == 1 + m = out[0] + assert m["used_pct"] == 50.0 + assert m["free_bytes"] > 0 and m["free_gb"] > 0 + assert m["dedup_key"] == 42 + + # Distinct devices -> two measurements. + devs = iter([1, 2]) + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": next(devs)})()) + out2 = measure_paths(["/repos", "/app/data"]) + assert len(out2) == 2 + + +# --------------------------------------------------------------------------- # +# TC-07: never-raise (broken path + send failure) +# --------------------------------------------------------------------------- # +def test_tc07_broken_path_does_not_kill_tick(monkeypatch): + """TC-07: a missing path is skipped; other paths are still measured.""" + def _maybe_raise(path): + if path == "/nope": + raise FileNotFoundError(path) + return _usage(50.0) + + monkeypatch.setattr(dw.shutil, "disk_usage", _maybe_raise) + devs = {"/nope": 1, "/repos": 2} + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": devs[p]})()) + + out = measure_paths(["/nope", "/repos"]) + assert len(out) == 1 + assert out[0]["path"] == "/repos" + + +def test_tc07_send_failure_does_not_raise(monkeypatch): + """TC-07: an exception in send_telegram is swallowed; the tick completes.""" + monkeypatch.setattr(dw.shutil, "disk_usage", lambda p: _usage(95.0)) + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": 7})()) + + def _boom(text, disable_notification=False): + raise RuntimeError("telegram down") + + monkeypatch.setattr(dw, "send_telegram", _boom) + wd = DiskWatchdog(now_provider=lambda: 1000.0) + wd.tick() # must not raise + + +# --------------------------------------------------------------------------- # +# TC-08: alert message format + notifying +# --------------------------------------------------------------------------- # +def test_tc08_alert_message_actionable_and_notifying(monkeypatch, captured_sends): + """TC-08: alert carries path/used_pct/free/threshold; sent notifying.""" + monkeypatch.setattr(dw.shutil, "disk_usage", lambda p: _usage(87.3)) + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": 9})()) + monkeypatch.setattr(dw.settings, "disk_monitor_paths", "/repos", raising=False) + monkeypatch.setattr(dw.settings, "disk_monitor_threshold_pct", 85, raising=False) + + wd = DiskWatchdog(now_provider=lambda: 1000.0) + wd.tick() + + assert len(captured_sends) == 1 + call = captured_sends[0] + text = call["text"] + assert "/repos" in text + assert "87.3" in text + assert "85" in text # threshold + assert "ГБ" in text # free space + assert call["disable_notification"] is False # notifying, not silent + + +def test_tc08_format_helpers(): + """TC-08 (unit): format helpers contain the actionable fields.""" + m = {"path": "/repos", "used_pct": 88.0, "free_gb": 6.2, "free_pct": 12.0} + alert = format_alert_message(m, 85, "mva154") + assert "/repos" in alert and "88.0" in alert and "85" in alert and "6.2" in alert + rec = format_recovery_message(m, "mva154") + assert "/repos" in rec and "88.0" in rec + + +# --------------------------------------------------------------------------- # +# TC-09: kill-switch +# --------------------------------------------------------------------------- # +def test_tc09_killswitch_does_not_start(monkeypatch): + """TC-09: disk_monitor_enabled=False -> start() is a no-op (no thread).""" + monkeypatch.setattr(dw.settings, "disk_monitor_enabled", False, raising=False) + wd = DiskWatchdog() + wd.start() + assert wd._thread is None + + +def test_tc09_killswitch_status_block(monkeypatch): + """TC-09: status() reports enabled=False under the kill-switch.""" + monkeypatch.setattr(dw.settings, "disk_monitor_enabled", False, raising=False) + wd = DiskWatchdog() + assert wd.status()["enabled"] is False + + +# --------------------------------------------------------------------------- # +# TC-10: status() +# --------------------------------------------------------------------------- # +def test_tc10_status_shape(monkeypatch): + """TC-10: status() returns the expected keys, never-raise with no measurements.""" + monkeypatch.setattr(dw.settings, "disk_monitor_enabled", True, raising=False) + wd = DiskWatchdog() + st = wd.status() + for key in ("enabled", "threshold_pct", "interval_s", "realert_s", "last_run_ts", "paths"): + assert key in st + assert st["paths"] == [] # no tick yet + + +def test_tc10_status_reflects_last_measurement(monkeypatch): + """TC-10: after a tick status().paths carries used_pct/free/alerting/last_alert_at.""" + monkeypatch.setattr(dw.shutil, "disk_usage", lambda p: _usage(90.0)) + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": 3})()) + monkeypatch.setattr(dw.settings, "disk_monitor_paths", "/repos", raising=False) + monkeypatch.setattr(dw, "send_telegram", lambda *a, **k: 1) + + wd = DiskWatchdog(now_provider=lambda: 1000.0) + wd.tick() + paths = wd.status()["paths"] + assert len(paths) == 1 + p = paths[0] + assert p["path"] == "/repos" + assert p["used_pct"] == 90.0 + assert p["alerting"] is True + assert p["last_alert_at"] == 1000.0 + for key in ("free_gb", "free_pct"): + assert key in p + + +# --------------------------------------------------------------------------- # +# Anti-spam / recovery end-to-end through tick() +# --------------------------------------------------------------------------- # +def test_tick_antispam_then_realert_then_recovery(monkeypatch, captured_sends): + """End-to-end: one alert on crossing, silence within cooldown, realert after + cooldown, then a single recovery — driving the daemon's in-memory state.""" + fill = {"pct": 90.0} + clock = {"t": 1000.0} + monkeypatch.setattr(dw.shutil, "disk_usage", lambda p: _usage(fill["pct"])) + monkeypatch.setattr(dw.os, "stat", lambda p: type("S", (), {"st_dev": 5})()) + monkeypatch.setattr(dw.settings, "disk_monitor_paths", "/repos", raising=False) + monkeypatch.setattr(dw.settings, "disk_monitor_threshold_pct", 85, raising=False) + monkeypatch.setattr(dw.settings, "disk_monitor_realert_s", 100, raising=False) + + wd = DiskWatchdog(now_provider=lambda: clock["t"]) + + wd.tick() # crossing up -> ALERT + assert len(captured_sends) == 1 + + clock["t"] += 10 # within cooldown -> silent + wd.tick() + assert len(captured_sends) == 1 + + clock["t"] += 200 # cooldown elapsed -> REALERT + wd.tick() + assert len(captured_sends) == 2 + + fill["pct"] = 70.0 # drop below -> RECOVERY (one message) + clock["t"] += 10 + wd.tick() + assert len(captured_sends) == 3 + assert "ниже порога" in captured_sends[2]["text"] + + wd.tick() # stays below -> silent (no repeat recovery) + assert len(captured_sends) == 3 + + +# --------------------------------------------------------------------------- # +# parse_paths +# --------------------------------------------------------------------------- # +def test_parse_paths_default_and_csv(): + assert parse_paths("") == ["/repos", "/app/data"] + assert parse_paths(" ") == ["/repos", "/app/data"] + assert parse_paths("/a, /b ,/c") == ["/a", "/b", "/c"] + + +# --------------------------------------------------------------------------- # +# TC-11 / TC-12: GET /queue integration +# --------------------------------------------------------------------------- # +def test_tc11_queue_has_disk_monitor_block(monkeypatch): + """TC-11: GET /queue carries an additive disk_monitor block; existing keys kept.""" + import asyncio + import src.db as db + from src.db import init_db + from src import main + + dbfile = os.path.join(tempfile.gettempdir(), "test_disk_queue.db") + monkeypatch.setattr(db.settings, "db_path", dbfile, raising=False) + init_db() + + payload = asyncio.run(main.queue()) + + for key in ( + "counts", "max_concurrency", "poll_interval", "resilience", "reconcile", + "reaper", "post_deploy", "merge_verify", "task_deps", "serial_gate", + "auto_labels", "recent", + ): + assert key in payload, f"existing /queue key '{key}' must be preserved" + + assert "disk_monitor" in payload + dm = payload["disk_monitor"] + assert "enabled" in dm and "threshold_pct" in dm and "interval_s" in dm + assert "paths" in dm + + +def test_tc12_queue_disabled_block(monkeypatch): + """TC-12: with the kill-switch off, /queue reports disk_monitor.enabled=false.""" + import asyncio + import src.db as db + from src.db import init_db + from src import main + from src import disk_watchdog as dwmod + + dbfile = os.path.join(tempfile.gettempdir(), "test_disk_queue2.db") + monkeypatch.setattr(db.settings, "db_path", dbfile, raising=False) + monkeypatch.setattr(dwmod.settings, "disk_monitor_enabled", False, raising=False) + init_db() + + payload = asyncio.run(main.queue()) + assert payload["disk_monitor"]["enabled"] is False