diff --git a/10-platform/health.md b/10-platform/health.md index 29af8a9..31e01a9 100644 --- a/10-platform/health.md +++ b/10-platform/health.md @@ -65,6 +65,7 @@ - `service`, `version`, `timestamp` — необязательные, для журналов. Мониторы, написанные по §1–2, работают с таким телом без изменений. +Полный набор слоёв самосвидетельства — §5. ## 4. Требования к эндпоинту @@ -78,6 +79,39 @@ - **Путь** — `/health` или `/healthz`, на выбор сервиса; монитор берёт полный URL из настроек. +## 5. Самосвидетельство (расширенное тело) + +Ответ health может нести не только лайвность, но и самосвидетельство — необязательные +слои информации о себе. Всё ниже необязательно; монитор по минимуму (§1–2) обязан +незнакомые поля игнорировать, сервис с богатым телом ничего не ломает. + +### Слои самосвидетельства + +**Identity — кто я.** +`service` (самоназвание), `version`, `build` (git sha), `environment` (production/…), +`uptime` (секунды) или `since` (ISO — момент старта). Монитор сверяет `service` с +настройкой (защита от перепутанного URL), показывает версию и аптайм в карточке; +сброс `uptime` между опросами — сигнал «сервис перезапустился». + +**Mode — сознательные состояния.** +`"mode": "maintenance" | "readonly" | "draining"` — сервис жив, это делается +намеренно (миграция, бэкап). Монитор показывает нейтральный бейдж «обслуживание»: +не degraded и не падение доступности. + +**Gauges — рабочие показатели.** +`"gauges": {"queue_depth": 42, "db_pool_in_use": 7, "cache_hit_ratio": 0.87}` — +числа без интерпретаций. Пороги и суждения остаются монитору: `"cpu": 62` — хорошо, +`"cpu_warn": true` — плохо. Очереди, пулы, кэш, счётчики — всё, что сервис считает +полезным для стороннего взгляда. + +### Ограничения +- **Без секретов и персональных данных.** Эндпоинт без авторизации — что в health, + читает любой в сети: имена пользователей, токены, содержимое секретов, внутренняя + топология — нельзя; версии, счётчики, режимы — можно. +- **Дёшево на пинге** (каждые ~30 с): gauges — из лёгкой статистики в памяти; + что дороже — кэшировать (§4). +- **timestamp** обязателен для кэшированных ответов — монитор видит свежесть ответа. + ## Ссылки - Референс-потребитель: hard-panel — https://git.gnexus.space/root/hard-panel