Spring Boot의 Graceful Shutdown 어디까지 알고있나요? (SmartLifeCycle, Phased 와 함께 timeout-per-shutdown-phase 오해 바로잡기)

이 글에서는 Graceful Shutdown을 "우아한 종료"로 언급합니다.

1. 우아한 종료 테스트 환경 설정

우아한 종료 테스트는 IDE에서 실행 시 원활하게 동작하지 않는다고 설명되어 있어, Linux 서버에서 jar를 수동으로 종료하며 테스트를 진행했습니다.

Using graceful shutdown with your IDE may not work properly if it does not send a proper SIGTERM signal. See the documentation of your IDE for more details.

1.1 application.yml 설정

application.yml에 우아한 종료를 설정하였습니다. 스프링 부트 3.4부터는 우아한 종료가 기본으로 설정되며, timeout-per-shutdown-phase는 30초입니다.

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 10s

1.2 비동기 쓰레드 풀 설정

그리고 애플리케이션에 오래 걸리는 작업(80초)을 비동기 처리 하기 위해 쓰레드 풀을 간단하게 설정한다고 가정했습니다.

@Configuration
public class AsyncConfig {

    @Bean
    public TaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(1);

        taskExecutor.initialize();

        return taskExecutor;
    }
}

! 참고

위처럼 큐 사이즈를 제한하지 않으면, ThreadPoolTaskExecutor의 initializeExecutor, createQueue를 통해 SynchronousQueue가 생성됩니다.

SynchronousQueue 는 작업이 큐에 적재되지 않고, 작업을 제출한 쓰레드는 작업을 소비할 쓰레드가 있을 때까지 대기합니다.

2. 첫 번째 문제: 우아한 종료는 비동기 작업을 기다려줄까?

2.1 실험 코드

이 상황에서 아래 코드처럼 쓰레드 풀에 80초가 걸리는 비동기 작업을 제출하고 애플리케이션을 종료해봅니다. (jar로 실행했습니다)

public class TestController {

    private final TaskExecutor taskExecutor;

    @GetMapping("/tasks")
    public String test() throws InterruptedException {
        log.info("비동기 작업 제출 (80초 소요 예상)...");
        taskExecutor.execute(() -> {
            try {
                for (int i = 1; i <= 80; i++) {
                    Thread.sleep(1000);
                    log.info("비동기 작업 진행 중: {}초 경과", i);
                }
                log.info("비동기 작업 완료!");
            } catch (InterruptedException e) {
                log.warn("비동기 작업이 강제 종료(Interrupted) 되었습니다!");
            }
        });

        return "작업이 제출되었습니다. 이제 서버를 종료(Ctrl+C)하여 로그를 확인하세요.";
    }
}

2.2 결과는 무엇일까?

결과는 무엇일까요?

톰캣 쓰레드 풀에 우아한 종료가 적용되더라도 모든 비동기 작업이 제출되어 `log.info("비동기 작업 진행 중: {}초 경과", i);`의 로그가 80번 다 찍힌 후에 종료된다.
아니다. 우아한 종료가 비동기 작업을 10초만 기다리고 애플리케이션이 종료된다. `log.info("비동기 작업 진행 중: {}초 경과", i);`의 로그가 1번보다 무조건 덜 찍힌다.

정답은 2번입니다.

2.3 로그 분석

전체 로그입니다.

