Why the drain refuses new work first
Refusing new work bounds the drain. A drain that accepts work is a drain that can be endless.
The number that must be zero
Failed requests during a stop. Zero is the claim, and the claim needs a run under load.
Shutdown under load
A server is stopped while it is serving. The stop has to be visible to the client, invisible to the client is a request that fails without saying why.
What you will see
One line with zero. Zero under load is the claim that makes a stop graceful.
About 1 min of reading
Try It
Count failures across a stop
1
Write the run
printf 'requests 5000 stopped 2500 failed 12\n' > /tmp/r.txt; awk '{printf "%.2f\n", 100*$4/$2}' /tmp/r.txt
Before you run it, say out loud what it will print. Then open the answer.
What it prints
0.24. A quarter percent failed during the stop, which is not zero.
2
Find the cause
printf 'failed 12 cause=connection-closed\n' > /tmp/c.txt; cat /tmp/c.txt
Before you run it, say out loud what it will print. Then open the answer.
What it prints
One line. The cause names the window, and the window is the fix.
3
Write the claim
printf 'graceful stop failures=0 requests=5000 date=2026-10-10\n' > /tmp/g.txt; cat /tmp/g.txt
Before you run it, say out loud what it will print. Then open the answer.
What it prints
One line with zero. Zero under load is the claim that makes a stop graceful.
Data Flow
A stop to a failure count
1
The signal arrives while serving
↓
2
New requests are refused with a retryable answer
↓
3
In flight requests finish
↓
4
The failure count is read
Why this works
Examples
The client needs to know
A connection closed without a response is retryable. A connection closed after a response is not.
The window is small
Between the last request accepted and the process exiting. The window is where the ambiguity lives.
The restart is the test
Restart under load and count the failures. The count is the whole measure of a graceful stop.
← Streaming a large response
Previous Lesson
Streaming a large response