Graceful shutdown is a critical feature for modern web applications, ensuring a smoother user experience and preventing data loss during server restarts or deployments. Spring Boot supports graceful shutdown for embedded web servers, enhancing the reliability of your applications.
Diagram illustrating the Spring Boot graceful shutdown process, showing the server completing active requests before shutting down.
Understanding Graceful Shutdown in Spring Boot
Graceful shutdown allows a web application to complete processing existing requests before the server fully shuts down. This is in contrast to an abrupt shutdown, which can interrupt ongoing requests, leading to errors and a poor user experience. Spring Boot implements graceful shutdown as part of its application context closing process, specifically during the stopping phase of SmartLifecycle beans.
This process works by setting a timeout period, known as the grace period. During this time, the server will:
- Stop accepting new requests: The server will cease to accept new incoming connections, ensuring no new work is started.
- Allow existing requests to complete: The server continues to process requests that were already in progress when the shutdown signal was received.
- Shutdown after grace period or completion: Once all active requests are completed, or the grace period timeout is reached, the server proceeds with the complete shutdown process, releasing resources and terminating the application.
The method of preventing new requests varies slightly depending on the embedded web server you are using with Spring Boot:
- Jetty, Reactor Netty, and Tomcat: These servers stop accepting new requests at the network layer itself. This means new connection attempts will be refused immediately.
- Undertow: Undertow, on the other hand, continues to accept new requests at the network level, but it immediately responds to them with a “Service Unavailable” (HTTP 503) error. This informs clients that the server is going down and cannot handle new requests.
Version Requirement for Tomcat
If you are using Tomcat as your embedded web server, it’s important to note the version requirement for graceful shutdown. Graceful shutdown with Tomcat requires Tomcat version 9.0.33 or later. Ensure your spring-boot-starter-tomcat dependency in your pom.xml or build.gradle is of a compatible version.
Configuring Graceful Shutdown in Spring Boot
Enabling graceful shutdown in Spring Boot is straightforward and involves minimal configuration. You need to set the following properties in your application.properties or application.yml file:
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s # Optional: Configures timeout, default is 30sserver.shutdown=graceful: This line is the primary switch to enable the graceful shutdown feature.spring.lifecycle.timeout-per-shutdown-phase: This is an optional setting that defines the timeout duration for the graceful shutdown period. The default value is 30 seconds. You can adjust this value based on the expected processing time of your longest-running requests. If your requests typically complete quickly, you can reduce this timeout. For longer-running tasks, you might need to increase it.
Important Note on SIGTERM Signal
Spring Boot’s graceful shutdown mechanism is triggered by the SIGTERM signal. SIGTERM is a standard signal in Linux-based systems used to request the termination of a process gracefully. It gives the application time to clean up and exit properly. In contrast, SIGKILL is a signal that immediately terminates a process without allowing for cleanup.
It’s important to be aware that using graceful shutdown within your IDE might not always behave as expected, particularly if your IDE doesn’t send a proper SIGTERM signal when stopping the application. Consult your IDE’s documentation for details on how it handles application termination signals. In production environments, deployments typically use SIGTERM for initiating shutdowns, making graceful shutdown effective.
Verifying Graceful Shutdown
To verify that graceful shutdown is working correctly, you can set up a simple test scenario. Consider the following Spring Boot controller example:
@Slf4j
@RestController
public class TestController {
@RequestMapping("/activeRequest")
public void activeRequest() throws InterruptedException {
log.info("【Request processing started】");
/**
* spring.lifecycle.timeout-per-shutdown-phase=30s
* Configured to wait for 30 seconds, so if the web service is stopped within 10 seconds after executing this method, it will still wait for the method to complete.
*/
Thread.sleep(10000); // Simulate a 10-second processing time
log.info("【Request processing finished】");
}
}This controller endpoint /activeRequest simulates a request that takes 10 seconds to process.
Scenario 1: Graceful Shutdown with Sufficient Timeout
- Configure
server.shutdown=gracefulandspring.lifecycle.timeout-per-shutdown-phase=30s. - Start your Spring Boot application.
- Send a request to
/activeRequest. - While the request is processing (within the 10-second sleep period), initiate a shutdown of your Spring Boot application (e.g., stop the Spring Boot run configuration in your IDE or send a
SIGTERMsignal to the running process).
In the logs, you should observe the following:
2023-03-18 10:31:41.582 INFO [nio-8080-exec-1] c.w.controller.安全关闭WEB服务.TestController : 【Request processing started】
... (Shutdown initiated here) ...
2023-03-18 10:31:45.158 INFO [extShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
2023-03-18 10:31:51.593 INFO [nio-8080-exec-1] c.w.controller.安全关闭WEB服务.TestController : 【Request processing finished】
2023-03-18 10:31:51.656 INFO [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown : Graceful shutdown complete
... (Application shutdown continues) ...This log output confirms that upon receiving the shutdown signal, Spring Boot initiated the graceful shutdown process (Commencing graceful shutdown. Waiting for active requests to complete). It waited for the active request to /activeRequest to finish processing (【Request processing finished】) before completing the server shutdown (Graceful shutdown complete).
Scenario 2: Graceful Shutdown with Insufficient Timeout
- Configure
server.shutdown=gracefulandspring.lifecycle.timeout-per-shutdown-phase=10s. - Modify the
/activeRequestendpoint to sleep for 20 seconds (Thread.sleep(20000);). - Repeat steps 2-4 from Scenario 1.
In this case, with a 10-second timeout and a 20-second request, the graceful shutdown will be aborted after the timeout. The logs will show:
2023-03-18 10:57:16.020 INFO [nio-8080-exec-1] c.w.controller.安全关闭WEB服务.TestController : 【Request processing started】
... (Shutdown initiated here) ...
2023-03-18 10:57:17.471 INFO [extShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
2023-03-18 10:57:27.478 INFO [extShutdownHook] o.s.c.support.DefaultLifecycleProcessor : Failed to shut down 1 bean with phase value 2147483647 within timeout of 10000ms: [webServerGracefulShutdown]
2023-03-18 10:57:27.510 INFO [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown : Graceful shutdown aborted with one or more requests still active
... (Application shutdown continues) ...The log Graceful shutdown aborted with one or more requests still active indicates that the timeout was reached before the /activeRequest completed. The server proceeded with shutdown, potentially interrupting the ongoing request.
Scenario 3: Shutdown without Graceful Shutdown Enabled
- Remove or comment out
server.shutdown=gracefulfrom your configuration. - Use the original 10-second sleep in
/activeRequest(Thread.sleep(10000);). - Repeat steps 2-4 from Scenario 1.
Without graceful shutdown enabled, there will be no waiting period for active requests. The server will shut down immediately upon receiving the shutdown signal, potentially interrupting the /activeRequest and without any “graceful shutdown” messages in the logs.
Undertow vs. Tomcat: Handling New Requests During Shutdown
As mentioned earlier, there’s a subtle difference in how Undertow and Tomcat handle new requests during the graceful shutdown period:
Undertow Behavior:
Undertow server behavior during graceful shutdown, responding with 503 Service Unavailable to new requests.
Undertow accepts new requests but immediately rejects them with a 503 “Service Unavailable” response. This is a clear signal to clients that the server is going down and cannot handle new work.
Tomcat Behavior:
Tomcat server behavior during graceful shutdown, blocking new requests at the network layer.
Tomcat, Jetty, and Reactor Netty, in contrast, stop accepting new requests at the network layer. New connection attempts will be refused, preventing any new requests from even reaching the application.
Both approaches effectively prevent new work from starting during shutdown, but Undertow’s 503 response provides explicit feedback to clients.
Conclusion
Spring Boot’s graceful shutdown feature is an essential tool for building robust and user-friendly web applications. By ensuring that ongoing requests are completed before server termination, you can avoid interrupted operations, minimize errors, and improve the overall reliability of your applications. Properly configuring and understanding graceful shutdown, including timeout settings and server-specific behaviors, is crucial for ensuring a smooth shutdown process in your Spring Boot deployments.