2026-01-23T09:50:51.460  INFO [nio-8080-exec-1] p.shutdown.config.TestController         : 비동기 작업 제출 (80초 소요 예상)...
2026-01-23T09:50:52.461  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 1초 경과
2026-01-23T09:50:57.239 DEBUG [ionShutdownHook] o.s.b.a.ApplicationAvailabilityBean      : Application availability state ReadinessState changed from ACCEPTING_TRAFFIC to REFUSING_TRAFFIC
2026-01-23T11:46:13.097 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147482623
2026-01-23T11:46:13.099  INFO [ionShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown        : Commencing graceful shutdown. Waiting for active requests to complete
2026-01-23T11:46:13.108  INFO [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown        : Graceful shutdown complete
2026-01-23T11:46:13.109 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147481599
2026-01-23T11:46:13.109 DEBUG [tomcat-shutdown] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerGracefulShutdown' completed its stop procedure
2026-01-23T11:46:13.111 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerStartStop' completed its stop procedure
2026-01-23T11:46:13.112 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 1073741823
2026-01-23T11:46:13.646  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 2초 경과
2026-01-23T11:46:14.646  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 3초 경과
...
2026-01-23T11:46:21.650  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 10초 경과
2026-01-23T11:46:22.650  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 11초 경과
2026-01-23T11:46:23.118  INFO [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Shutdown phase 1073741823 ends with 1 bean still running after timeout of 10000ms: [taskExecutor1]
2026-01-23T11:46:23.119 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase -2147483647
2026-01-23T11:46:23.119 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'springBootLoggingLifecycle' completed its stop procedure
2026-01-23T11:46:23.120 DEBUG [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Shutting down ExecutorService 'taskExecutor1'
2026-01-23T11:46:23.121  WARN [       Async1-1] p.shutdown.config.TestController         : 비동기 작업이 강제 종료(Interrupted) 되었습니다!
2026-01-23T11:46:23.121 DEBUG [       Async1-1] o.s.c.support.DefaultLifecycleProcessor  : Bean 'taskExecutor1' completed its stop procedure

로그를 잘 보면 애플리케이션을 ACCEPTING_TRAFFIC 상태에서 REFUSING_TRAFFIC 상태로 변경한 후에 2147482623이라는 phase에 있는 빈을 Stopping하기 시작합니다.

2147482623 값은 Integer.MAX_VALUE인데, 나중에 Phased 인터페이스를 설명할 때 다시 나오니 기억해두시기 바랍니다.

2026-01-23T09:50:57.239 DEBUG [ionShutdownHook] o.s.b.a.ApplicationAvailabilityBean      : Application availability state ReadinessState changed from ACCEPTING_TRAFFIC to REFUSING_TRAFFIC
2026-01-23T11:46:13.097 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147482623
2026-01-23T11:46:13.099  INFO [ionShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown        : Commencing graceful shutdown. Waiting for active requests to complete
2026-01-23T11:46:13.108  INFO [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown        : Graceful shutdown complete

그 후에 'Stopping beans in phase {Integer 값}' 순으로 로그가 찍히는 것을 볼 수 있습니다.

여기서, phase 란 로그는 timeout-per-shutdown-phase 의 phase 를 의미합니다.

2026-01-23T11:46:13.109 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147481599
2026-01-23T11:46:13.109 DEBUG [tomcat-shutdown] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerGracefulShutdown' completed its stop procedure
2026-01-23T11:46:13.111 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerStartStop' completed its stop procedure
2026-01-23T11:46:13.112 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 1073741823
2026-01-23T11:46:23.118  INFO [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Shutdown phase 1073741823 ends with 1 bean still running after timeout of 10000ms: [taskExecutor1]
2026-01-23T11:46:23.119 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase -2147483647
2026-01-23T11:46:23.119 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'springBootLoggingLifecycle' completed its stop procedure

2.4 timeout-per-shutdown-phase의 진짜 의미

그래서, 아래 설정 값은 사실 phase 숫자 값이 다른 빈들을 종료할 때마다 최대 10초를 기다리는 것이지, 이 시간 안에 애플리케이션의 종료가 완료되기까지 기다리는 것이 아닙니다.

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 10s

단지 애플리케이션을 종료할 때 phase가 높은 순에서 낮은 순으로 내림차순 정렬한 후, 각 phase 그룹을 종료하게 되는데, 내장된 웹서버(톰캣, 네티) 관련 빈들의 phase 값이 가장 높기 때문에 가장 먼저 종료되어 새로운 요청을 받아들이지 않게 되는 것뿐입니다.

2.5 Phase 별 종료 메커니즘

예를 들어, 빈 A와 B가 phase 1000이라는 값을 가지고, 빈 C, D, E가 phase 999라는 값을 가질 때 (빈은 같은 phase 값을 가질 수 있습니다), DefaultLifecycleProcessor(애플리케이션의 빈들을 phase 단위로 종료하는 객체)는 phase 1000을 가진 빈들을 정리할 때 각 빈들이 사용하는 또 다른 빈들을 재귀적으로 찾으며 관련 빈들을 모두 정리합니다. (이는 내부적으로 doStop()을 재귀적으로 호출합니다). 이 과정을 phase 값 별로 최대 10초까지 기다린다는 것입니다.

그래서 최대 10초를 기다린 후에는 다음 phase 값을 가진 999 phase 를 종료하기 시작합니다.

그래서 1073741823 빈인 쓰레드 풀을 종료할 때, 작업이 10초 이상 걸리게 되니 timeout-per-shutdown-phase 10초를 넘기게 되어 해당 phase는 타임아웃 되었다는 로그와 함께 다음 phase로 넘어가게 되는 것입니다.

2026-01-23T11:46:13.112 DEBUG [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 1073741823
2026-01-23T11:46:13.646  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 2초 경과
2026-01-23T11:46:14.646  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 3초 경과
...
2026-01-23T11:46:21.650  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 10초 경과
2026-01-23T11:46:22.650  INFO [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 11초 경과
2026-01-23T11:46:23.118  INFO [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Shutdown phase 1073741823 ends with 1 bean still running after timeout of 10000ms: [taskExecutor1]

3. 두 번째 문제: 쓰레드 풀에 우아한 종료를 추가하면?

3.1 쓰레드 풀 우아한 종료 설정

다음 2번째 문제입니다.

그럼 비동기 쓰레드 풀에 우아한 종료를 추가하고, 애플리케이션을 종료해봅시다.

@Configuration
public class AsyncConfig {

    @Bean
    public TaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(1);

        // 추가!
        taskExecutor.setWaitForTasksToCompleteOnShutdown(true);
        taskExecutor.setAwaitTerminationSeconds(30);

        taskExecutor.initialize();

        return taskExecutor;
    }
}

3.2 결과는 어떻게 될까?

결과는 어떻게 될까요?

톰캣 쓰레드 풀의 우아한 종료 시간을 10초로 설정했기 때문에 비동기 쓰레드 풀에 적용한 30초는 적용되지 않고 애플리케이션은 10초만 기다리고 종료된다!
톰캣 쓰레드 풀의 우아한 종료 시간 10초와 비동기 쓰레드 풀에 적용한 30초가 더해져 총 40초 동안 우아한 종료를 기다리고 종료된다!
톰캣 쓰레드 풀의 우아한 종료 시간 따로, 쓰레드 풀 우아한 종료가 따로 적용되어 비동기 작업을 30초 동안 기다리고 종료된다!

정답은 3번 입니다.

3.3 왜 이렇게 동작할까?

아래는 전체 로그입니다.

2026-01-22T21:02:43 INFO --- [nio-8080-exec-1] p.shutdown.config.TestController         : 비동기 작업 제출 (80초 소요 예상)...
2026-01-22T21:02:44 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 1초 경과
2026-01-22T21:02:44 INFO --- [ionShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown        : Commencing graceful shutdown. Waiting for active requests to complete
2026-01-22T21:02:45 INFO --- [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown        : Graceful shutdown complete
2026-01-22T21:02:45 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 2초 경과
2026-01-22T21:02:46 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 3초 경과
...
2026-01-22T21:03:12 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 29초 경과
2026-01-22T21:03:13 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 30초 경과
2026-01-22T21:03:14 INFO --- [ taskExecutor-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 31초 경과
2026-01-22T21:03:15 WARN --- [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Timed out while waiting for executor 'taskExecutor' to terminate

왜 이런지 timeout-per-shutdown-phase의 의미를 잘 생각해봅시다.

timeout-per-shutdown-phase는 phase 간의 타임아웃을 지정할 뿐이지, 다른 쓰레드 풀의 우아한 종료가 설정되어 있으면 간섭하지 않습니다.

즉, 비동기를 위한 쓰레드 풀에 우아한 종료를 설정하게 되면 애플리케이션은 종료할 때 "그래, 너 우아한 종료 설정되어 있으니 너 시간만큼 기다리도록 해"라고 하고 다음 phase를 바로 종료하러 가고, 비동기를 위한 쓰레드 풀은 그 풀 자체로 우아한 종료로 설정한 타임아웃 시간만큼 작업을 수행하게 됩니다.

그러다가 그 시간까지 비동기 쓰레드 풀이 작업을 종료하지 못하면 마지막 로그(Timed out while waiting for...)처럼 "해당 쓰레드 풀을 종료하는데 타임아웃이 떴어요. 작업이 완료될 수도 있고, 안될 수도 있어요."라고 WARN 로그 레벨을 남기며 종료하게 됩니다.

4. 세 번째 문제: 여러 쓰레드 풀의 우아한 종료

4.1 복수 쓰레드 풀 설정

다음 마지막 문제입니다.

외부 연동 서비스 A와 B 간의 장애를 격리하기 위해 쓰레드 풀 2개를 사용해 각 연동 서비스를 호출하는 상황을 가정했습니다.(일종의 벌크헤더 패턴입니다).

쓰레드 풀 1번의 우아한 종료 시간은 30초, 쓰레드 풀 2번은 15초입니다.

@Configuration
public class AsyncConfig {

    @Bean
    public TaskExecutor taskExecutor1() {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(1);
        taskExecutor.setWaitForTasksToCompleteOnShutdown(true);
        taskExecutor.setAwaitTerminationSeconds(30);

        taskExecutor.setThreadNamePrefix("Async1-");

        taskExecutor.initialize();

        return taskExecutor;
    }

    @Bean
    public TaskExecutor taskExecutor2() {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(1);
        taskExecutor.setWaitForTasksToCompleteOnShutdown(true);
        taskExecutor.setAwaitTerminationSeconds(15);

        taskExecutor.setThreadNamePrefix("Async2-");
        
        taskExecutor.initialize();

        return taskExecutor;
    }
}

API 엔드포인트도 2개가 생겼습니다.

@RestController
@RequiredArgsConstructor
public class TestController {

    private final TaskExecutor taskExecutor1;
    private final TaskExecutor taskExecutor2;


    @GetMapping("/tasks-1")
    public String test() throws InterruptedException {
        ThreadPoolExecutor taskExecutor = (ThreadPoolExecutor) taskExecutor1;
        log.info("비동기 작업 제출 (80초 소요 예상)...");
        taskExecutor.submit(() -> {
            try {
                for (int i = 1; i <= 80; i++) {
                    Thread.sleep(1000); // 1초씩 30번 대기
                    log.info("비동기 작업 진행 중: {}초 경과", i);
                }
                log.info("비동기 작업 완료!");
            } catch (InterruptedException e) {
                log.warn("비동기 작업이 강제 종료(Interrupted) 되었습니다!");
            }
        });

        return "작업이 제출되었습니다. 이제 서버를 종료(Ctrl+C)하여 로그를 확인하세요.";
    }

    @GetMapping("/tasks-2")
    public String test2() throws InterruptedException {
        ThreadPoolExecutor taskExecutor = (ThreadPoolExecutor) taskExecutor2;
        log.info("비동기 작업 제출 (30초 소요 예상)...");
        taskExecutor.submit(() -> {
            try {
                for (int i = 1; i <= 30; i++) {
                    Thread.sleep(1000); // 1초씩 30번 대기
                    log.info("비동기 작업 진행 중: {}초 경과", i);
                }
                log.info("비동기 작업 완료!");
            } catch (InterruptedException e) {
                log.warn("비동기 작업이 강제 종료(Interrupted) 되었습니다!");
            }
        });

        return "작업이 제출되었습니다. 이제 서버를 종료(Ctrl+C)하여 로그를 확인하세요.";
    }
}

요약하자면 다음과 같습니다.

- 애플리케이션 전역 설정: timeout-per-shutdown-phase 10초

- 비동기 쓰레드 풀 1번: 작업 기다리기 까지 30초, 실제 작업 소요 시간 80초

- 비동기 쓰레드 풀 2번: 작업 기다리기 까지 15초, 실제 작업 소요 시간 30초

4.2 결과는?

결과가 어떻게 될까요?

비동기 쓰레드 풀 2번은 WARN 레벨의 경고 타임아웃이 발생했다는 로그와 함께 작업이 완료되었다는 로그가 나왔습니다.

비동기 쓰레드 풀 1번은 30초 이후에 WARN 레벨의 경고 타임아웃이 발생했다는 로그만 나오고, 작업이 완료되지 않고 애플리케이션이 종료되었습니다.

아래는 전체 로그입니다.

026-01-22T21:26:57.619+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 1초 경과
2026-01-22T21:26:57.724+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 2초 경과
2026-01-22T21:26:57.750+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.b.a.ApplicationAvailabilityBean      : Application availability state ReadinessState changed from ACCEPTING_TRAFFIC to REFUSING_TRAFFIC
2026-01-22T21:26:57.751+09:00 DEBUG 60684 --- [ionShutdownHook] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@62452cc9, started on Thu Jan 22 21:26:53 KST 2026
2026-01-22T21:26:57.752+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147482623
2026-01-22T21:26:57.753+09:00  INFO 60684 --- [ionShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown        : Commencing graceful shutdown. Waiting for active requests to complete
2026-01-22T21:26:58.418+09:00  INFO 60684 --- [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown        : Graceful shutdown complete

2026-01-22T21:26:58.418+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 2147481599
2026-01-22T21:26:58.418+09:00 DEBUG 60684 --- [tomcat-shutdown] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerGracefulShutdown' completed its stop procedure
2026-01-22T21:26:58.419+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'webServerStartStop' completed its stop procedure

2026-01-22T21:26:58.419+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase 1073741823
2026-01-22T21:26:58.419+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'taskExecutor1' completed its stop procedure
2026-01-22T21:26:58.419+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'taskExecutor2' completed its stop procedure

2026-01-22T21:26:58.436+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Stopping beans in phase -2147483647
2026-01-22T21:26:58.436+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.c.support.DefaultLifecycleProcessor  : Bean 'springBootLoggingLifecycle' completed its stop procedure

2026-01-22T21:26:58.436+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Shutting down ExecutorService 'taskExecutor2'
2026-01-22T21:26:58.622+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 2초 경과
2026-01-22T21:26:58.726+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 3초 경과
...
2026-01-22T21:27:11.812+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 16초 경과
2026-01-22T21:27:12.729+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 16초 경과
2026-01-22T21:27:12.820+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 17초 경과
2026-01-22T21:27:13.448+09:00  WARN 60684 --- [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Timed out while waiting for executor 'taskExecutor2' to terminate
2026-01-22T21:27:13.448+09:00 DEBUG 60684 --- [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Shutting down ExecutorService 'taskExecutor1'
2026-01-22T21:27:13.734+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 17초 경과
2026-01-22T21:27:13.825+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 18초 경과
...
2026-01-22T21:27:26.849+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 30초 경과
2026-01-22T21:27:26.849+09:00  INFO 60684 --- [       Async2-1] p.shutdown.config.TestController         : 비동기 작업 완료!
2026-01-22T21:27:26.926+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 31초 경과
2026-01-22T21:27:27.942+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 32초 경과
2026-01-22T21:27:28.944+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 33초 경과
...
2026-01-22T21:27:41.009+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 45초 경과
2026-01-22T21:27:42.021+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 46초 경과
2026-01-22T21:27:43.027+09:00  INFO 60684 --- [       Async1-1] p.shutdown.config.TestController         : 비동기 작업 진행 중: 47초 경과
2026-01-22T21:27:43.459+09:00  WARN 60684 --- [ionShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Timed out while waiting for executor 'taskExecutor1' to terminate

4.3 왜 쓰레드 풀 2번은 30초 작업을 완료할 수 있었을까?

왜 비동기 쓰레드 풀 2번은 작업 기다리기까지 15초니까 실제 작업을 완료하지 못하고 종료될 것 같은데, 어떻게 작업을 완료할 수 있었을까요?

이는 Spring이 쓰레드 풀을 우아한 종료를 위해 기능을 확장했기 때문입니다.(Java의 ThreadPoolExecutor 를 Spring 의 ThreadPoolTaskExecutor 로 확장)

4.4 Spring의 Java 쓰레드 풀 확장 메커니즘

Shutdown 훅에 의해 ThreadPoolTaskExecutor의 shutdown이 호출되면 우아한 종료를 true로 설정했을 시, Java 쓰레드 풀 종료 방식인 ThreadPoolExecutor 구현체에 맞춰 이미 제출된 작업들은 실행되지만 새로운 작업은 받지 않는 종료를 시작합니다. (여기 까지는 Java의 ThreadPoolExecutor 기능입니다.) 하지만, Spring 은 쓰레드 풀의 shutdown 을 끝마치고 추가로 awaitTerminationIfNecessary() 를 호출하게 됩니다. 메서드 명만 봐도 알 수 있듯이 "쓰레드 풀이 필요한 경우 종료를 기다립니다"입니다.

이때 설정된 시간(15초 또는 30초) 동안 기다리게 되고, 만약 그 시간 내에 작업을 다 못 끝내면 WARN 레벨의 로그만 노출하고 강제 종료하지 않는 것을 볼 수 있습니다.

여기서 핵심은 "강제 종료하지 않는다"는 점입니다. 쓰레드 풀 2의 shutdown hook이 호출되어 15초 동안 기다렸지만 작업이 완료되지 않았습니다. 이때 Spring은 쓰레드 풀 2를 강제로 종료하지 않고 WARN 로그만 남긴 채 다음 phase로 넘어갑니다. 그리고, 쓰레드 풀 1의 종료 phase가 시작되고 30초 동안 기다리는 동안, 쓰레드 풀 2의 작업도 함께 계속 실행하는 것입니다. 쓰레드 풀2를 기다리는 동안 1도 종료할 필요 없이 같이 실행하는 것입니다.

결과적으로 쓰레드 풀 2는 자신에게 할당된 15초를 넘어 쓰레드 풀 1이 종료를 기다리는 30초 동안 추가로 작업을 수행할 수 있게 되어, 총 30초 소요 작업을 완료할 수 있었던 것입니다. 정리하면, Spring 생명주기에 맞춰 쓰레드 풀의 작업이 최대한 처리될 수 있게 해주고 있습니다. 각 쓰레드 풀은 자신에게 설정된 시간만큼 기다리지만, 그 시간이 지났다고 해서 강제로 작업을 중단하지 않고, 다른 phase가 종료되기를 기다리는 동안 계속해서 작업을 처리할 수 있는 여유를 주는 것입니다.

그래서, 쓰레드 풀2 의 shutdown hook 이 호출되었지만 쓰레드 풀1의 우아한 종료 시간을 기다리기 때문에 스프링이 쓰레드 풀2 도 그냥 기다리는 동안만 일단 실행 시킬께~ 하지만, Warn 레벨 로그를 통해 작업이 다 완료되진 않을 수 있어.라고 타임아웃 경고를 WARN 로그로 주는 것입니다.

그래서 우리는 스프링에서 쓰레드 풀을 빈으로 등록할 때, 스프링이 쓰레드 풀의 생명주기를 애플리케이션 컨텍스트에 맞춰 관리할 수 있게 ThreadPoolExecutor가 아닌 ThreadPoolTaskExecutor를 사용하는 것입니다. 반면, 우리가 테스트할 때 Executors.newFixedThreadPool()을 사용하는 것은 이 쓰레드 풀이 스프링 생명주기에 맞춰질 필요가 없기 때문입니다.

5. SmartLifecycle과 Phased: Spring의 생명주기 관리 메커니즘

그럼 Spring은 어떻게 생명주기에 맞춰 쓰레드 풀을 종료하게 구현되어 있을까요?

SmartLifecycle(Bean을 관리하는 ApplicationContext가 refresh되거나 shutdown될 때, 특정 순서에 맞게 빈을 시작하거나 종료하도록 지원하는 인터페이스입니다)과 Phased라는 인터페이스를 통해 애플리케이션 컨텍스트가 관리하는 빈들을 순서(Phased)에 따라 효율적으로 정리해줍니다. 참고로 Phased의 getPhase는 int라서 Integer.MIN_VALUE부터 Integer.MAX_VALUE 값을 가지는데, ThreadPoolTaskExecutor와 ThreadPoolTaskScheduler는 Integer.MAX_VALUE / 2의 값을 가집니다.

스프링 컨텍스트가 종료될 때, Phased가 높은 순서(톰캣 쓰레드 풀)부터 종료됨으로써 웹 요청을 막는 것부터 시작하며 천천히 컨텍스트에 등록된 빈들을 Phased가 낮은 순으로 정리하기 시작합니다.

SmartLifecycle을 구현하지 않은 애플리케이션 빈들, 일반 Lifecycle 인터페이스를 구현하거나 @Component 로 등록된 빈들은 Phase를 0으로 처리합니다.

6. 결론

7.1 timeout-per-shutdown-phase의 정확한 의미

직역하자면 "각 Phase를 shutdown 할 때마다 10초의 타임아웃"이라는 얘기입니다.

그리고, 애플리케이션을 종료할 때는 Phase 값이 큰 Bean 부터 종료하기 시작합니다.

Phase 2147482623 (Tomcat):
→ stop() 호출
→ 최대 10초 대기
→ 10초 지나면 다음 Phase로

Phase 1073741823 (TaskExecutor들):
→ stop() 호출
→ 최대 10초 대기
→ 10초 지나면 다음 Phase로

Phase 0:
→ stop() 호출
→ 최대 10초 대기

7.2 import(패키지)의 중요성

자, ThreadPoolExecutor, Executor, ExecutorService의 import는 java입니다. ThreadPoolTaskExecutor, ThreadPoolTaskScheduler의 패키지는 spring입니다.

이렇게 사소하게 패키지만 나뉘게 되지만 그에 따라 동작하는 것은 다르다는 것을 기억하며, "어? 비슷한 기능을 가진 클래스가 있는데 Spring은 무슨 이유로 확장한 거지? 어떤 기능이 더 있는 거지?"를 생각하는 계기가 됐으면 좋겠습니다.

7.3 ThreadPoolTaskExecutor의 추가 기능

이외에도 ThreadPoolTaskExecutor는 빈이 등록될 때 Core 수만큼 쓰레드를 미리 만들어 놓는 설정, Max 쓰레드뿐 아니라 Core 쓰레드도 keep-alive 시간을 줄 수 있는 설정 등 다양하니 찾아보는 것도 도움이 될 것 같습니다.

7.4 작업의 원자성을 보장하는 TransactionalOutbox 패턴

마지막으로, 그럼 우리가 애플리케이션을 종료할 때 모든 작업을 깔끔하게 끝내야만 한다면, 작업이 유실되어야 하지 않아야 한다면 그 작업이 얼마나 걸릴지 예측하고 계산해서 우아한 종료의 시간을 설정하면 될까요?

차라리 DB 나 메시지 큐 같은 미들웨어에 먼저 저장편이 나아 보입니다. 메시지 큐 같은 미들웨어에 저장하려면 TransactionalOutbox 패턴을 통해 at least once 방식으로 정합성을 맞추는 것은 덤이구요.

참고자료

Graceful Shutdown

SmartLifeCycle

추가로 읽어볼만한 자료

톰캣의 우아한 종료 지원 과정

저작자표시 (새창열림)

'Spring' 카테고리의 다른 글

Cloud OpenFeign 의 재시도는 언제 동작할까? Retryer.Default 동작 원리와 테스트 (0)	2025.11.12
복잡함 대신 단순함 추구하기 - RestTemplate 확장 되돌리기 (3)	2025.08.13
Spring AOP 로 사용자가 가진 권한에 따라 특정 메뉴(기능) 접속 제한하기 (3)	2025.08.11
MultipartFile 의 transferTo 이후 getBytes 호출 시 NoSuchFileException 발생 원인 소개 (2)	2025.07.26
OpenFeign 에서 ISO-8601 날짜 포맷을 위해 FeignFormatterRegistrar 를 등록하는 이유 (5)	2025.05.10

It`s all your duck🍀

Spring Boot의 Graceful Shutdown 어디까지 알고있나요? (SmartLifeCycle, Phased 와 함께 timeout-per-shutdown-phase 오해 바로잡기)

1. 우아한 종료 테스트 환경 설정

1.1 application.yml 설정

1.2 비동기 쓰레드 풀 설정

2. 첫 번째 문제: 우아한 종료는 비동기 작업을 기다려줄까?

2.1 실험 코드

2.2 결과는 무엇일까?

2.3 로그 분석

2.4 timeout-per-shutdown-phase의 진짜 의미

2.5 Phase 별 종료 메커니즘

3. 두 번째 문제: 쓰레드 풀에 우아한 종료를 추가하면?

3.1 쓰레드 풀 우아한 종료 설정

3.2 결과는 어떻게 될까?

3.3 왜 이렇게 동작할까?

4. 세 번째 문제: 여러 쓰레드 풀의 우아한 종료

4.1 복수 쓰레드 풀 설정

4.2 결과는?

4.3 왜 쓰레드 풀 2번은 30초 작업을 완료할 수 있었을까?

4.4 Spring의 Java 쓰레드 풀 확장 메커니즘

5. SmartLifecycle과 Phased: Spring의 생명주기 관리 메커니즘

6. 결론

7.1 timeout-per-shutdown-phase의 정확한 의미

7.3 ThreadPoolTaskExecutor의 추가 기능

7.4 작업의 원자성을 보장하는 TransactionalOutbox 패턴

'Spring' 카테고리의 다른 글

티스토리툴바

Spring Boot의 Graceful Shutdown 어디까지 알고있나요? (SmartLifeCycle, Phased 와 함께 timeout-per-shutdown-phase 오해 바로잡기)

1. 우아한 종료 테스트 환경 설정

1.1 application.yml 설정

1.2 비동기 쓰레드 풀 설정

2. 첫 번째 문제: 우아한 종료는 비동기 작업을 기다려줄까?

2.1 실험 코드

2.2 결과는 무엇일까?

2.3 로그 분석

2.4 timeout-per-shutdown-phase의 진짜 의미

2.5 Phase 별 종료 메커니즘

3. 두 번째 문제: 쓰레드 풀에 우아한 종료를 추가하면?

3.1 쓰레드 풀 우아한 종료 설정

3.2 결과는 어떻게 될까?

3.3 왜 이렇게 동작할까?

4. 세 번째 문제: 여러 쓰레드 풀의 우아한 종료

4.1 복수 쓰레드 풀 설정

4.2 결과는?

4.3 왜 쓰레드 풀 2번은 30초 작업을 완료할 수 있었을까?

4.4 Spring의 Java 쓰레드 풀 확장 메커니즘

5. SmartLifecycle과 Phased: Spring의 생명주기 관리 메커니즘

6. 결론

7.1 timeout-per-shutdown-phase의 정확한 의미

7.3 ThreadPoolTaskExecutor의 추가 기능

7.4 작업의 원자성을 보장하는 TransactionalOutbox 패턴

'Spring' 카테고리의 다른 글

'Spring' Related Articles

티스토리툴바