24 KiB
graceful-shutdown Specification
Purpose
Как сервис останавливается по SIGTERM: перестаёт принимать новые запросы, дорабатывает текущие и завершается за заявленный срок, до того как Docker применит SIGKILL.
Requirements
Requirement: Новые запросы после SIGTERM не принимаются
После получения SIGTERM сервис SHALL прекращать принимать новые соединения и MUST NOT начинать обработку новых запросов на уже открытых простаивающих соединениях.
Scenario: Нагрузка во время остановки
- WHEN во время непрерывной отправки сообщений контейнеру отправлен SIGTERM
- THEN запросы, начатые после сигнала, завершаются ошибкой соединения, а не ответом сервиса
Requirement: Текущие запросы дорабатывают
Запросы, начатые до SIGTERM, SHALL получать ответ, если укладываются в
срок [app] graceful_shutdown_seconds. Запросы, которые не уложились,
SHALL отменяться, чтобы процесс всё равно завершился.
Scenario: Запрос в полёте
- WHEN SIGTERM приходит, пока сервис обрабатывает запрос
- THEN клиент получает ответ на этот запрос, после чего процесс завершается
Requirement: Завершение за заявленный срок
Процесс SHALL завершаться после SIGTERM не дольше чем за
[app] graceful_shutdown_seconds плюс время shutdown в lifespan. Это
значение MUST быть не больше 9 с: Docker применяет SIGKILL через 10 с.
Код выхода MUST NOT быть 137 (SIGKILL).
Scenario: docker stop
- WHEN выполняется
docker stopдля работающего контейнера - THEN команда завершается быстрее 10 с, а код выхода контейнера не равен 137
Requirement: Остановка видна в журнале
Этапы остановки SHALL записываться в журнал сервиса JSON-записями с временем: начало остановки, завершение lifespan, завершение процесса. По меткам времени SHALL определяться длительность остановки.
Scenario: Журнал остановки
- WHEN контейнер остановлен по SIGTERM
- THEN в журнале по порядку есть «Shutting down», «Stopped API» и
«Finished server process», и разница их
timestampменьше 10 с
Requirement: Остановка реплики за балансировщиком
Реплика API за балансировщиком (LB) после SIGTERM SHALL сразу
перестать принимать соединения и дорабатывать начатые запросы
(требования выше). Новое соединение с ней LB SHALL получать как отказ
соединения и передавать такой запрос другой реплике. Поэтому штатная
остановка одной реплики из двух (docker stop) под постоянной
нагрузкой через LB MUST NOT давать клиенту ошибок от недоступности
реплики. На время обнаружения отказа допустим рост задержки.
Единственное исключение — запрос, который LB отправил в простаивающее keep-alive соединение в тот момент, когда реплика закрывает его при остановке. Ответа на него нет, LB отвечает 502 и не повторяет его. Такие ошибки SHALL учитываться. Доля успешных ответов в каждой секунде фазы MUST NOT опускаться ниже 99 %.
Scenario: docker stop под нагрузкой
- WHEN через LB с постоянной интенсивностью идут запись с ключом и
чтение истории, и одна из двух реплик остановлена
docker stop - THEN доля успешных ответов в каждой секунде фазы не ниже 99 %, время восстановления 0 с, а неуспешные ответы, если есть, — одиночные 502 в момент SIGTERM; так для остановки каждой из реплик по очереди
Scenario: Клиент с новым соединением на запрос
- WHEN клиент открывает новое соединение на каждый запрос, как
публичная проверка
make test-failover, и реплика остановленаdocker stop - THEN клиент не получает ни одной ошибки: его запрос не идёт в простаивающее соединение с репликой
Requirement: Простаивающие соединения закрывает балансировщик
Реплика SHALL держать простаивающее keep-alive соединение дольше, чем
LB держит простаивающее соединение с ней. Тогда простаивающее
соединение LB → реплика закрывает LB, и он не отправляет запрос в
соединение, которое реплика в этот момент закрывает. Срок простоя на
стороне реплики SHALL задаваться настройкой [app] keep_alive_seconds. LB MUST NOT держать простаивающие соединения с
репликой дольше своего срока простоя клиентского соединения.
Scenario: Клиенты молчат после всплеска
- WHEN через LB прошёл всплеск запросов от клиентов с keep-alive, а затем клиенты остаются подключены и молчат
- THEN соединения на порт API внутри каждой реплики закрываются
раньше
keep_alive_secondsс момента последнего запроса, по сроку простоя LB
Requirement: Плановая остановка реплики без ошибок
При плановой остановке реплики за балансировщиком (поочерёдная замена,
load-balancing) реплика SHALL сначала выводиться из LB. Только когда
у неё не осталось запросов в полёте, она получает SIGTERM. Поэтому
плановая остановка под постоянной нагрузкой MUST NOT давать клиенту ни
одной ошибки, включая 502 гонки keep-alive из требования «Остановка
реплики за балансировщиком».
Поведение процесса по SIGTERM не меняется: требования выше действуют. Не
меняется и остановка без дренажа (scripts/stop-one.sh, docker stop): она имитирует отказ, и исключение для 502 гонки keep-alive к
ней по-прежнему применяется.
Scenario: Остановка после дренажа под нагрузкой
- WHEN через LB с постоянной интенсивностью идут запись с ключом и чтение истории, и реплика остановлена после вывода из LB
- THEN ни одного неуспешного ответа, в том числе 502, а журнал LB не показывает ошибок соединения с этой репликой
Scenario: Остановка за заявленный срок после дренажа
- WHEN реплика выведена из LB и получила SIGTERM
- THEN процесс завершается быстрее 10 с с кодом выхода не 137, а в её журнале есть «Shutting down», «Stopped API» и «Finished server process»
Requirement: Остановка во время старта
SIGTERM и SIGINT, пришедшие процессу сервиса во время старта, SHALL его останавливать, а не теряться. Это действует и в контейнере, где сервер — процесс с PID 1, и в консоли. Действует с первых строк точки входа, ещё до импорта приложения.
- Пока сервер не установил свои обработчики сигналов и не начал
принимать соединения, запросов у процесса нет. Процесс SHALL
завершаться сразу, без ожидания, с кодом выхода 0. Перед выходом он
SHALL записывать в журнал одну JSON-запись уровня
infoсevent«Stopped API before startup» и именем сигнала в полеsignal. Запись SHALL содержатьtimestamp,levelиinstance_id, как все записи журнала (service-logging). - Сигнал, пришедший после того, как сервер установил свои обработчики, но до конца старта, SHALL вести к штатной остановке сразу после старта. В журнале SHALL быть «Shutting down», «Stopped API» и «Finished server process», код выхода — 0.
docker stopстартующего контейнера SHALL завершаться не дольше чем за 1 с, а не по сроку Docker с SIGKILL.
Запуск интерпретатора до первых строк точки входа — первые десятки миллисекунд жизни процесса — это требование не покрывает. Остановка уже работающего процесса не меняется: требования выше действуют.
Scenario: docker stop во время импорта приложения
- WHEN контейнер API остановлен
docker stopв первые 0,5 с после старта, пока процесс ещё импортирует приложение (на стенде лабы запись «Started server process» появляется через ~0,7 с после старта) - THEN
docker stopзавершается не дольше чем за 1 с, код выхода контейнера 0, в журнале есть запись «Stopped API before startup» сsignalSIGTERM, а записей сервера о старте нет
Scenario: Сигнал во время старта сервера
- WHEN SIGTERM приходит после записи «Started server process» и до записи «Uvicorn running on»
- THEN в журнале после старта идут «Shutting down», «Stopped API» и
«Finished server process»,
docker stopзавершается не дольше чем за 1 с, а код выхода 0
Scenario: Ctrl+C в консоли во время старта
- WHEN сервер, запущенный в консоли (
make run_devилиpython -m src), получает SIGINT, пока импортирует приложение - THEN процесс завершается сразу с кодом 0 и той же записью «Stopped
API before startup» с
signalSIGINT, без traceback
Scenario: Работающий процесс останавливается как раньше
- WHEN
docker stopвыполняется для контейнера, сервер которого уже записал «Uvicorn running on» - THEN в журнале «Shutting down», «Stopped API» и «Finished server process», записи «Stopped API before startup» нет, код выхода 0, а запросы в полёте получают ответ
Requirement: Остановка уборщика
По SIGTERM уборщик незавершённых загрузок (capability
storage-consistency) SHALL довести текущий шаг уборки загрузки до
конца или до отката и больше новых шагов не начинать. Загрузка,
остановленная между шагами, остаётся в состоянии, из которого её
доводит следующий проход.
Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с
PostgreSQL доводится до конца или до отката. Новые страницы списка и
новые действия не начинаются. Ожидание из-за предела скорости сверки
(capability storage-consistency, «Скорость сверки») сигнал прерывает
сразу: остановка не ждёт конца паузы. Сверку, прерванную сигналом,
доводит следующий проход, как прерванную отказом.
Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время старта процесса SHALL завершать его с кодом 0 без traceback, как у API (требование «Остановка во время старта»). Остановка SHALL быть видна в журнале записью об остановке уборщика.
Scenario: docker stop уборщика
- WHEN выполняется
docker compose stop cleanerдля работающего уборщика - THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись об остановке
Scenario: docker stop во время сверки
- WHEN
docker compose stop cleanerвыполняется, пока идёт проход сверки, а вызов S3 в нём ждёт ответа - THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале — итог сверки с причиной прерывания «остановка» и запись об остановке уборщика
Scenario: docker stop во время паузы предела скорости
- WHEN
docker stopвыполняется для разового прохода сверки, пока тот ждёт из-за предела скорости - THEN контейнер останавливается не позже чем через секунду после сигнала, код выхода 1, а в журнале — итог сверки с причиной прерывания «остановка» и запись об остановке уборщика
Requirement: Остановка worker
По SIGTERM worker (capability attachment-processing) SHALL перестать принимать
новые сообщения и дать начатым заданиям завершиться, но не дольше [worker] graceful_shutdown_seconds. Задание, которое не успело, SHALL оставаться
неподтверждённым: брокер доставит его снова (attachment-processing, «Доставка at
least once»), а его процесс обработки SHALL быть убит. Затем worker SHALL выйти с кодом 0
раньше срока остановки контейнера (10 с), а не по SIGKILL, в том числе если декодирование
ещё идёт.
Значение graceful_shutdown_seconds MUST быть не больше 8: вместе с закрытием клиентов
остановка в худшем случае укладывается в 9,5 с. Сигнал во время старта процесса SHALL
завершать его с кодом 0 без traceback, как у API (требование «Остановка во время старта»).
Остановка SHALL быть видна в журнале записью об остановке worker.
Ограничение называется в REPORT.md. Задание, прерванное остановкой, считается начатой
попыткой: следующую она получит, когда истечёт срок её аренды.
Scenario: docker stop простаивающего worker
- WHEN выполняется
docker compose stop workerдля worker без заданий - THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись об остановке
Scenario: docker stop во время обработки
- WHEN
docker compose stop workerвыполняется, пока фиксация результата задания задержана дольше срока остановки worker - THEN команда завершается быстрее 10 с, код выхода контейнера 0, сообщение
задания снова в очереди, а после запуска worker вложение становится
ready
Scenario: docker stop во время декодирования
- WHEN
docker compose stop workerвыполняется, пока идёт декодирование дольше срока остановки worker - THEN команда завершается быстрее 10 с, код выхода контейнера 0, процесса обработки не осталось, а задание получает следующую попытку после запуска worker
Scenario: docker stop во время старта worker
- WHEN контейнер worker остановлен в первые доли секунды после старта, пока процесс ещё импортирует приложение
- THEN
docker stopзавершается не дольше чем за 1 с, код выхода контейнера 0, а в журнале есть запись об остановке worker до старта
Requirement: Остановка relay
По SIGTERM relay (capability job-outbox) SHALL довести текущий проход до фиксации или
отката и выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. Новые
проходы не начинаются, а паузу между проходами сигнал прерывает сразу. Незаписанное время
подтверждения ничего не теряет: следующий запуск опубликует задание снова. Сигнал во время
старта процесса SHALL завершать его с кодом 0 без traceback. Остановка SHALL быть видна в
журнале.
Scenario: docker stop relay
- WHEN выполняется
docker compose stop relay, в том числе при замороженном брокере - THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись об остановке relay
Scenario: docker stop во время старта relay
- WHEN контейнер relay остановлен в первые доли секунды после старта
- THEN
docker stopзавершается не дольше чем за 1 с, код выхода контейнера 0, а в журнале есть запись об остановке relay до старта
Requirement: Остановка при недоступном Collector
С включённой телеметрией (capability observability) реплика API, worker и relay SHALL останавливаться по SIGTERM в
прежние сроки: API — требования «Завершение за заявленный срок» и «Остановка видна в журнале», worker — «Остановка worker»,
relay — «Остановка relay», в том числе когда Collector остановлен или заморожен. Отправка накопленной телеметрии при
остановке SHALL ограничиваться своим сроком внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать
Collector дольше. Запись об остановке процесса SHALL быть в stdout при любом состоянии Collector.
Срок отправки при остановке SHALL входить в тот же бюджет, а не прибавляться к нему: у API с включённой телеметрией
[app] graceful_shutdown_seconds вместе со сроком закрытия SDK MUST NOT превышать 9 с (требование «Завершение за заявленный
срок»), иначе запуск SHALL останавливаться ошибкой проверки настроек с именем поля app.graceful_shutdown_seconds; без
телеметрии допустимы прежние 9 с. У worker и relay закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай
остаётся прежним (требования «Остановка worker» и «Остановка relay»).
Scenario: docker stop при остановленном Collector
- WHEN Collector остановлен, реплика API только что обслуживала запросы, relay только что опубликовал задание, и
выполняется
docker stopэтой реплики, а затемdocker compose stop workerиdocker compose stop relay - THEN все три команды завершаются быстрее 10 с, коды выхода контейнеров 0, а в stdout есть «Stopped API», «Stopped worker» и «Stopped relay»
Scenario: docker stop при замороженном Collector
- WHEN контейнер Collector заморожен (
docker pause), и выполняются те же остановки - THEN все три команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке
Scenario: Срок остановки API не оставляет места закрытию SDK
- WHEN API запускается с включённой телеметрией и
APP__GRACEFUL_SHUTDOWN_SECONDS=9 - THEN запуск останавливается ошибкой проверки настроек, которая называет поле
app.graceful_shutdown_secondsи допустимый предел, а с выключенной телеметрией то же значение принимается