Проверки состояния backend-процессов¶
Требования этого документа применяются к долгоживущим backend-процессам:
API, worker-, consumer-процессам и data pipelines. Уровни обязательности
определены в корневом README.md.
BE-HLTH-001. Раздельные проверки состояния¶
Уровень: MUST
Применяется к: каждому экземпляру долгоживущего backend-процесса в среде, поддерживающей проверки состояния
Экземпляр должен предоставлять среде исполнения раздельные проверки liveness и readiness через поддерживаемый ею интерфейс.
Если используется HTTP, успешная проверка должна возвращать 200 OK,
неуспешная — 503 Service Unavailable; ответ должен иметь
Content-Type: application/json и поле status со значением pass или
fail.
Ненормативная
health-check.schema.json проецирует
только JSON body и не определяет HTTP method, path, status или header.
Обоснование¶
Разделение семантики позволяет среде исполнения принимать правильное решение, а единый HTTP-контракт упрощает наиболее распространённую интеграцию.
Проверка¶
- contract-тест обеих проверок и их состояний;
- для HTTP — тест статусов и JSON-ответов;
- проверка конфигурации probe среды исполнения;
- запуск проверки для каждого типа процесса проекта.
Исключения¶
Краткоживущая задача и среда без механизма проверок состояния находятся вне области требования. Отсутствие именно HTTP-интерфейса не является исключением.
BE-HLTH-009. Стандартные HTTP-пути проверок¶
Уровень: SHOULD
Применяется к: HTTP-интерфейсу liveness и readiness
Для liveness следует использовать GET /healthz/live, для readiness —
GET /healthz/ready. Другие методы на выбранных путях следует отклонять с
405 Method Not Allowed.
Обоснование¶
Единые пути упрощают платформенную конфигурацию, но могут быть заменены эквивалентным контрактом конкретной среды исполнения.
Проверка¶
- contract-тест путей и методов;
- сопоставление путей с конфигурацией probe.
Исключения¶
Другие стабильные пути MAY использоваться, если они явно заданы в deployment- контракте и проверяются автоматически.
BE-HLTH-002. Семантика liveness¶
Уровень: MUST
Применяется к: проверке liveness
Liveness должна быть успешной, пока процесс способен выполнять свой цикл
обработки и может восстановиться без перезапуска. Проверка должна быть
неуспешной только при состоянии, для восстановления из которого требуется
перезапуск экземпляра. HTTP-интерфейс должен отображать эти состояния в
200 OK и 503 Service Unavailable соответственно.
Liveness не должен проверять сеть, базу данных, broker, cache, внешние сервисы, OpenTelemetry Collector, OpenObserve, Vector или GlitchTip.
Обоснование¶
Зависимость liveness от внешней системы вызывает массовые перезапуски исправных экземпляров и усиливает исходный отказ.
Проверка¶
- fault-injection тест недоступности каждой внешней зависимости;
- тест обнаруживаемого зависания внутреннего цикла обработки;
- проверка отсутствия сетевых вызовов из liveness.
Исключения¶
Не допускаются для внешних зависимостей.
BE-HLTH-003. Семантика readiness¶
Уровень: MUST
Применяется к: проверке readiness
Readiness должна быть успешной только тогда, когда экземпляр готов принять
новую работу и выполнить её обязательный контракт. HTTP-интерфейс должен
возвращать 200 OK для успешного и 503 Service Unavailable для неуспешного
состояния.
Readiness должен учитывать завершение инициализации и доступность только тех зависимостей, без которых экземпляр не способен выполнить ни одну назначенную ему операцию. Частичный отказ зависимости не должен делать весь экземпляр неготовым, если маршрутизация или контракт позволяют обслуживать независимые операции безопасно.
Недоступность необязательной зависимости и платформы наблюдаемости не должна делать экземпляр неготовым.
Обоснование¶
Readiness исключает заведомо неспособный экземпляр из маршрутизации, не распространяя частичный отказ на независимые функции.
Проверка¶
- таблица обязательных зависимостей и операций процесса;
- fault-injection тест каждой обязательной и необязательной зависимости;
- integration-тест начальной инициализации и восстановления зависимости.
Исключения¶
Состав обязательных зависимостей определяется архитектурой проекта и должен быть зафиксирован в проверяемой конфигурации или проектном контракте.
BE-HLTH-004. Состояние при запуске¶
Уровень: MUST
Применяется к: периоду от запуска процесса с проверками по BE-HLTH-001
до окончания инициализации
После запуска интерфейса проверок liveness должна быть успешной, если процесс не требует перезапуска. Readiness должна оставаться неуспешной до завершения всей обязательной инициализации.
Процесс не должен сообщать readiness до применения конфигурации, завершения обязательных миграционных или стартовых проверок и готовности обработчиков принимать работу.
Обоснование¶
Раздельное состояние предотвращает маршрутизацию трафика в частично инициализированный экземпляр без ошибочного перезапуска исправного процесса.
Проверка¶
- integration-тест медленной и неуспешной инициализации;
- проверка последовательности liveness, readiness и допуска работы;
- тест отсутствия успешной бизнес-операции до readiness.
Исключения¶
Не допускаются.
BE-HLTH-005. Состояние при завершении¶
Уровень: MUST
Применяется к: периоду штатного завершения процесса с проверками по
BE-HLTH-001
С начала процедуры завершения readiness должна быть неуспешной. Liveness должна оставаться успешной, пока процесс выполняет управляемое дренирование и не находится в состоянии, требующем принудительного перезапуска.
Readiness должна изменить состояние до прекращения допуска новой работы и
оставаться доступной в течение интервала, предусмотренного BE-SHUT-002.
Обоснование¶
Неготовность удаляет экземпляр из маршрутизации, а успешная liveness не прерывает дренирование преждевременным перезапуском.
Проверка¶
- integration-тест штатного завершения с выполняемой операцией;
- проверка последовательности readiness, прекращения маршрутизации и выхода;
- тест отсутствия рестарта по liveness во время дренирования.
Исключения¶
Не допускаются.
BE-HLTH-006. Ограниченность проверки¶
Уровень: MUST
Применяется к: выполнению liveness и readiness
Проверка не должна изменять бизнес-данные, публиковать сообщения или выполнять иную бизнес-операцию. Все обращения readiness к зависимостям должны иметь конечный timeout меньше timeout probe и выполняться с ограниченным параллелизмом.
Проверка не должна ждать свободного места в общей очереди запросов, если переполнение этой очереди препятствует выполнению самой проверки. Частота probe, timeout и порог неуспеха должны быть согласованы с допустимым временем обнаружения отказа и восстановления процесса.
Обоснование¶
Дешёвая и ограниченная проверка остаётся доступной при перегрузке и сама не создаёт дополнительный отказ.
Проверка¶
- нагрузочный тест проверок при насыщении основных пулов и очередей;
- измерение времени и числа обращений к зависимостям;
- review timeout, period и failure threshold probe.
Исключения¶
Readiness может читать локальное состояние, обновляемое отдельной ограниченной проверкой зависимости, если максимальная давность этого состояния меньше допустимого времени обнаружения отказа.
BE-HLTH-007. Изоляция и защита интерфейсов¶
Уровень: MUST
Применяется к: доступу и содержимому интерфейсов состояния
Интерфейсы состояния не должны требовать пользовательской аутентификации и не должны проходить через бизнес-авторизацию. Их сетевой доступ должен быть ограничен средой исполнения и уполномоченными средствами мониторинга.
Ответ не должен содержать секреты, персональные данные, строки подключения, адреса внутренних систем, stack trace или текст ошибки зависимости. Допустимы только заранее определённые низкокардинальные имена проверок и их состояния.
Обоснование¶
Probe должен работать независимо от пользовательской подсистемы безопасности, но не раскрывать внутреннюю топологию через публичный интерфейс.
Проверка¶
- security-тест доступа из разрешённой и запрещённой сети;
- проверка ответа при ошибках зависимостей;
- review исключения интерфейсов из бизнес-аутентификации и публичной маршрутизации.
Исключения¶
Дополнительная машинная аутентификация допускается для внешнего мониторинга, если probe среды исполнения сохраняет гарантированный доступ.
BE-HLTH-008. Наблюдаемость проверок¶
Уровень: MUST
Применяется к: логам, трассам и метрикам проверок состояния
Каждый успешный вызов проверки состояния не должен создавать диагностическую запись или событие ошибки. Неуспешный переход состояния должен регистрироваться один раз, а повторяющееся неизменное состояние должно ограничиваться по частоте.
Метрики должны позволять определить текущее состояние readiness и число переходов в неуспешное состояние. Проверки состояния должны быть исключены из пользовательских Service Level Indicator (SLI) запросов и распределённых трасс, если отдельное ограниченное диагностическое измерение не утверждено проектом.
Обоснование¶
Частые probe не должны искажать пользовательские показатели или создавать поток однотипной телеметрии.
Проверка¶
- нагрузочный вызов проверок и анализ логов, трасс и метрик;
- тест перехода и длительного неизменного неуспешного состояния;
- проверка запросов пользовательских SLI.
Исключения¶
Логирование отдельного успешного перехода состояния допускается как низкочастотное событие жизненного цикла.