87 lines
6.3 KiB
Markdown
87 lines
6.3 KiB
Markdown
---
|
||
verdict: APPROVED
|
||
work_item: ORCH-099
|
||
stage: review
|
||
author_agent: reviewer
|
||
status: approved
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
type: review
|
||
work_item_id: ORCH-099
|
||
version: 1
|
||
---
|
||
|
||
# Review ORCH-099 — FND/F1a: лёгкий read-only `GET /metrics` (сырьё для sidecar F1b)
|
||
|
||
## Summary
|
||
|
||
Реализация полностью соответствует ТЗ (`02-trz.md`), критериям приёмки (`03-acceptance-criteria.md`)
|
||
и архитектурному решению (`06-adr/ADR-001` + сквозной `adr-0030`). Добавлен аддитивный, строго
|
||
read-only, never-raise эндпоинт `GET /metrics` через leaf-модуль `src/metrics.py` (`build_metrics()`,
|
||
паттерн `serial_gate.snapshot()`) + тонкая обёртка в `src/main.py` + три read-only helper'а в
|
||
`src/db.py`. Конвейерные инварианты целы: `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` /
|
||
machine-verdict ключи / схема БД — не тронуты (в диффе нет `src/stages.py`/`src/qg/`; упоминания этих
|
||
имён — только в документации/комментариях). Полный регресс `pytest tests/ -q` — **1482 passed**.
|
||
Документация обновлена в том же PR. Блокирующих findings нет.
|
||
|
||
**Оси проверки:**
|
||
|
||
1. **Соответствие ТЗ** — ✅. FR-1 (`stages`, фильтр терминалов `{done,cancelled}`), FR-2 (`queue`:
|
||
counts+`cancelled`, depth, retries, breaker, max_concurrency), FR-3 (`agents`-liveness:
|
||
agent/run_id/job_id/pid/runtime_s/model/effort + `cpu_ticks`), FR-4 (`cost`: running+aggregate),
|
||
FR-5 (конверт `schema_version`/`generated_at`/`clk_tck`), FR-6 (never-raise по разделам) —
|
||
реализованы. AC-1…AC-8 проверены по коду и тестам (TC-01…TC-11), все зелёные.
|
||
2. **Соответствие ADR** — ✅. D1–D8 реализованы как описано: D3 фильтр терминалов на потребителе
|
||
(helper-инвариант ORCH-053/086 не тронут); D5 dedicated `get_running_agents()` вместо расширения
|
||
hot-path `get_running_jobs()` (ORCH-065); D6 `runtime_s` от `jobs.started_at`; D8 kill-switch
|
||
`metrics_endpoint_enabled` (дефолт `True`, `200` с минимальным телом при `False`). Глобальный
|
||
инвариант терминального множества `{done,cancelled}` (adr-0026) соблюдён. `validation_alias`
|
||
`ORCH_METRICS_ENABLED` — обоснованное усиление D8 (документированное имя контракта реально
|
||
управляет флагом), покрыто `tests/test_config.py`. Нарушений глобальных ADR нет.
|
||
3. **Качество кода** — ✅. Все колонки БД (`agent_runs.{cost_usd,*_tokens}`, `jobs.{pid,run_id,
|
||
started_at,repo,attempts,transient_attempts,available_at}`) сверены — существуют. Парсинг
|
||
`/proc/<pid>/stat` устойчив к пробелам/скобкам в `comm` (`rfind(") ")`, индексы 11/12 = поля
|
||
14/15); `_read_cpu_ticks` never-raise per-pid. Docstrings на всех публичных функциях, тесты
|
||
содержательные (живой pid → реальный int, мёртвый/`None` → `null`, бросающий источник → дефолт).
|
||
4. **Документация** — ✅ (см. секцию ниже).
|
||
|
||
## Findings
|
||
|
||
### P0 — Blocker
|
||
- Нет.
|
||
|
||
### P1 — Must fix
|
||
- Нет.
|
||
|
||
### P2 — Should fix
|
||
- Нет.
|
||
|
||
### P3 — Nice-to-have (не блокирует)
|
||
- [ ] `db.get_running_agents()` вызывается дважды на один запрос `/metrics` — в `_build_agents` и в
|
||
`_build_cost` (`src/metrics.py:176` и `:206`) — два идентичных SELECT'а. На типовом объёме
|
||
(running-jobs ≤ `max_concurrency`) — пренебрежимо, AC-3 не нарушен; при желании можно выбрать строки
|
||
один раз и переиспользовать. Косметика, исправление не требуется для приёмки.
|
||
|
||
## Документация
|
||
|
||
Обновлена в том же PR (правило «доки = golden source», AC-7) — проверено явно:
|
||
- **`docs/architecture/README.md`** — новый компонент «Metrics endpoint» в списке, полный раздел-
|
||
контракт «Сырьё-эндпоинт `/metrics` для sidecar» (конверт, разделы, политика `schema_version`,
|
||
гарантии read-only/never-raise, kill-switch) и строка в таблице API. Соответствует фактическому
|
||
ответу эндпоинта.
|
||
- **`CHANGELOG.md`** — запись `## [Unreleased]` с пометкой `ORCH-099` (D1–D8 + тесты + откат).
|
||
- **`docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`** — детальное решение (D1–D8).
|
||
- **`docs/architecture/adr/adr-0030-metrics-endpoint.md`** — сквозной ADR (новый компонент
|
||
наблюдаемости + публичный контракт), зарегистрирован в `docs/architecture/adr/README.md` (индекс +
|
||
«текущий максимум — `0030`»).
|
||
- **`.env.example`** — задокументирован `ORCH_METRICS_ENABLED=true`.
|
||
|
||
`src/` изменён → документация обновлена (golden source соблюдён). Эпик-обзорные доки `README.md`
|
||
«Известные ограничения» этой задачей не затрагиваются (новый компонент, не закрытие ограничения).
|
||
|
||
## Регресс / проверки
|
||
- `pytest tests/ -q` → **1482 passed** (новые `tests/test_metrics.py` TC-01…TC-11 + `test_config.py`
|
||
×2; регресс `/health`//status//queue зелёный, TC-10).
|
||
- Дифф `src/stages.py` / `src/qg/` — пуст; machine-verdict ключи и схема БД — байт-в-байт прежние.
|
||
- Read-only подтверждён тестом снимка БД до/после (TC-09); never-raise — TC-05/TC-07.
|